Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(projections): api, model routing, structured output (#4461)

teod93de7d4fade
diff --git a/js/app/packages/app/component/debug/ProjectionPlayground.tsx b/js/app/packages/app/component/debug/ProjectionPlayground.tsx
new file mode 100644
index 0000000000..5a7ad63280
--- /dev/null
+++ b/js/app/packages/app/component/debug/ProjectionPlayground.tsx
@@ -0,0 +1,329 @@
+import { createAIProjection } from '@queries/ai/projection';
+import type { Expiry } from '@service-cognition/generated/schemas/expiry';
+import type { RefreshCadence } from '@service-cognition/generated/schemas/refreshCadence';
+import { createConnectionWebsocketEffect } from '@service-connection/websocket';
+import { Button, InlineCheckbox, SegmentedControl } from '@ui';
+import { createMemo, createSignal, For, Show } from 'solid-js';
+import { z } from 'zod';
+
+/** Demo schema for the structured-output variation. Non-strict server-side, so
+ * the shape just needs to be representable as plain JSON schema. */
+const DEMO_SCHEMA = z.object({
+ headline: z.string(),
+ items: z.array(z.object({ title: z.string(), detail: z.string() })),
+ confidence: z.number(),
+});
+
+const DEFAULT_PROMPT =
+ 'Look at my three most recent unread items and produce a short brief: what they are and why (or why not) they need my attention.';
+
+type OutputMode = 'text' | 'structured';
+type ModelChoice = 'default' | 'fast' | 'cerebras' | 'custom';
+
+const MODEL_IDS: Record<Exclude<ModelChoice, 'custom'>, string | undefined> = {
+ default: undefined,
+ fast: 'anthropic/claude-haiku-4-5',
+ cerebras: 'cerebras/llama-3.3-70b',
+};
+
+const AI_PROJECTION_UPDATED_MESSAGE_TYPE = 'ai_projection_updated';
+
+/**
+ * Dev playground for AI projections (`createAIProjection`).
+ *
+ * Variations to poke at:
+ * - text vs structured output (zod schema -> non-strict JSON generation)
+ * - model routing (default / fast / cerebras / custom `provider/model` id)
+ * - `await` inline generation vs fire-and-forget + gateway push
+ * - reactive `enabled` (the query does nothing until enabled)
+ * - `refresh()` re-trigger over a cached result
+ *
+ * Requires the `read:professional_features` permission (the endpoint is
+ * premium-gated). Changing prompt/schema/model revises the projection
+ * server-side and regenerates on the next request.
+ */
+export default function ProjectionPlayground() {
+ const [id, setId] = createSignal('playground/projection-demo');
+ const [prompt, setPrompt] = createSignal(DEFAULT_PROMPT);
+ const [outputMode, setOutputMode] = createSignal<OutputMode>('text');
+ const [modelChoice, setModelChoice] = createSignal<ModelChoice>('default');
+ const [customModel, setCustomModel] = createSignal('cerebras/llama-3.3-70b');
+ const [awaitGeneration, setAwaitGeneration] = createSignal(true);
+ const [enabled, setEnabled] = createSignal(false);
+ const [cadence, setCadence] = createSignal<RefreshCadence>('low');
+ const [expiry, setExpiry] = createSignal<Expiry>('day');
+
+ const model = () =>
+ modelChoice() === 'custom'
+ ? customModel() || undefined
+ : MODEL_IDS[modelChoice() as Exclude<ModelChoice, 'custom'>];
+
+ const projection = createAIProjection(() => ({
+ id: id(),
+ prompt: prompt(),
+ schema: outputMode() === 'structured' ? DEMO_SCHEMA : undefined,
+ model: model(),
+ awaitGeneration: awaitGeneration(),
+ refreshCadence: cadence(),
+ expiry: expiry(),
+ enabled: enabled(),
+ }));
+
+ // Raw gateway frames, so the push path is visible even when the cache
+ // update is subtle (e.g. same data regenerated).
+ const [events, setEvents] = createSignal<string[]>([]);
+ createConnectionWebsocketEffect((message) => {
+ if (message.type !== AI_PROJECTION_UPDATED_MESSAGE_TYPE) return;
+ const stamp = new Date().toLocaleTimeString();
+ setEvents((prev) => [`${stamp} ${message.data}`, ...prev].slice(0, 20));
+ });
+
+ const dataDisplay = createMemo(() => {
+ const value = projection.data();
+ if (value === undefined) return undefined;
+ return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+ });
+
+ const timeLabel = (timestamp: string | null | undefined) =>
+ timestamp ? new Date(timestamp).toLocaleTimeString() : undefined;
+ const generatedAtLabel = () => timeLabel(projection.query.data?.generated_at);
+ const staleAtLabel = () => timeLabel(projection.query.data?.stale_at);
+
+ const [busy, setBusy] = createSignal(false);
+ const regenerate = async () => {
+ setBusy(true);
+ try {
+ await projection.refresh();
+ } catch (error) {
+ console.error('projection regenerate failed', error);
+ } finally {
+ setBusy(false);
+ }
+ };
+
+ return (
+ <div class="flex h-full flex-col bg-bg text-ink">
+ <header class="flex h-10 shrink-0 items-center border-edge-muted border-b px-4">
+ <div class="text-sm font-medium">AI Projection Playground</div>
+ <div class="ml-auto text-ink-muted text-xs">
+ POST /ai-projections · gateway `ai_projection_updated`
+ </div>
+ </header>
+ <div class="grid min-h-0 flex-1 grid-cols-[380px_1fr] overflow-hidden">
+ <aside class="flex min-h-0 flex-col gap-4 overflow-auto border-edge-muted border-r p-4">
+ <section class="space-y-2">
+ <div class="text-sm font-medium">Projection id</div>
+ <input
+ class="w-full rounded-sm border border-edge-muted bg-surface p-1.5 text-sm outline-none focus:border-accent"
+ value={id()}
+ onInput={(event) => setId(event.currentTarget.value)}
+ />
+ <div class="text-ink-muted text-xs">
+ The cache key. Same id + same prompt/model/schema = cached result;
+ changing any of those revises the projection and regenerates.
+ </div>
+ </section>
+
+ <section class="space-y-2">
+ <div class="text-sm font-medium">Prompt</div>
+ <textarea
+ class="min-h-24 w-full rounded-sm border border-edge-muted bg-surface p-1.5 text-sm outline-none focus:border-accent"
+ value={prompt()}
+ onInput={(event) => setPrompt(event.currentTarget.value)}
+ />
+ </section>
+
+ <section class="space-y-2">
+ <div class="text-sm font-medium">Output</div>
+ <SegmentedControl
+ class="w-full"
+ size="sm"
+ value={outputMode()}
+ options={[
+ { value: 'text', label: 'Free text' },
+ { value: 'structured', label: 'Structured (zod)' },
+ ]}
+ onChange={(value) => setOutputMode(value)}
+ />
+ <Show when={outputMode() === 'structured'}>
+ <pre class="overflow-auto rounded-sm border border-edge-muted bg-surface p-2 text-xs">
+ {'{ headline, items: [{ title, detail }], confidence }'}
+ </pre>
+ </Show>
+ </section>
+
+ <section class="space-y-2">
+ <div class="text-sm font-medium">Model</div>
+ <SegmentedControl
+ class="w-full"
+ size="sm"
+ value={modelChoice()}
+ options={[
+ { value: 'default', label: 'Default' },
+ { value: 'fast', label: 'Haiku' },
+ { value: 'cerebras', label: 'Cerebras' },
+ { value: 'custom', label: 'Custom' },
+ ]}
+ onChange={(value) => setModelChoice(value)}
+ />
+ <Show when={modelChoice() === 'custom'}>
+ <input
+ class="w-full rounded-sm border border-edge-muted bg-surface p-1.5 text-sm outline-none focus:border-accent"
+ placeholder="provider/model, e.g. cerebras/llama-3.3-70b"
+ value={customModel()}
+ onInput={(event) => setCustomModel(event.currentTarget.value)}
+ />
+ </Show>
+ <div class="text-ink-muted text-xs">
+ Unroutable ids silently fall back to the server default.
+ </div>
+ </section>
+
+ <section class="space-y-2">
+ <div class="text-sm font-medium">Request behavior</div>
+ <button
+ type="button"
+ class="flex w-full items-center gap-2 text-left text-sm hover:bg-hover"
+ onClick={() => setAwaitGeneration((prev) => !prev)}
+ >
+ <InlineCheckbox checked={awaitGeneration()} />
+ <span>
+ await — generate inline and return the finished result
+ </span>
+ </button>
+ <button
+ type="button"
+ class="flex w-full items-center gap-2 text-left text-sm hover:bg-hover"
+ onClick={() => setEnabled((prev) => !prev)}
+ >
+ <InlineCheckbox checked={enabled()} />
+ <span>enabled — reactive; off = the query never fires</span>
+ </button>
+ <div class="grid grid-cols-2 gap-2">
+ <select
+ class="w-full rounded-sm border border-edge-muted bg-surface p-1.5 text-sm outline-none focus:border-accent"
+ value={cadence()}
+ onChange={(event) =>
+ setCadence(event.currentTarget.value as RefreshCadence)
+ }
+ >
+ <option value="high">cadence: high</option>
+ <option value="medium">cadence: medium</option>
+ <option value="low">cadence: low</option>
+ </select>
+ <select
+ class="w-full rounded-sm border border-edge-muted bg-surface p-1.5 text-sm outline-none focus:border-accent"
+ value={expiry()}
+ onChange={(event) =>
+ setExpiry(event.currentTarget.value as Expiry)
+ }
+ >
+ <option value="day">expiry: day</option>
+ <option value="week">expiry: week</option>
+ <option value="month">expiry: month</option>
+ </select>
+ </div>
+ </section>
+
+ <section class="flex gap-2">
+ <Button
+ variant="base"
+ size="sm"
+ disabled={projection.query.isFetching}
+ onClick={() => projection.query.refetch()}
+ >
+ Send request
+ </Button>
+ <Button
+ variant="cta"
+ size="sm"
+ disabled={busy()}
+ onClick={() => void regenerate()}
+ >
+ Force regenerate
+ </Button>
+ </section>
+ </aside>
+
+ <main class="flex min-h-0 flex-col gap-4 overflow-auto p-4">
+ <section class="flex items-center gap-3 text-sm">
+ <span class="rounded-sm border border-edge-muted bg-surface px-2 py-0.5">
+ status: {projection.status() ?? '—'}
+ </span>
+ <span class="rounded-sm border border-edge-muted bg-surface px-2 py-0.5">
+ generating: {String(projection.isGenerating())}
+ </span>
+ <span class="rounded-sm border border-edge-muted bg-surface px-2 py-0.5">
+ fetching: {String(projection.query.isFetching)}
+ </span>
+ <Show when={generatedAtLabel()}>
+ <span class="text-ink-muted text-xs">
+ generated {generatedAtLabel()}
+ </span>
+ </Show>
+ <Show when={staleAtLabel()}>
+ <span class="text-ink-muted text-xs">stale {staleAtLabel()}</span>
+ </Show>
+ </section>
+
+ <Show when={projection.error()}>
+ <section class="rounded-sm border border-edge-muted bg-surface p-3 text-danger text-sm">
+ {projection.error()}
+ </section>
+ </Show>
+
+ <section class="space-y-2">
+ <div class="text-sm font-medium">Result</div>
+ <Show
+ when={dataDisplay() !== undefined}
+ fallback={
+ <div class="rounded-sm border border-edge-muted border-dashed p-4 text-ink-muted text-sm">
+ No result yet. Enable the query (or hit “Send request”) to
+ upsert the projection; with `await` off, watch the gateway
+ event land below.
+ </div>
+ }
+ >
+ <pre class="whitespace-pre-wrap rounded-sm border border-edge-muted bg-surface p-3 text-sm">
+ {dataDisplay()}
+ </pre>
+ </Show>
+ </section>
+
+ <section class="space-y-2">
+ <div class="text-sm font-medium">Raw response</div>
+ <pre class="overflow-auto rounded-sm border border-edge-muted bg-surface p-3 text-xs">
+ {projection.query.data
+ ? JSON.stringify(projection.query.data, null, 2)
+ : '—'}
+ </pre>
+ </section>
+
+ <section class="space-y-2">
+ <div class="text-sm font-medium">
+ Gateway events ({events().length})
+ </div>
+ <Show
+ when={events().length > 0}
+ fallback={
+ <div class="text-ink-muted text-sm">
+ No `ai_projection_updated` frames received yet.
+ </div>
+ }
+ >
+ <div class="space-y-1">
+ <For each={events()}>
+ {(event) => (
+ <pre class="overflow-auto rounded-sm border border-edge-muted bg-surface p-2 text-xs">
+ {event}
+ </pre>
+ )}
+ </For>
+ </div>
+ </Show>
+ </section>
+ </main>
+ </div>
+ </div>
+ );
+}
diff --git a/js/app/packages/app/component/split-layout/componentRegistry.tsx b/js/app/packages/app/component/split-layout/componentRegistry.tsx
index b0a47ef3e4..279a36c4cf 100644
--- a/js/app/packages/app/component/split-layout/componentRegistry.tsx
+++ b/js/app/packages/app/component/split-layout/componentRegistry.tsx
@@ -458,6 +458,11 @@ if (DEV_MODE_ENV) {
)
);
+ registerComponent(
+ 'projection-playground',
+ withAuth(lazy(() => import('@app/component/debug/ProjectionPlayground')))
+ );
+
// NOTE (seamus) : putting pixel icons on dev/staging for aidan
registerComponent(
'pixel-icon',
diff --git a/js/app/packages/queries/ai/projection.ts b/js/app/packages/queries/ai/projection.ts
new file mode 100644
index 0000000000..cc8929fb37
--- /dev/null
+++ b/js/app/packages/queries/ai/projection.ts
@@ -0,0 +1,238 @@
+import { throwOnErr } from '@core/util/result';
+import { cognitionApiServiceClient } from '@service-cognition/client';
+import type { Expiry } from '@service-cognition/generated/schemas/expiry';
+import type { ProjectionStateResponse } from '@service-cognition/generated/schemas/projectionStateResponse';
+import type { ProjectionStatus } from '@service-cognition/generated/schemas/projectionStatus';
+import type { RefreshCadence } from '@service-cognition/generated/schemas/refreshCadence';
+import type { TargetType } from '@service-cognition/generated/schemas/targetType';
+import type { UpsertProjectionRequest } from '@service-cognition/generated/schemas/upsertProjectionRequest';
+import { createConnectionWebsocketEffect } from '@service-connection/websocket';
+import { useQuery } from '@tanstack/solid-query';
+import { type Accessor, createMemo } from 'solid-js';
+import { z } from 'zod';
+import { queryClient } from '../client';
+
+const AI_PROJECTION_UPDATED_MESSAGE_TYPE = 'ai_projection_updated';
+
+/** Gateway push sent when a projection materialization finishes (or errors).
+ * Mirrors `ProjectionStateResponse` plus the routing discriminators. */
+type ProjectionUpdatedMessage = ProjectionStateResponse & {
+ type: typeof AI_PROJECTION_UPDATED_MESSAGE_TYPE;
+ target_type?: TargetType;
+};
+
+export const aiProjectionQueryKey = (id: string, targetType: TargetType) =>
+ ['ai-projection', targetType, id] as const;
+
+const GENERATING_STATUSES: ProjectionStatus[] = [
+ 'cold',
+ 'loading',
+ 'refreshing',
+];
+
+/** Gateway pushes only land while a subscriber is mounted, so refetch fairly
+ * eagerly on remount (the POST is cheap: it returns the server-side cache and
+ * bumps the projection's keepalive). */
+const PROJECTION_STALE_TIME = 30 * 1000;
+
+export type CreateAIProjectionOptions<Schema extends z.ZodType = z.ZodType> = {
+ /** Frontend-defined projection id (e.g. `notification_important_widget`). */
+ id: string;
+ /** The prompt materialized by the projection. Changing the prompt (or
+ * `schema`/`model`) revises the projection server-side and regenerates. */
+ prompt: string;
+ /** Zod schema for structured output. When set, the projection result is
+ * generated as schema-conforming JSON (prompted, non-strict — works across
+ * providers) and `data` returns the parsed, validated object. */
+ schema?: Schema;
+ /** Optional `provider/model` id (e.g. `cerebras/llama-3.3-70b`,
+ * `anthropic/claude-haiku-4-5`). Defaults to the server's default model. */
+ model?: string;
+ /** Whether the projection targets the user or their team. Default `user`. */
+ targetType?: TargetType;
+ /** Background refresh cadence. Default `medium`. */
+ refreshCadence?: RefreshCadence;
+ /** How long the projection stays alive without being requested. Default `week`. */
+ expiry?: Expiry;
+ /** When true, a request that needs generation (cold cache or refresh)
+ * generates inline and resolves with the finished result instead of
+ * returning immediately and relying on the gateway push. Pair with a fast
+ * `model` for interactive use. */
+ awaitGeneration?: boolean;
+ /** Reactive enabled flag, like tanstack query's. Default true. */
+ enabled?: boolean;
+};
+
+/** Converts a zod schema into the non-strict JSON schema sent to the server. */
+function toOutputSchema(schema: z.ZodType): Record<string, unknown> {
+ return z.toJSONSchema(schema, {
+ target: 'draft-07',
+ unrepresentable: 'throw',
+ cycles: 'throw',
+ reused: 'inline',
+ }) as Record<string, unknown>;
+}
+
+function toProjectionState(
+ message: ProjectionUpdatedMessage
+): ProjectionStateResponse {
+ return {
+ id: message.id,
+ status: message.status,
+ data: message.data,
+ error: message.error,
+ generated_at: message.generated_at,
+ stale_at: message.stale_at,
+ };
+}
+
+/**
+ * Materialized AI projection query, inspired by the Vercel AI SDK's
+ * `useObject` but backed by the server-side projection cache.
+ *
+ * - Upserting is reading: the query POSTs `/ai-projections`, which returns the
+ * cached result when warm and otherwise kicks off (or, with
+ * `awaitGeneration`, awaits) materialization.
+ * - Completion updates arrive over the connection gateway
+ * (`ai_projection_updated`) and are written straight into the query cache —
+ * no polling.
+ * - `refresh()` re-triggers generation even when a cached result exists; the
+ * stale data stays visible (`status: 'refreshing'`) until the new result
+ * lands.
+ *
+ * @example
+ * ```tsx
+ * const projection = createAIProjection(() => ({
+ * id: 'inbox/important',
+ * prompt: 'Summarize my most important unread emails.',
+ * schema: z.object({ items: z.array(z.string()) }),
+ * model: 'cerebras/llama-3.3-70b',
+ * awaitGeneration: true,
+ * enabled: inboxOpen(),
+ * }));
+ *
+ * projection.data()?.items;
+ * <Button onClick={() => projection.refresh()} />
+ * ```
+ */
+export function createAIProjection<Schema extends z.ZodType>(
+ options: Accessor<CreateAIProjectionOptions<Schema>>
+) {
+ const targetType = () => options().targetType ?? 'user';
+ const queryKey = () => aiProjectionQueryKey(options().id, targetType());
+
+ const buildRequest = (
+ overrides?: Partial<UpsertProjectionRequest>
+ ): UpsertProjectionRequest => {
+ const opts = options();
+ return {
+ id: opts.id,
+ prompt: opts.prompt,
+ target_type: targetType(),
+ refresh_cadence: opts.refreshCadence ?? 'medium',
+ expiry: opts.expiry ?? 'week',
+ ...(opts.model === undefined ? {} : { model: opts.model }),
+ ...(opts.schema === undefined
+ ? {}
+ : { output_schema: toOutputSchema(opts.schema) }),
+ await: opts.awaitGeneration ?? false,
+ ...overrides,
+ };
+ };
+
+ const query = useQuery(() => ({
+ queryKey: queryKey(),
+ queryFn: async () =>
+ throwOnErr(
+ async () =>
+ await cognitionApiServiceClient.upsertAiProjection(buildRequest())
+ ),
+ enabled:
+ (options().enabled ?? true) && !!options().id && !!options().prompt,
+ staleTime: PROJECTION_STALE_TIME,
+ }));
+
+ // Materializations finish out-of-band (SQS worker or refresh sweeps); the
+ // gateway pushes the final state, which we write straight into the cache.
+ createConnectionWebsocketEffect((message) => {
+ if (message.type !== AI_PROJECTION_UPDATED_MESSAGE_TYPE) return;
+
+ let update: ProjectionUpdatedMessage;
+ try {
+ update = JSON.parse(message.data);
+ } catch {
+ console.error('unparsable ai projection update payload', message);
+ return;
+ }
+
+ if (update.id !== options().id) return;
+ if ((update.target_type ?? 'user') !== targetType()) return;
+
+ queryClient.setQueryData(queryKey(), toProjectionState(update));
+ });
+
+ /** Re-triggers generation even when a cached result exists. Resolves with
+ * the post-trigger state (`refreshing`, or the finished result when
+ * `awaitGeneration` is set). */
+ const refresh = async (): Promise<ProjectionStateResponse> => {
+ const key = queryKey();
+ const state = await throwOnErr(
+ async () =>
+ await cognitionApiServiceClient.upsertAiProjection(
+ buildRequest({ regenerate: true })
+ )
+ );
+ queryClient.setQueryData(key, state);
+ return state;
+ };
+
+ /** The projection result: schema-parsed object when a schema is set,
+ * otherwise the raw text. Undefined until a result exists (stale results
+ * remain visible while refreshing). */
+ const data = createMemo((): z.infer<Schema> | string | undefined => {
+ const raw = query.data?.data;
+ if (raw === null || raw === undefined) return undefined;
+
+ const schema = options().schema;
+ if (!schema) return raw;
+
+ let json: unknown;
+ try {
+ json = JSON.parse(raw);
+ } catch (error) {
+ console.error('ai projection result is not valid JSON', error);
+ return undefined;
+ }
+
+ const parsed = schema.safeParse(json);
+ if (!parsed.success) {
+ console.error(
+ 'ai projection result failed schema validation',
+ parsed.error
+ );
+ return undefined;
+ }
+ return parsed.data;
+ });
+
+ const status = () => query.data?.status;
+
+ return {
+ /** Parsed result (see above). */
+ data,
+ /** The projection lifecycle status (`cold`/`loading`/`ready`/...). */
+ status,
+ /** True while the initial fetch or a server-side generation is in flight. */
+ isGenerating: () => {
+ if (query.isLoading) return true;
+ const current = status();
+ return current !== undefined && GENERATING_STATUSES.includes(current);
+ },
+ /** Materialization error (from the projection) or request error message. */
+ error: () => query.data?.error ?? query.error?.message ?? undefined,
+ /** Re-trigger generation, keeping stale data visible meanwhile. */
+ refresh,
+ /** The underlying tanstack query, for advanced use. */
+ query,
+ };
+}
diff --git a/js/app/packages/service-clients/service-cognition/client.ts b/js/app/packages/service-clients/service-cognition/client.ts
index f6e3095ed5..0383e72bf9 100644
--- a/js/app/packages/service-clients/service-cognition/client.ts
+++ b/js/app/packages/service-clients/service-cognition/client.ts
@@ -20,6 +20,7 @@ import type { GetChatResponse } from './generated/schemas/getChatResponse';
import type { GetChatsForAttachmentResponse } from './generated/schemas/getChatsForAttachmentResponse';
import type { HttpSendChatMessageRequest } from './generated/schemas/httpSendChatMessageRequest';
import type { PatchChatRequest } from './generated/schemas/patchChatRequest';
+import type { ProjectionStateResponse } from './generated/schemas/projectionStateResponse';
import type { SendChatMessageResponse } from './generated/schemas/sendChatMessageResponse';
import type { ServerResponse } from './generated/schemas/serverResponse';
import type { StartAuthRequest } from './generated/schemas/startAuthRequest';
@@ -30,6 +31,7 @@ import type { StringIDResponse } from './generated/schemas/stringIDResponse';
import type { StructuredCompletionRequest } from './generated/schemas/structuredCompletionRequest';
import type { StructuredCompletionResponse } from './generated/schemas/structuredCompletionResponse';
import type { UpdateServerRequest } from './generated/schemas/updateServerRequest';
+import type { UpsertProjectionRequest } from './generated/schemas/upsertProjectionRequest';
import type * as toolTypes from './generated/tools/tool.ts';
type ToolCallArgs = {
@@ -365,6 +367,19 @@ export const cognitionApiServiceClient = {
})
).map((result) => result);
},
+
+ /** Gets or creates an AI projection and the requesting user's instance of
+ * it, triggering (or, with `await: true`, awaiting) materialization when
+ * needed. Completion updates are also pushed over the connection gateway as
+ * `ai_projection_updated` messages. */
+ async upsertAiProjection(args: UpsertProjectionRequest) {
+ return (
+ await dcsFetch<ProjectionStateResponse>(`/ai-projections`, {
+ method: 'POST',
+ body: JSON.stringify(args),
+ })
+ ).map((result) => result);
+ },
};
export async function generateTitle(text: string): Promise<string | undefined> {
diff --git a/js/app/packages/service-clients/service-cognition/generated/client.ts b/js/app/packages/service-clients/service-cognition/generated/client.ts
index b0d1189570..d2fdbe8da2 100644
--- a/js/app/packages/service-clients/service-cognition/generated/client.ts
+++ b/js/app/packages/service-clients/service-cognition/generated/client.ts
@@ -169,7 +169,8 @@ export const getUsageHandler = async (
};
/**
- * @summary Gets or creates an ai projection and the requesting user's cold instance.
+ * @summary Gets or creates an ai projection and the requesting user's instance,
+triggering (or awaiting) materialization when needed.
*/
export type upsertAiProjectionResponse200 = {
data: ProjectionStateResponse;
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/index.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/index.ts
index 38dd6490a3..ebef92894d 100644
--- a/js/app/packages/service-clients/service-cognition/generated/schemas/index.ts
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/index.ts
@@ -134,6 +134,7 @@ export * from './patchChatRequestSharePermission';
export * from './price';
export * from './projectionStateResponse';
export * from './projectionStateResponseData';
+export * from './projectionStateResponseError';
export * from './projectionStateResponseGeneratedAt';
export * from './projectionStateResponseStaleAt';
export * from './projectionStatus';
@@ -186,6 +187,9 @@ export * from './updateSharePermissionRequestV2PublicAccessLevel';
export * from './updateToolCallRequest';
export * from './updateToolResponseRequest';
export * from './upsertProjectionRequest';
+export * from './upsertProjectionRequestModel';
+export * from './upsertProjectionRequestOutputSchema';
+export * from './upsertProjectionRequestOutputSchemaAnyOf';
export * from './usage';
export * from './usagePrice';
export * from './usageRequest';
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponse.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponse.ts
index 8d96778ffb..2538156607 100644
--- a/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponse.ts
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponse.ts
@@ -5,6 +5,7 @@
* OpenAPI spec version: 1.0.0
*/
import type { ProjectionStateResponseData } from './projectionStateResponseData';
+import type { ProjectionStateResponseError } from './projectionStateResponseError';
import type { ProjectionStateResponseGeneratedAt } from './projectionStateResponseGeneratedAt';
import type { ProjectionStateResponseStaleAt } from './projectionStateResponseStaleAt';
import type { ProjectionStatus } from './projectionStatus';
@@ -13,8 +14,11 @@ import type { ProjectionStatus } from './projectionStatus';
* The current state of a user's projection instance.
*/
export interface ProjectionStateResponse {
- /** The cached result, if any. */
+ /** The cached result, if any. JSON-encoded when the projection defines an
+`output_schema`. */
data?: ProjectionStateResponseData;
+ /** The most recent materialization error, if any. */
+ error?: ProjectionStateResponseError;
/** When the result was generated. */
generated_at?: ProjectionStateResponseGeneratedAt;
/** The projection id. */
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponseData.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponseData.ts
index 352a6dcff8..74d356ccd9 100644
--- a/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponseData.ts
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponseData.ts
@@ -6,6 +6,7 @@
*/
/**
- * The cached result, if any.
+ * The cached result, if any. JSON-encoded when the projection defines an
+`output_schema`.
*/
export type ProjectionStateResponseData = string | null;
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponseError.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponseError.ts
new file mode 100644
index 0000000000..be6060a25b
--- /dev/null
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/projectionStateResponseError.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Document Cognition Service
+ * OpenAPI spec version: 1.0.0
+ */
+
+/**
+ * The most recent materialization error, if any.
+ */
+export type ProjectionStateResponseError = string | null;
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequest.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequest.ts
index 877d8b05a1..0aba076349 100644
--- a/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequest.ts
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequest.ts
@@ -7,20 +7,36 @@
import type { Expiry } from './expiry';
import type { RefreshCadence } from './refreshCadence';
import type { TargetType } from './targetType';
+import type { UpsertProjectionRequestModel } from './upsertProjectionRequestModel';
+import type { UpsertProjectionRequestOutputSchema } from './upsertProjectionRequestOutputSchema';
/**
* Request body for getting or creating an ai projection. The concrete target
id is resolved from the authenticated user, so only the target type is sent.
*/
export interface UpsertProjectionRequest {
+ /** When `true` and generation is needed (cold instance or `regenerate`),
+the server generates inline and responds with the finished result
+instead of returning immediately and pushing an update through the
+connection gateway. */
+ await?: boolean;
/** How long the projection remains active without being requested. */
expiry: Expiry;
/** The frontend-defined projection id (e.g. `notification_important_widget`). */
id: string;
+ /** Optional `provider/model` id used for generation (e.g.
+`cerebras/llama-3.3-70b`). The default model is used when absent. */
+ model?: UpsertProjectionRequestModel;
+ /** Optional JSON schema the generated result must conform to. When set,
+`data` holds the JSON serialization of a conforming value. Enforcement
+is prompted (non-strict), so it works across providers. */
+ output_schema?: UpsertProjectionRequestOutputSchema;
/** The prompt used to materialize the projection. */
prompt: string;
/** How frequently the projection should be regenerated. */
refresh_cadence: RefreshCadence;
+ /** When `true`, regenerate even if a cached result exists. */
+ regenerate?: boolean;
/** Whether the projection is materialized for the requesting user or their team. */
target_type: TargetType;
}
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestModel.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestModel.ts
new file mode 100644
index 0000000000..5d274a2c66
--- /dev/null
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestModel.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Document Cognition Service
+ * OpenAPI spec version: 1.0.0
+ */
+
+/**
+ * Optional `provider/model` id used for generation (e.g.
+`cerebras/llama-3.3-70b`). The default model is used when absent.
+ */
+export type UpsertProjectionRequestModel = string | null;
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestOutputSchema.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestOutputSchema.ts
new file mode 100644
index 0000000000..afd03e91f7
--- /dev/null
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestOutputSchema.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Document Cognition Service
+ * OpenAPI spec version: 1.0.0
+ */
+import type { UpsertProjectionRequestOutputSchemaAnyOf } from './upsertProjectionRequestOutputSchemaAnyOf';
+
+/**
+ * Optional JSON schema the generated result must conform to. When set,
+`data` holds the JSON serialization of a conforming value. Enforcement
+is prompted (non-strict), so it works across providers.
+ */
+export type UpsertProjectionRequestOutputSchema =
+ UpsertProjectionRequestOutputSchemaAnyOf | null;
diff --git a/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestOutputSchemaAnyOf.ts b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestOutputSchemaAnyOf.ts
new file mode 100644
index 0000000000..d6fe8d8df2
--- /dev/null
+++ b/js/app/packages/service-clients/service-cognition/generated/schemas/upsertProjectionRequestOutputSchemaAnyOf.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Document Cognition Service
+ * OpenAPI spec version: 1.0.0
+ */
+
+/**
+ * Optional JSON schema the generated result must conform to. When set,
+`data` holds the JSON serialization of a conforming value. Enforcement
+is prompted (non-strict), so it works across providers.
+ */
+export type UpsertProjectionRequestOutputSchemaAnyOf = {
+ [key: string]: unknown;
+};
diff --git a/js/app/packages/service-clients/service-cognition/openapi.json b/js/app/packages/service-clients/service-cognition/openapi.json
index 0d95a33a12..cf0cf0c108 100644
--- a/js/app/packages/service-clients/service-cognition/openapi.json
+++ b/js/app/packages/service-clients/service-cognition/openapi.json
@@ -115,7 +115,7 @@
"/ai-projections": {
"post": {
"tags": ["ai_projections::inbound::axum_router::upsert_projection"],
- "summary": "Gets or creates an ai projection and the requesting user's cold instance.",
+ "summary": "Gets or creates an ai projection and the requesting user's instance,\ntriggering (or awaiting) materialization when needed.",
"operationId": "upsert_ai_projection",
"requestBody": {
"content": {
@@ -3159,7 +3159,11 @@
"properties": {
"data": {
"type": ["string", "null"],
- "description": "The cached result, if any."
+ "description": "The cached result, if any. JSON-encoded when the projection defines an\n`output_schema`."
+ },
+ "error": {
+ "type": ["string", "null"],
+ "description": "The most recent materialization error, if any."
},
"generated_at": {
"type": ["string", "null"],
@@ -3661,6 +3665,10 @@
"expiry"
],
"properties": {
+ "await": {
+ "type": "boolean",
+ "description": "When `true` and generation is needed (cold instance or `regenerate`),\nthe server generates inline and responds with the finished result\ninstead of returning immediately and pushing an update through the\nconnection gateway."
+ },
"expiry": {
"$ref": "#/components/schemas/Expiry",
"description": "How long the projection remains active without being requested."
@@ -3669,6 +3677,14 @@
"type": "string",
"description": "The frontend-defined projection id (e.g. `notification_important_widget`)."
},
+ "model": {
+ "type": ["string", "null"],
+ "description": "Optional `provider/model` id used for generation (e.g.\n`cerebras/llama-3.3-70b`). The default model is used when absent."
+ },
+ "output_schema": {
+ "type": ["object", "null"],
+ "description": "Optional JSON schema the generated result must conform to. When set,\n`data` holds the JSON serialization of a conforming value. Enforcement\nis prompted (non-strict), so it works across providers."
+ },
"prompt": {
"type": "string",
"description": "The prompt used to materialize the projection."
@@ -3677,6 +3693,10 @@
"$ref": "#/components/schemas/RefreshCadence",
"description": "How frequently the projection should be regenerated."
},
+ "regenerate": {
+ "type": "boolean",
+ "description": "When `true`, regenerate even if a cached result exists."
+ },
"target_type": {
"$ref": "#/components/schemas/TargetType",
"description": "Whether the projection is materialized for the requesting user or their team."
diff --git a/rust/cloud-storage/.sqlx/query-44e7fd51a0308617c9641b7d42de6a2ddd91a43806bde7e2910e4ae7d536a041.json b/rust/cloud-storage/.sqlx/query-1c7e554ec85b140159779958a267647e6cdca5f0aea7aa5c260b9969635266b8.json
similarity index 71%
rename from rust/cloud-storage/.sqlx/query-44e7fd51a0308617c9641b7d42de6a2ddd91a43806bde7e2910e4ae7d536a041.json
rename to rust/cloud-storage/.sqlx/query-1c7e554ec85b140159779958a267647e6cdca5f0aea7aa5c260b9969635266b8.json
index d7864e5efb..574d987ea5 100644
--- a/rust/cloud-storage/.sqlx/query-44e7fd51a0308617c9641b7d42de6a2ddd91a43806bde7e2910e4ae7d536a041.json
+++ b/rust/cloud-storage/.sqlx/query-1c7e554ec85b140159779958a267647e6cdca5f0aea7aa5c260b9969635266b8.json
@@ -1,6 +1,6 @@
{
"db_name": "PostgreSQL",
- "query": "\n SELECT id, prompt, prompt_hash, target_type, refresh_cadence, expiry, created_at, updated_at\n FROM ai_projection\n WHERE id = $1\n ",
+ "query": "\n SELECT id, prompt, prompt_hash, target_type, refresh_cadence, expiry, model, output_schema, created_at, updated_at\n FROM ai_projection\n WHERE id = $1\n ",
"describe": {
"columns": [
{
@@ -35,11 +35,21 @@
},
{
"ordinal": 6,
+ "name": "model",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 7,
+ "name": "output_schema",
+ "type_info": "Jsonb"
+ },
+ {
+ "ordinal": 8,
"name": "created_at",
"type_info": "Timestamptz"
},
{
- "ordinal": 7,
+ "ordinal": 9,
"name": "updated_at",
"type_info": "Timestamptz"
}
@@ -56,9 +66,11 @@
false,
false,
false,
+ true,
+ true,
false,
false
]
},
- "hash": "44e7fd51a0308617c9641b7d42de6a2ddd91a43806bde7e2910e4ae7d536a041"
+ "hash": "1c7e554ec85b140159779958a267647e6cdca5f0aea7aa5c260b9969635266b8"
}
diff --git a/rust/cloud-storage/.sqlx/query-af8f1da403e88b09bf7ca62ae45e70927d33e28402ff66b8e8eeb39ab54f96ea.json b/rust/cloud-storage/.sqlx/query-2edf47d06aedea406c308de5017585ab4792ab88a742498176a2e2065ec086f1.json
similarity index 55%
rename from rust/cloud-storage/.sqlx/query-af8f1da403e88b09bf7ca62ae45e70927d33e28402ff66b8e8eeb39ab54f96ea.json
rename to rust/cloud-storage/.sqlx/query-2edf47d06aedea406c308de5017585ab4792ab88a742498176a2e2065ec086f1.json
index 6ddf8e6caf..4cea259544 100644
--- a/rust/cloud-storage/.sqlx/query-af8f1da403e88b09bf7ca62ae45e70927d33e28402ff66b8e8eeb39ab54f96ea.json
+++ b/rust/cloud-storage/.sqlx/query-2edf47d06aedea406c308de5017585ab4792ab88a742498176a2e2065ec086f1.json
@@ -1,6 +1,6 @@
{
"db_name": "PostgreSQL",
- "query": "\n UPDATE user_ai_projection\n SET status = $3, error = $4, updated_at = NOW()\n WHERE ai_projection_id = $1 AND target_id = $2\n ",
+ "query": "\n UPDATE user_ai_projection\n SET status = $4, updated_at = NOW()\n WHERE ai_projection_id = $1 AND target_id = $2 AND prompt_hash = $3\n ",
"describe": {
"columns": [],
"parameters": {
@@ -13,5 +13,5 @@
},
"nullable": []
},
- "hash": "af8f1da403e88b09bf7ca62ae45e70927d33e28402ff66b8e8eeb39ab54f96ea"
+ "hash": "2edf47d06aedea406c308de5017585ab4792ab88a742498176a2e2065ec086f1"
}
diff --git a/rust/cloud-storage/.sqlx/query-4cacf56482bf5307f00763a90f91a1bae873a0cb73d8785e238bdaf71f58d9b7.json b/rust/cloud-storage/.sqlx/query-4cacf56482bf5307f00763a90f91a1bae873a0cb73d8785e238bdaf71f58d9b7.json
new file mode 100644
index 0000000000..a9a171c5ca
--- /dev/null
+++ b/rust/cloud-storage/.sqlx/query-4cacf56482bf5307f00763a90f91a1bae873a0cb73d8785e238bdaf71f58d9b7.json
@@ -0,0 +1,34 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n UPDATE user_ai_projection u\n SET status = 'refreshing', prompt_hash = p.prompt_hash, updated_at = NOW()\n FROM ai_projection p\n WHERE u.ai_projection_id = p.id\n AND p.refresh_cadence = $1\n AND (\n (u.stale_at IS NOT NULL AND u.stale_at < NOW())\n OR (u.status = 'error' AND u.stale_at IS NULL)\n )\n AND u.last_requested_at >= NOW() - (\n CASE p.expiry\n WHEN 'day' THEN INTERVAL '1 day'\n WHEN 'week' THEN INTERVAL '7 days'\n WHEN 'month' THEN INTERVAL '30 days'\n END)\n AND (\n u.status IN ('ready', 'error')\n OR (u.status = 'refreshing' AND u.updated_at < NOW() - INTERVAL '15 minutes')\n )\n RETURNING u.ai_projection_id, u.target_id, p.prompt_hash\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "ai_projection_id",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 1,
+ "name": "target_id",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 2,
+ "name": "prompt_hash",
+ "type_info": "Text"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Text"
+ ]
+ },
+ "nullable": [
+ false,
+ false,
+ false
+ ]
+ },
+ "hash": "4cacf56482bf5307f00763a90f91a1bae873a0cb73d8785e238bdaf71f58d9b7"
+}
diff --git a/rust/cloud-storage/.sqlx/query-4f7d47d4b75fd81a44c21bd147957428788a190933c8f4aef68587165b10eb74.json b/rust/cloud-storage/.sqlx/query-4f7d47d4b75fd81a44c21bd147957428788a190933c8f4aef68587165b10eb74.json
deleted file mode 100644
index d5d5affcf8..0000000000
--- a/rust/cloud-storage/.sqlx/query-4f7d47d4b75fd81a44c21bd147957428788a190933c8f4aef68587165b10eb74.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "db_name": "PostgreSQL",
- "query": "\n INSERT INTO user_ai_projection (ai_projection_id, target_id, prompt_hash, status)\n VALUES ($1, $2, $3, $4)\n ON CONFLICT (target_id, ai_projection_id)\n DO UPDATE SET last_requested_at = NOW(), updated_at = NOW()\n ",
- "describe": {
- "columns": [],
- "parameters": {
- "Left": [
- "Text",
- "Text",
- "Text",
- "Text"
- ]
- },
- "nullable": []
- },
- "hash": "4f7d47d4b75fd81a44c21bd147957428788a190933c8f4aef68587165b10eb74"
-}
diff --git a/rust/cloud-storage/.sqlx/query-663af7d62849f2b928e48fefb52662cf24d94b18ee47caaa4f12dc6492fc2931.json b/rust/cloud-storage/.sqlx/query-663af7d62849f2b928e48fefb52662cf24d94b18ee47caaa4f12dc6492fc2931.json
deleted file mode 100644
index 6d04ee83ec..0000000000
--- a/rust/cloud-storage/.sqlx/query-663af7d62849f2b928e48fefb52662cf24d94b18ee47caaa4f12dc6492fc2931.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
- "db_name": "PostgreSQL",
- "query": "\n INSERT INTO ai_projection (id, prompt, prompt_hash, target_type, refresh_cadence, expiry)\n VALUES ($1, $2, $3, $4, $5, $6)\n ON CONFLICT (id) DO NOTHING\n ",
- "describe": {
- "columns": [],
- "parameters": {
- "Left": [
- "Text",
- "Text",
- "Text",
- "Text",
- "Text",
- "Text"
- ]
- },
- "nullable": []
- },
- "hash": "663af7d62849f2b928e48fefb52662cf24d94b18ee47caaa4f12dc6492fc2931"
-}
diff --git a/rust/cloud-storage/.sqlx/query-a1c2f53a2400350d4ccde0d3a07e4f2d85893cdbdda343830d4e4ff721e183b9.json b/rust/cloud-storage/.sqlx/query-a1c2f53a2400350d4ccde0d3a07e4f2d85893cdbdda343830d4e4ff721e183b9.json
deleted file mode 100644
index e7199c82c8..0000000000
--- a/rust/cloud-storage/.sqlx/query-a1c2f53a2400350d4ccde0d3a07e4f2d85893cdbdda343830d4e4ff721e183b9.json
+++ /dev/null
@@ -1,34 +0,0 @@
-{
- "db_name": "PostgreSQL",
- "query": "\n UPDATE user_ai_projection u\n SET status = 'refreshing', updated_at = NOW()\n FROM ai_projection p\n WHERE u.ai_projection_id = p.id\n AND p.refresh_cadence = $1\n AND u.stale_at IS NOT NULL\n AND u.stale_at < NOW()\n AND u.last_requested_at >= NOW() - (\n CASE p.expiry\n WHEN 'day' THEN INTERVAL '1 day'\n WHEN 'week' THEN INTERVAL '7 days'\n WHEN 'month' THEN INTERVAL '30 days'\n END)\n AND (\n u.status IN ('ready', 'error')\n OR (u.status = 'refreshing' AND u.updated_at < NOW() - INTERVAL '15 minutes')\n )\n RETURNING u.ai_projection_id, u.target_id, p.prompt_hash\n ",
- "describe": {
- "columns": [
- {
- "ordinal": 0,
- "name": "ai_projection_id",
- "type_info": "Text"
- },
- {
- "ordinal": 1,
- "name": "target_id",
- "type_info": "Text"
- },
- {
- "ordinal": 2,
- "name": "prompt_hash",
- "type_info": "Text"
- }
- ],
- "parameters": {
- "Left": [
- "Text"
- ]
- },
- "nullable": [
- false,
- false,
- false
- ]
- },
- "hash": "a1c2f53a2400350d4ccde0d3a07e4f2d85893cdbdda343830d4e4ff721e183b9"
-}
diff --git a/rust/cloud-storage/.sqlx/query-b1d6ec1e36ba60b7b733b32bbc5b27b92de96478fe100662b876325c47816f55.json b/rust/cloud-storage/.sqlx/query-b1d6ec1e36ba60b7b733b32bbc5b27b92de96478fe100662b876325c47816f55.json
new file mode 100644
index 0000000000..03f529fe2b
--- /dev/null
+++ b/rust/cloud-storage/.sqlx/query-b1d6ec1e36ba60b7b733b32bbc5b27b92de96478fe100662b876325c47816f55.json
@@ -0,0 +1,18 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n UPDATE user_ai_projection\n SET status = $4, error = $5, updated_at = NOW()\n WHERE ai_projection_id = $1 AND target_id = $2 AND prompt_hash = $3\n ",
+ "describe": {
+ "columns": [],
+ "parameters": {
+ "Left": [
+ "Text",
+ "Text",
+ "Text",
+ "Text",
+ "Text"
+ ]
+ },
+ "nullable": []
+ },
+ "hash": "b1d6ec1e36ba60b7b733b32bbc5b27b92de96478fe100662b876325c47816f55"
+}
diff --git a/rust/cloud-storage/.sqlx/query-b3f1c2bf756ce138b10dbbcb99ae15524a4940e14a8d34eadb2723dc0627b96c.json b/rust/cloud-storage/.sqlx/query-b3f1c2bf756ce138b10dbbcb99ae15524a4940e14a8d34eadb2723dc0627b96c.json
new file mode 100644
index 0000000000..b0e2fa40c8
--- /dev/null
+++ b/rust/cloud-storage/.sqlx/query-b3f1c2bf756ce138b10dbbcb99ae15524a4940e14a8d34eadb2723dc0627b96c.json
@@ -0,0 +1,21 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n INSERT INTO ai_projection (id, prompt, prompt_hash, target_type, refresh_cadence, expiry, model, output_schema)\n VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n ON CONFLICT (id) DO UPDATE SET\n prompt = EXCLUDED.prompt,\n prompt_hash = EXCLUDED.prompt_hash,\n target_type = EXCLUDED.target_type,\n refresh_cadence = EXCLUDED.refresh_cadence,\n expiry = EXCLUDED.expiry,\n model = EXCLUDED.model,\n output_schema = EXCLUDED.output_schema,\n updated_at = NOW()\n WHERE ai_projection.prompt_hash IS DISTINCT FROM EXCLUDED.prompt_hash\n OR ai_projection.target_type IS DISTINCT FROM EXCLUDED.target_type\n OR ai_projection.refresh_cadence IS DISTINCT FROM EXCLUDED.refresh_cadence\n OR ai_projection.expiry IS DISTINCT FROM EXCLUDED.expiry\n ",
+ "describe": {
+ "columns": [],
+ "parameters": {
+ "Left": [
+ "Text",
+ "Text",
+ "Text",
+ "Text",
+ "Text",
+ "Text",
+ "Text",
+ "Jsonb"
+ ]
+ },
+ "nullable": []
+ },
+ "hash": "b3f1c2bf756ce138b10dbbcb99ae15524a4940e14a8d34eadb2723dc0627b96c"
+}
diff --git a/rust/cloud-storage/.sqlx/query-01ee626a0234bc3bd1463f146588eeff4d4fb032d4b9f1153ef2415f50bdae2f.json b/rust/cloud-storage/.sqlx/query-bc0108c18e64a08669064cf1c7f97cff4e9c12379e88b21e9b1f4f4bca17b2bc.json
similarity index 50%
rename from rust/cloud-storage/.sqlx/query-01ee626a0234bc3bd1463f146588eeff4d4fb032d4b9f1153ef2415f50bdae2f.json
rename to rust/cloud-storage/.sqlx/query-bc0108c18e64a08669064cf1c7f97cff4e9c12379e88b21e9b1f4f4bca17b2bc.json
index e3117a619d..1012388d56 100644
--- a/rust/cloud-storage/.sqlx/query-01ee626a0234bc3bd1463f146588eeff4d4fb032d4b9f1153ef2415f50bdae2f.json
+++ b/rust/cloud-storage/.sqlx/query-bc0108c18e64a08669064cf1c7f97cff4e9c12379e88b21e9b1f4f4bca17b2bc.json
@@ -1,6 +1,6 @@
{
"db_name": "PostgreSQL",
- "query": "\n UPDATE user_ai_projection\n SET status = $3, result = $4, error = NULL,\n generated_at = $5, stale_at = $6, updated_at = NOW()\n WHERE ai_projection_id = $1 AND target_id = $2\n ",
+ "query": "\n UPDATE user_ai_projection\n SET status = $4, result = $5, error = NULL,\n generated_at = $6, stale_at = $7, updated_at = NOW()\n WHERE ai_projection_id = $1 AND target_id = $2 AND prompt_hash = $3\n ",
"describe": {
"columns": [],
"parameters": {
@@ -9,11 +9,12 @@
"Text",
"Text",
"Text",
+ "Text",
"Timestamptz",
"Timestamptz"
]
},
"nullable": []
},
- "hash": "01ee626a0234bc3bd1463f146588eeff4d4fb032d4b9f1153ef2415f50bdae2f"
+ "hash": "bc0108c18e64a08669064cf1c7f97cff4e9c12379e88b21e9b1f4f4bca17b2bc"
}
diff --git a/rust/cloud-storage/.sqlx/query-d6e06bcf3cf31ae9d59812057706efe3cae430139bb134856163491df162abf9.json b/rust/cloud-storage/.sqlx/query-d6e06bcf3cf31ae9d59812057706efe3cae430139bb134856163491df162abf9.json
new file mode 100644
index 0000000000..7ce99d4aa1
--- /dev/null
+++ b/rust/cloud-storage/.sqlx/query-d6e06bcf3cf31ae9d59812057706efe3cae430139bb134856163491df162abf9.json
@@ -0,0 +1,17 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n INSERT INTO user_ai_projection (ai_projection_id, target_id, prompt_hash, status)\n VALUES ($1, $2, $3, $4)\n ON CONFLICT (target_id, ai_projection_id)\n DO UPDATE SET\n last_requested_at = NOW(),\n updated_at = NOW(),\n status = CASE\n WHEN user_ai_projection.prompt_hash IS DISTINCT FROM EXCLUDED.prompt_hash\n THEN 'cold'\n ELSE user_ai_projection.status\n END,\n prompt_hash = EXCLUDED.prompt_hash\n ",
+ "describe": {
+ "columns": [],
+ "parameters": {
+ "Left": [
+ "Text",
+ "Text",
+ "Text",
+ "Text"
+ ]
+ },
+ "nullable": []
+ },
+ "hash": "d6e06bcf3cf31ae9d59812057706efe3cae430139bb134856163491df162abf9"
+}
diff --git a/rust/cloud-storage/Cargo.lock b/rust/cloud-storage/Cargo.lock
index b04ae0e588..a5e38b60ea 100644
--- a/rust/cloud-storage/Cargo.lock
+++ b/rust/cloud-storage/Cargo.lock
@@ -114,10 +114,12 @@ dependencies = [
"aws-sdk-sqs",
"axum",
"chrono",
+ "connection_gateway_client",
"futures",
"http-body-util",
"macro_db_migrator",
"macro_user_id",
+ "model-entity",
"model-error-response",
"model_user",
"models_ai_projection",
@@ -3826,6 +3828,7 @@ dependencies = [
"chat",
"chrono",
"connection_gateway",
+ "connection_gateway_client",
"cookie",
"crm",
"document_storage_service_client",
diff --git a/rust/cloud-storage/ai_projections/Cargo.toml b/rust/cloud-storage/ai_projections/Cargo.toml
index 80985a4a5a..9a4b62786d 100644
--- a/rust/cloud-storage/ai_projections/Cargo.toml
+++ b/rust/cloud-storage/ai_projections/Cargo.toml
@@ -16,7 +16,8 @@ inbound = ["axum", "ports"]
outbound = [
"dep:sqlx",
"dep:sqs_client",
- "dep:serde_json",
+ "dep:connection_gateway_client",
+ "dep:model-entity",
"ports",
]
# Agent-backed projection generator (the outbound adapter that runs the AI
@@ -34,7 +35,6 @@ worker = [
"ports",
"dep:sqs_worker",
"dep:aws-sdk-sqs",
- "dep:serde_json",
]
[dependencies]
@@ -44,6 +44,7 @@ chrono = { workspace = true }
macro_user_id = { path = "../macro_user_id" }
models_ai_projection = { path = "../models_ai_projection" }
serde = { workspace = true }
+serde_json = { workspace = true }
sha2 = { workspace = true }
thiserror = { workspace = true }
tracing = { workspace = true }
@@ -64,11 +65,12 @@ sqlx = { workspace = true, optional = true }
sqs_client = { path = "../sqs_client", default-features = false, features = [
"ai_projection",
], optional = true }
+connection_gateway_client = { path = "../connection_gateway_client", optional = true }
+model-entity = { path = "../model-entity", optional = true }
# Worker (inbound SQS poller) dependencies
sqs_worker = { path = "../sqs_worker", optional = true }
aws-sdk-sqs = { workspace = true, optional = true }
-serde_json = { workspace = true, optional = true }
# Agent generator dependencies (the AI toolset adapter)
ai_tools = { path = "../ai_tools", optional = true }
diff --git a/rust/cloud-storage/ai_projections/src/domain.rs b/rust/cloud-storage/ai_projections/src/domain.rs
index 2b2c73f2d7..d5c2d4d47e 100644
--- a/rust/cloud-storage/ai_projections/src/domain.rs
+++ b/rust/cloud-storage/ai_projections/src/domain.rs
@@ -5,3 +5,4 @@ pub mod ai_projection_repo;
pub mod ai_projection_service;
pub mod model;
pub mod projection_generator;
+pub mod projection_notifier;
diff --git a/rust/cloud-storage/ai_projections/src/domain/ai_projection_repo.rs b/rust/cloud-storage/ai_projections/src/domain/ai_projection_repo.rs
index c8ba518991..e0e239ced8 100644
--- a/rust/cloud-storage/ai_projections/src/domain/ai_projection_repo.rs
+++ b/rust/cloud-storage/ai_projections/src/domain/ai_projection_repo.rs
@@ -8,9 +8,12 @@ use crate::domain::model::{
/// The AiProjectionRepository defines the persistence actions for ai projections.
pub trait AiProjectionRepository: Clone + Send + Sync + 'static {
- /// Gets an existing projection definition by id, or creates it if it does
- /// not exist. Existing definitions are returned unchanged.
- fn get_or_create_projection(
+ /// Gets a projection definition by id, creating it if absent. An existing
+ /// definition whose `prompt_hash` (or cadence/expiry) differs from the
+ /// request is updated in place, so re-upserting with a changed prompt,
+ /// model, or output schema revises the definition.
+ #[allow(clippy::too_many_arguments)]
+ fn upsert_projection_definition(
&self,
id: &str,
prompt: &str,
@@ -18,10 +21,14 @@ pub trait AiProjectionRepository: Clone + Send + Sync + 'static {
target_type: TargetType,
refresh_cadence: RefreshCadence,
expiry: Expiry,
+ model: Option<&str>,
+ output_schema: Option<&serde_json::Value>,
) -> impl Future<Output = Result<AiProjection, AiProjectionError>> + Send;
/// Gets the target's instance of a projection, or creates a cold instance
- /// if one does not exist for the given prompt version.
+ /// if one does not exist. An existing instance whose `prompt_hash` differs
+ /// from the definition's is reset to cold (keeping its previous result
+ /// visible until regeneration overwrites it).
fn get_or_create_target_projection(
&self,
ai_projection_id: &str,
@@ -29,6 +36,14 @@ pub trait AiProjectionRepository: Clone + Send + Sync + 'static {
prompt_hash: &str,
) -> impl Future<Output = Result<UserAiProjection, AiProjectionError>> + Send;
+ /// Gets the target's instance of a projection. Returns
+ /// [`AiProjectionError::NotFound`] if no instance exists.
+ fn get_target_projection(
+ &self,
+ ai_projection_id: &str,
+ target_id: &str,
+ ) -> impl Future<Output = Result<UserAiProjection, AiProjectionError>> + Send;
+
/// Gets an existing projection definition by id. Returns
/// [`AiProjectionError::NotFound`] if no definition exists.
fn get_projection(
@@ -55,30 +70,45 @@ pub trait AiProjectionRepository: Clone + Send + Sync + 'static {
target_id: &str,
) -> impl Future<Output = Result<(), AiProjectionError>> + Send;
- /// Marks the target's projection instance as loading.
+ /// Marks the target's projection instance as loading. A no-op if the
+ /// instance's `prompt_hash` no longer matches (a newer version exists).
fn set_projection_loading(
&self,
ai_projection_id: &str,
target_id: &str,
+ prompt_hash: &str,
+ ) -> impl Future<Output = Result<(), AiProjectionError>> + Send;
+
+ /// Marks the target's projection instance as refreshing, signalling that a
+ /// regeneration is in flight while the previous result remains available.
+ fn set_projection_refreshing(
+ &self,
+ ai_projection_id: &str,
+ target_id: &str,
) -> impl Future<Output = Result<(), AiProjectionError>> + Send;
/// Stores a materialized result on the target's projection instance and
- /// marks it ready.
+ /// marks it ready. A no-op if the instance's `prompt_hash` no longer
+ /// matches (the result belongs to an outdated version).
+ #[allow(clippy::too_many_arguments)]
fn set_projection_result(
&self,
ai_projection_id: &str,
target_id: &str,
+ prompt_hash: &str,
result: &str,
generated_at: chrono::DateTime<chrono::Utc>,
stale_at: chrono::DateTime<chrono::Utc>,
) -> impl Future<Output = Result<(), AiProjectionError>> + Send;
/// Records a materialization error on the target's projection instance and
- /// marks it errored.
+ /// marks it errored. A no-op if the instance's `prompt_hash` no longer
+ /// matches.
fn set_projection_error(
&self,
ai_projection_id: &str,
target_id: &str,
+ prompt_hash: &str,
error: &str,
) -> impl Future<Output = Result<(), AiProjectionError>> + Send;
diff --git a/rust/cloud-storage/ai_projections/src/domain/ai_projection_service.rs b/rust/cloud-storage/ai_projections/src/domain/ai_projection_service.rs
index 126a68cc41..aeebc5e7d6 100644
--- a/rust/cloud-storage/ai_projections/src/domain/ai_projection_service.rs
+++ b/rust/cloud-storage/ai_projections/src/domain/ai_projection_service.rs
@@ -11,10 +11,11 @@ use crate::domain::{
ai_projection_queue::AiProjectionQueue,
ai_projection_repo::AiProjectionRepository,
model::{
- AiProjectionError, ProjectionStatus, TargetType, UpsertProjectionError,
+ AiProjection, AiProjectionError, ProjectionStatus, TargetType, UpsertProjectionError,
UpsertProjectionParams, UserAiProjection,
},
- projection_generator::ProjectionGenerator,
+ projection_generator::{GenerationRequest, ProjectionGenerator},
+ projection_notifier::ProjectionNotifier,
};
/// The permission required to read professional (premium) features.
@@ -22,10 +23,15 @@ pub const READ_PROFESSIONAL_FEATURES: &str = "read:professional_features";
/// The AiProjectionService defines the high-level operations for ai projections.
pub trait AiProjectionService: Clone + Send + Sync + 'static {
- /// Gets or creates a projection definition and the target's cold instance
- /// of it, returning that instance. The concrete target id is resolved from
- /// the authenticated user: a `user` target resolves to the user's own id,
- /// a `team` target resolves to the user's (single) team.
+ /// Gets or creates a projection definition and the target's instance of it,
+ /// returning that instance. The concrete target id is resolved from the
+ /// authenticated user: a `user` target resolves to the user's own id, a
+ /// `team` target resolves to the user's (single) team.
+ ///
+ /// A cold instance (or a `regenerate` request) triggers materialization:
+ /// asynchronously via the queue by default, or inline when
+ /// `await_generation` is set — in which case the returned instance reflects
+ /// the finished generation.
fn upsert_projection(
&self,
user_id: &MacroUserIdStr<'_>,
@@ -49,51 +55,55 @@ pub trait AiProjectionService: Clone + Send + Sync + 'static {
}
/// Implementation of [`AiProjectionService`] backed by an
-/// [`AiProjectionRepository`], an [`AiProjectionQueue`], and a
-/// [`ProjectionGenerator`].
+/// [`AiProjectionRepository`], an [`AiProjectionQueue`], a
+/// [`ProjectionGenerator`], and a [`ProjectionNotifier`].
#[derive(Debug, Clone)]
-pub struct AiProjectionServiceImpl<R, Q, G>
+pub struct AiProjectionServiceImpl<R, Q, G, N>
where
R: AiProjectionRepository,
Q: AiProjectionQueue,
G: ProjectionGenerator,
+ N: ProjectionNotifier,
{
repository: R,
queue: Q,
generator: G,
+ notifier: N,
}
-impl<R, Q, G> AiProjectionServiceImpl<R, Q, G>
+impl<R, Q, G, N> AiProjectionServiceImpl<R, Q, G, N>
where
R: AiProjectionRepository,
Q: AiProjectionQueue,
G: ProjectionGenerator,
+ N: ProjectionNotifier,
{
/// Creates a new AiProjectionServiceImpl.
- pub fn new(repository: R, queue: Q, generator: G) -> Self {
+ pub fn new(repository: R, queue: Q, generator: G, notifier: N) -> Self {
Self {
repository,
queue,
generator,
+ notifier,
}
}
- /// Loads the projection definition, marks the target instance as loading,
- /// runs the prompt through the generator, and stores the result as ready.
+ /// Marks the target instance as loading, runs the prompt through the
+ /// generator, and stores the result as ready.
///
/// The caller ([`AiProjectionService::materialize`]) owns the processing
/// claim and is responsible for releasing it and recording errors.
async fn generate_and_store(
&self,
+ projection: &AiProjection,
message: &AiProjectionQueueMessage,
) -> Result<(), AiProjectionError> {
- let projection = self
- .repository
- .get_projection(&message.ai_projection_id)
- .await?;
-
self.repository
- .set_projection_loading(&message.ai_projection_id, &message.target_id)
+ .set_projection_loading(
+ &message.ai_projection_id,
+ &message.target_id,
+ &message.prompt_hash,
+ )
.await?;
// For `user` targets the target id is the user id. `team` targets store
@@ -103,7 +113,15 @@ where
let result = self
.generator
- .generate(&user_id, &projection.prompt)
+ .generate(
+ &user_id,
+ GenerationRequest {
+ projection_id: &projection.id,
+ prompt: &projection.prompt,
+ model: projection.model.as_deref(),
+ output_schema: projection.output_schema.as_ref(),
+ },
+ )
.await?;
let generated_at = chrono::Utc::now();
@@ -113,6 +131,7 @@ where
.set_projection_result(
&message.ai_projection_id,
&message.target_id,
+ &message.prompt_hash,
&result,
generated_at,
stale_at,
@@ -122,6 +141,30 @@ where
Ok(())
}
+ /// Pushes the instance's current state to the target's connected clients.
+ /// Best-effort: a failed lookup or send is logged and swallowed so
+ /// notification issues never fail materialization.
+ async fn notify_updated(&self, target_type: TargetType, message: &AiProjectionQueueMessage) {
+ let instance = match self
+ .repository
+ .get_target_projection(&message.ai_projection_id, &message.target_id)
+ .await
+ {
+ Ok(instance) => instance,
+ Err(e) => {
+ tracing::error!(error=?e, "failed to load ai projection instance for notification");
+ return;
+ }
+ };
+ self.notifier
+ .notify_updated(target_type, &instance)
+ .await
+ .inspect_err(|e| {
+ tracing::error!(error=?e, "failed to push ai projection update notification");
+ })
+ .ok();
+ }
+
/// Resolves the concrete target id from the authenticated user and the
/// requested target type. A `user` target resolves to the user's own id; a
/// `team` target resolves to the user's single team (erroring if the user
@@ -149,9 +192,24 @@ where
}
}
-/// Computes the prompt version hash used as part of a projection's cache key.
-pub fn hash_prompt(prompt: &str) -> String {
- let digest = Sha256::digest(prompt.as_bytes());
+/// Computes the version hash used as part of a projection's cache key: any
+/// change to the prompt, model, or output schema regenerates cached instances.
+pub fn hash_projection_version(
+ prompt: &str,
+ model: Option<&str>,
+ output_schema: Option<&serde_json::Value>,
+) -> String {
+ let mut hasher = Sha256::new();
+ hasher.update(prompt.as_bytes());
+ hasher.update([0u8]);
+ hasher.update(model.unwrap_or_default().as_bytes());
+ hasher.update([0u8]);
+ if let Some(schema) = output_schema {
+ // serde_json::Value maps are BTreeMap-backed, so serialization is
+ // canonical regardless of the key order the client sent.
+ hasher.update(schema.to_string().as_bytes());
+ }
+ let digest = hasher.finalize();
let mut hex = String::with_capacity(digest.len() * 2);
for byte in digest {
use std::fmt::Write;
@@ -160,11 +218,12 @@ pub fn hash_prompt(prompt: &str) -> String {
hex
}
-impl<R, Q, G> AiProjectionService for AiProjectionServiceImpl<R, Q, G>
+impl<R, Q, G, N> AiProjectionService for AiProjectionServiceImpl<R, Q, G, N>
where
R: AiProjectionRepository,
Q: AiProjectionQueue,
G: ProjectionGenerator,
+ N: ProjectionNotifier,
{
#[tracing::instrument(skip(self), err)]
async fn upsert_projection(
@@ -185,42 +244,82 @@ where
let target_id = self.resolve_target_id(user_id, params.target_type).await?;
- let prompt_hash = hash_prompt(&params.prompt);
+ let prompt_hash = hash_projection_version(
+ &params.prompt,
+ params.model.as_deref(),
+ params.output_schema.as_ref(),
+ );
let projection = self
.repository
- .get_or_create_projection(
+ .upsert_projection_definition(
&params.id,
&params.prompt,
&prompt_hash,
params.target_type,
params.refresh_cadence,
params.expiry,
+ params.model.as_deref(),
+ params.output_schema.as_ref(),
)
.await?;
- let target_projection = self
+ // An instance whose prompt_hash no longer matches the definition comes
+ // back reset to cold, so a changed prompt/model/schema regenerates.
+ let mut target_projection = self
.repository
.get_or_create_target_projection(&projection.id, &target_id, &projection.prompt_hash)
.await?;
- // A cold instance has no materialized result yet, so request async
- // materialization. The instance already exists, so a failed enqueue is
- // logged and swallowed rather than failing the request.
- if target_projection.status == ProjectionStatus::Cold {
- self.queue
- .enqueue_materialization(AiProjectionQueueMessage {
- ai_projection_id: target_projection.ai_projection_id.clone(),
- target_id: target_projection.target_id.clone(),
- prompt_hash: target_projection.prompt_hash.clone(),
- })
+ let needs_generation =
+ target_projection.status == ProjectionStatus::Cold || params.regenerate;
+ if !needs_generation {
+ return Ok(target_projection);
+ }
+
+ let message = AiProjectionQueueMessage {
+ ai_projection_id: target_projection.ai_projection_id.clone(),
+ target_id: target_projection.target_id.clone(),
+ prompt_hash: target_projection.prompt_hash.clone(),
+ };
+
+ if params.await_generation {
+ // Materialize inline and return the finished state. Generation
+ // failures are recorded on the instance (status `error`) rather
+ // than failing the request, and a concurrent claim elsewhere means
+ // the state below reflects that in-flight work.
+ self.materialize(message)
.await
.inspect_err(|e| {
- tracing::error!(error=?e, "failed to enqueue ai projection materialization");
+ tracing::error!(error=?e, "inline ai projection materialization failed");
})
.ok();
+ target_projection = self
+ .repository
+ .get_target_projection(&projection.id, &target_id)
+ .await?;
+ return Ok(target_projection);
+ }
+
+ // Re-triggering over an existing result: surface as refreshing so the
+ // stale result stays visible while the regeneration is in flight.
+ if target_projection.status != ProjectionStatus::Cold {
+ self.repository
+ .set_projection_refreshing(&projection.id, &target_id)
+ .await?;
+ target_projection.status = ProjectionStatus::Refreshing;
}
+ // The instance already exists, so a failed enqueue is logged and
+ // swallowed rather than failing the request.
+ self.queue
+ .enqueue_materialization(message)
+ .await
+ .inspect_err(|e| {
+ tracing::error!(error=?e, "failed to enqueue ai projection materialization");
+ })
+ .ok();
+
Ok(target_projection)
}
@@ -246,6 +345,22 @@ where
"materializing ai projection"
);
+ let projection = self
+ .repository
+ .get_projection(&message.ai_projection_id)
+ .await?;
+
+ // The definition was revised after this message was enqueued; a newer
+ // message for the current version exists, so skip and acknowledge.
+ if projection.prompt_hash != message.prompt_hash {
+ tracing::info!(
+ ai_projection_id = %message.ai_projection_id,
+ target_id = %message.target_id,
+ "ai projection version changed since enqueue; skipping stale message"
+ );
+ return Ok(());
+ }
+
// Claim the (ai_projection_id, target_id) pair. If another worker is
// already processing it, skip and acknowledge the message rather than
// duplicating work.
@@ -264,7 +379,7 @@ where
// Run the generation, then release the claim regardless of the outcome
// so a retried message can re-acquire it.
- let result = self.generate_and_store(&message).await;
+ let result = self.generate_and_store(&projection, &message).await;
match result {
Ok(()) => {
@@ -277,6 +392,7 @@ where
tracing::error!(error=?e, "failed to release ai projection processing claim");
})
.ok();
+ self.notify_updated(projection.target_type, &message).await;
Ok(())
}
Err(e) => {
@@ -286,6 +402,7 @@ where
.set_projection_error(
&message.ai_projection_id,
&message.target_id,
+ &message.prompt_hash,
&e.to_string(),
)
.await
@@ -296,6 +413,7 @@ where
self.repository
.finish_processing(&message.ai_projection_id, &message.target_id)
.await?;
+ self.notify_updated(projection.target_type, &message).await;
Err(e)
}
}
diff --git a/rust/cloud-storage/ai_projections/src/domain/ai_projection_service/test.rs b/rust/cloud-storage/ai_projections/src/domain/ai_projection_service/test.rs
index 15e1933074..17da5845fc 100644
--- a/rust/cloud-storage/ai_projections/src/domain/ai_projection_service/test.rs
+++ b/rust/cloud-storage/ai_projections/src/domain/ai_projection_service/test.rs
@@ -7,17 +7,25 @@ use models_ai_projection::AiProjectionQueueMessage;
use crate::domain::{
ai_projection_queue::AiProjectionQueue,
ai_projection_repo::AiProjectionRepository,
- ai_projection_service::{AiProjectionService, AiProjectionServiceImpl, hash_prompt},
+ ai_projection_service::{
+ AiProjectionService, AiProjectionServiceImpl, hash_projection_version,
+ },
model::{
AiProjection, AiProjectionError, Expiry, ProjectionStatus, RefreshCadence, TargetType,
UpsertProjectionError, UpsertProjectionParams, UserAiProjection,
},
- projection_generator::ProjectionGenerator,
+ projection_generator::{GenerationRequest, ProjectionGenerator},
+ projection_notifier::ProjectionNotifier,
};
/// The prompt the mock repository reports for any projection definition.
const TEST_PROMPT: &str = "What is important?";
+/// The version hash of [`TEST_PROMPT`] with no model or schema.
+fn test_hash() -> String {
+ hash_projection_version(TEST_PROMPT, None, None)
+}
+
/// A tiny in-memory mock queue that records enqueued materialization messages.
#[derive(Clone, Default)]
struct MockQueue {
@@ -40,19 +48,21 @@ impl AiProjectionQueue for MockQueue {
struct MockGenerator {
response: String,
fail: bool,
- calls: Arc<Mutex<Vec<(String, String)>>>,
+ calls: Arc<Mutex<Vec<(String, String, Option<String>, Option<serde_json::Value>)>>>,
}
impl ProjectionGenerator for MockGenerator {
async fn generate(
&self,
user_id: &MacroUserIdStr<'_>,
- prompt: &str,
+ request: GenerationRequest<'_>,
) -> Result<String, AiProjectionError> {
- self.calls
- .lock()
- .unwrap()
- .push((user_id.as_ref().to_string(), prompt.to_string()));
+ self.calls.lock().unwrap().push((
+ user_id.as_ref().to_string(),
+ request.prompt.to_string(),
+ request.model.map(str::to_string),
+ request.output_schema.cloned(),
+ ));
if self.fail {
return Err(AiProjectionError::Generation("boom".to_string()));
}
@@ -60,9 +70,36 @@ impl ProjectionGenerator for MockGenerator {
}
}
-/// Builds a service from a repo, using a default mock queue and generator.
-fn service_with(repo: MockRepo) -> AiProjectionServiceImpl<MockRepo, MockQueue, MockGenerator> {
- AiProjectionServiceImpl::new(repo, MockQueue::default(), MockGenerator::default())
+/// A mock notifier that records the instances it was asked to push.
+#[derive(Clone, Default)]
+struct MockNotifier {
+ notified: Arc<Mutex<Vec<(TargetType, UserAiProjection)>>>,
+}
+
+impl ProjectionNotifier for MockNotifier {
+ async fn notify_updated(
+ &self,
+ target_type: TargetType,
+ instance: &UserAiProjection,
+ ) -> anyhow::Result<()> {
+ self.notified
+ .lock()
+ .unwrap()
+ .push((target_type, instance.clone()));
+ Ok(())
+ }
+}
+
+type TestService = AiProjectionServiceImpl<MockRepo, MockQueue, MockGenerator, MockNotifier>;
+
+/// Builds a service from a repo, using default mock collaborators.
+fn service_with(repo: MockRepo) -> TestService {
+ AiProjectionServiceImpl::new(
+ repo,
+ MockQueue::default(),
+ MockGenerator::default(),
+ MockNotifier::default(),
+ )
}
/// A tiny in-memory mock repository for exercising the service layer.
@@ -70,6 +107,9 @@ fn service_with(repo: MockRepo) -> AiProjectionServiceImpl<MockRepo, MockQueue,
struct MockRepo {
has_permission: bool,
team_ids: Vec<uuid::Uuid>,
+ /// The instance returned by `get_or_create_target_projection`; defaults to
+ /// a fresh cold instance when unset.
+ existing_instance: Option<UserAiProjection>,
created_target_projections: Arc<Mutex<Vec<UserAiProjection>>>,
/// When set, `try_start_processing` reports the pair as already claimed.
start_returns_false: bool,
@@ -78,10 +118,36 @@ struct MockRepo {
statuses: Arc<Mutex<Vec<ProjectionStatus>>>,
stored_results: Arc<Mutex<Vec<String>>>,
stored_errors: Arc<Mutex<Vec<String>>>,
+ upserted_definitions: Arc<Mutex<Vec<AiProjection>>>,
+}
+
+impl MockRepo {
+ /// The instance state `get_target_projection` reports, reflecting the
+ /// mutations recorded so far (result stored -> ready, error stored ->
+ /// error).
+ fn current_instance(&self, ai_projection_id: &str, target_id: &str) -> UserAiProjection {
+ let status = self
+ .statuses
+ .lock()
+ .unwrap()
+ .last()
+ .copied()
+ .unwrap_or(ProjectionStatus::Cold);
+ UserAiProjection {
+ ai_projection_id: ai_projection_id.to_string(),
+ target_id: target_id.to_string(),
+ prompt_hash: test_hash(),
+ status,
+ result: self.stored_results.lock().unwrap().last().cloned(),
+ error: self.stored_errors.lock().unwrap().last().cloned(),
+ generated_at: None,
+ stale_at: None,
+ }
+ }
}
impl AiProjectionRepository for MockRepo {
- async fn get_or_create_projection(
+ async fn upsert_projection_definition(
&self,
id: &str,
prompt: &str,
@@ -89,17 +155,26 @@ impl AiProjectionRepository for MockRepo {
target_type: TargetType,
refresh_cadence: RefreshCadence,
expiry: Expiry,
+ model: Option<&str>,
+ output_schema: Option<&serde_json::Value>,
) -> Result<AiProjection, AiProjectionError> {
- Ok(AiProjection {
+ let projection = AiProjection {
id: id.to_string(),
prompt: prompt.to_string(),
prompt_hash: prompt_hash.to_string(),
target_type,
refresh_cadence,
expiry,
+ model: model.map(str::to_string),
+ output_schema: output_schema.cloned(),
created_at: Utc::now(),
updated_at: Utc::now(),
- })
+ };
+ self.upserted_definitions
+ .lock()
+ .unwrap()
+ .push(projection.clone());
+ Ok(projection)
}
async fn get_or_create_target_projection(
@@ -108,16 +183,19 @@ impl AiProjectionRepository for MockRepo {
target_id: &str,
prompt_hash: &str,
) -> Result<UserAiProjection, AiProjectionError> {
- let target_projection = UserAiProjection {
- ai_projection_id: ai_projection_id.to_string(),
- target_id: target_id.to_string(),
- prompt_hash: prompt_hash.to_string(),
- status: ProjectionStatus::Cold,
- result: None,
- error: None,
- generated_at: None,
- stale_at: None,
- };
+ let target_projection =
+ self.existing_instance
+ .clone()
+ .unwrap_or_else(|| UserAiProjection {
+ ai_projection_id: ai_projection_id.to_string(),
+ target_id: target_id.to_string(),
+ prompt_hash: prompt_hash.to_string(),
+ status: ProjectionStatus::Cold,
+ result: None,
+ error: None,
+ generated_at: None,
+ stale_at: None,
+ });
self.created_target_projections
.lock()
.unwrap()
@@ -125,14 +203,24 @@ impl AiProjectionRepository for MockRepo {
Ok(target_projection)
}
+ async fn get_target_projection(
+ &self,
+ ai_projection_id: &str,
+ target_id: &str,
+ ) -> Result<UserAiProjection, AiProjectionError> {
+ Ok(self.current_instance(ai_projection_id, target_id))
+ }
+
async fn get_projection(&self, id: &str) -> Result<AiProjection, AiProjectionError> {
Ok(AiProjection {
id: id.to_string(),
prompt: TEST_PROMPT.to_string(),
- prompt_hash: hash_prompt(TEST_PROMPT),
+ prompt_hash: test_hash(),
target_type: TargetType::User,
refresh_cadence: RefreshCadence::High,
expiry: Expiry::Day,
+ model: None,
+ output_schema: None,
created_at: Utc::now(),
updated_at: Utc::now(),
})
@@ -166,6 +254,7 @@ impl AiProjectionRepository for MockRepo {
&self,
_ai_projection_id: &str,
_target_id: &str,
+ _prompt_hash: &str,
) -> Result<(), AiProjectionError> {
self.statuses
.lock()
@@ -174,10 +263,23 @@ impl AiProjectionRepository for MockRepo {
Ok(())
}
+ async fn set_projection_refreshing(
+ &self,
+ _ai_projection_id: &str,
+ _target_id: &str,
+ ) -> Result<(), AiProjectionError> {
+ self.statuses
+ .lock()
+ .unwrap()
+ .push(ProjectionStatus::Refreshing);
+ Ok(())
+ }
+
async fn set_projection_result(
&self,
_ai_projection_id: &str,
_target_id: &str,
+ _prompt_hash: &str,
result: &str,
_generated_at: chrono::DateTime<chrono::Utc>,
_stale_at: chrono::DateTime<chrono::Utc>,
@@ -191,6 +293,7 @@ impl AiProjectionRepository for MockRepo {
&self,
_ai_projection_id: &str,
_target_id: &str,
+ _prompt_hash: &str,
error: &str,
) -> Result<(), AiProjectionError> {
self.statuses.lock().unwrap().push(ProjectionStatus::Error);
@@ -221,16 +324,27 @@ fn user_id() -> MacroUserIdStr<'static> {
}
#[test]
-fn hash_prompt_is_deterministic_and_hex() {
- let a = hash_prompt("hello world");
- let b = hash_prompt("hello world");
- let c = hash_prompt("different");
+fn hash_projection_version_is_deterministic_and_hex() {
+ let a = hash_projection_version("hello world", None, None);
+ let b = hash_projection_version("hello world", None, None);
+ let c = hash_projection_version("different", None, None);
assert_eq!(a, b);
assert_ne!(a, c);
assert_eq!(a.len(), 64);
assert!(a.chars().all(|ch| ch.is_ascii_hexdigit()));
}
+#[test]
+fn hash_projection_version_covers_model_and_schema() {
+ let base = hash_projection_version("prompt", None, None);
+ let with_model = hash_projection_version("prompt", Some("cerebras/llama-3.3-70b"), None);
+ let schema = serde_json::json!({"type": "object"});
+ let with_schema = hash_projection_version("prompt", None, Some(&schema));
+ assert_ne!(base, with_model);
+ assert_ne!(base, with_schema);
+ assert_ne!(with_model, with_schema);
+}
+
#[tokio::test]
async fn has_professional_features_delegates_to_repo() {
let service = service_with(MockRepo {
@@ -253,6 +367,10 @@ fn user_params(id: &str, prompt: &str) -> UpsertProjectionParams {
target_type: TargetType::User,
refresh_cadence: RefreshCadence::High,
expiry: Expiry::Day,
+ model: None,
+ output_schema: None,
+ await_generation: false,
+ regenerate: false,
}
}
@@ -273,10 +391,7 @@ async fn upsert_projection_creates_cold_target_instance_for_user() {
// The user target id is resolved from the authenticated user.
assert_eq!(target_projection.target_id, "macro|[email protected]");
assert_eq!(target_projection.status, ProjectionStatus::Cold);
- assert_eq!(
- target_projection.prompt_hash,
- hash_prompt("What is important?")
- );
+ assert_eq!(target_projection.prompt_hash, test_hash());
assert_eq!(repo.created_target_projections.lock().unwrap().len(), 1);
}
@@ -284,7 +399,12 @@ async fn upsert_projection_creates_cold_target_instance_for_user() {
async fn upsert_projection_enqueues_materialization_for_cold_instance() {
let repo = MockRepo::default();
let queue = MockQueue::default();
- let service = AiProjectionServiceImpl::new(repo, queue.clone(), MockGenerator::default());
+ let service = AiProjectionServiceImpl::new(
+ repo,
+ queue.clone(),
+ MockGenerator::default(),
+ MockNotifier::default(),
+ );
service
.upsert_projection(
@@ -298,26 +418,181 @@ async fn upsert_projection_enqueues_materialization_for_cold_instance() {
assert_eq!(enqueued.len(), 1);
assert_eq!(enqueued[0].ai_projection_id, "inbox/important");
assert_eq!(enqueued[0].target_id, "macro|[email protected]");
- assert_eq!(enqueued[0].prompt_hash, hash_prompt("What is important?"));
+ assert_eq!(enqueued[0].prompt_hash, test_hash());
+}
+
+#[tokio::test]
+async fn upsert_projection_passes_model_and_schema_into_version_hash() {
+ let repo = MockRepo::default();
+ let service = service_with(repo.clone());
+
+ let schema =
+ serde_json::json!({"type": "object", "properties": {"answer": {"type": "string"}}});
+ let mut params = user_params("inbox/important", TEST_PROMPT);
+ params.model = Some("cerebras/llama-3.3-70b".to_string());
+ params.output_schema = Some(schema.clone());
+
+ let target_projection = service.upsert_projection(&user_id(), params).await.unwrap();
+
+ let expected =
+ hash_projection_version(TEST_PROMPT, Some("cerebras/llama-3.3-70b"), Some(&schema));
+ assert_eq!(target_projection.prompt_hash, expected);
+
+ let definitions = repo.upserted_definitions.lock().unwrap();
+ assert_eq!(
+ definitions[0].model.as_deref(),
+ Some("cerebras/llama-3.3-70b")
+ );
+ assert_eq!(definitions[0].output_schema.as_ref(), Some(&schema));
+}
+
+#[tokio::test]
+async fn upsert_projection_returns_ready_instance_without_regenerating() {
+ let ready = UserAiProjection {
+ ai_projection_id: "inbox/important".to_string(),
+ target_id: "macro|[email protected]".to_string(),
+ prompt_hash: test_hash(),
+ status: ProjectionStatus::Ready,
+ result: Some("cached".to_string()),
+ error: None,
+ generated_at: Some(Utc::now()),
+ stale_at: Some(Utc::now()),
+ };
+ let repo = MockRepo {
+ existing_instance: Some(ready),
+ ..Default::default()
+ };
+ let queue = MockQueue::default();
+ let generator = MockGenerator::default();
+ let service = AiProjectionServiceImpl::new(
+ repo,
+ queue.clone(),
+ generator.clone(),
+ MockNotifier::default(),
+ );
+
+ let target_projection = service
+ .upsert_projection(&user_id(), user_params("inbox/important", TEST_PROMPT))
+ .await
+ .unwrap();
+
+ assert_eq!(target_projection.status, ProjectionStatus::Ready);
+ assert_eq!(target_projection.result.as_deref(), Some("cached"));
+ assert!(queue.enqueued.lock().unwrap().is_empty());
+ assert!(generator.calls.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn upsert_projection_regenerate_marks_refreshing_and_enqueues() {
+ let ready = UserAiProjection {
+ ai_projection_id: "inbox/important".to_string(),
+ target_id: "macro|[email protected]".to_string(),
+ prompt_hash: test_hash(),
+ status: ProjectionStatus::Ready,
+ result: Some("cached".to_string()),
+ error: None,
+ generated_at: Some(Utc::now()),
+ stale_at: Some(Utc::now()),
+ };
+ let repo = MockRepo {
+ existing_instance: Some(ready),
+ ..Default::default()
+ };
+ let queue = MockQueue::default();
+ let service = AiProjectionServiceImpl::new(
+ repo.clone(),
+ queue.clone(),
+ MockGenerator::default(),
+ MockNotifier::default(),
+ );
+
+ let mut params = user_params("inbox/important", TEST_PROMPT);
+ params.regenerate = true;
+
+ let target_projection = service.upsert_projection(&user_id(), params).await.unwrap();
+
+ // The stale result stays visible while the regeneration is queued.
+ assert_eq!(target_projection.status, ProjectionStatus::Refreshing);
+ assert_eq!(target_projection.result.as_deref(), Some("cached"));
+ assert_eq!(
+ repo.statuses.lock().unwrap().as_slice(),
+ [ProjectionStatus::Refreshing]
+ );
+ assert_eq!(queue.enqueued.lock().unwrap().len(), 1);
+}
+
+#[tokio::test]
+async fn upsert_projection_await_generates_inline_and_returns_ready() {
+ let repo = MockRepo::default();
+ let queue = MockQueue::default();
+ let generator = MockGenerator {
+ response: "inline result".to_string(),
+ ..Default::default()
+ };
+ let notifier = MockNotifier::default();
+ let service =
+ AiProjectionServiceImpl::new(repo.clone(), queue.clone(), generator, notifier.clone());
+
+ let mut params = user_params("inbox/important", TEST_PROMPT);
+ params.await_generation = true;
+
+ let target_projection = service.upsert_projection(&user_id(), params).await.unwrap();
+
+ // Inline generation finished before the response was returned.
+ assert_eq!(target_projection.status, ProjectionStatus::Ready);
+ assert_eq!(target_projection.result.as_deref(), Some("inline result"));
+ // Nothing was enqueued; materialization happened in the request.
+ assert!(queue.enqueued.lock().unwrap().is_empty());
+ // Other connected clients still get the gateway push.
+ assert_eq!(notifier.notified.lock().unwrap().len(), 1);
+}
+
+#[tokio::test]
+async fn upsert_projection_await_returns_error_state_on_generation_failure() {
+ let repo = MockRepo::default();
+ let generator = MockGenerator {
+ fail: true,
+ ..Default::default()
+ };
+ let service = AiProjectionServiceImpl::new(
+ repo.clone(),
+ MockQueue::default(),
+ generator,
+ MockNotifier::default(),
+ );
+
+ let mut params = user_params("inbox/important", TEST_PROMPT);
+ params.await_generation = true;
+
+ let target_projection = service.upsert_projection(&user_id(), params).await.unwrap();
+
+ // The failure is surfaced on the instance rather than failing the request.
+ assert_eq!(target_projection.status, ProjectionStatus::Error);
+ assert!(target_projection.error.is_some());
}
fn materialize_message() -> AiProjectionQueueMessage {
AiProjectionQueueMessage {
ai_projection_id: "inbox/important".to_string(),
target_id: "macro|[email protected]".to_string(),
- prompt_hash: hash_prompt(TEST_PROMPT),
+ prompt_hash: test_hash(),
}
}
#[tokio::test]
-async fn materialize_generates_and_stores_result() {
+async fn materialize_generates_stores_result_and_notifies() {
let repo = MockRepo::default();
let generator = MockGenerator {
response: "the materialized result".to_string(),
..Default::default()
};
- let service =
- AiProjectionServiceImpl::new(repo.clone(), MockQueue::default(), generator.clone());
+ let notifier = MockNotifier::default();
+ let service = AiProjectionServiceImpl::new(
+ repo.clone(),
+ MockQueue::default(),
+ generator.clone(),
+ notifier.clone(),
+ );
service.materialize(materialize_message()).await.unwrap();
@@ -339,6 +614,16 @@ async fn materialize_generates_and_stores_result() {
// The processing claim was acquired and released.
assert_eq!(repo.started.lock().unwrap().len(), 1);
assert_eq!(repo.finished.lock().unwrap().len(), 1);
+
+ // Connected clients were pushed the ready instance.
+ let notified = notifier.notified.lock().unwrap();
+ assert_eq!(notified.len(), 1);
+ assert_eq!(notified[0].0, TargetType::User);
+ assert_eq!(notified[0].1.status, ProjectionStatus::Ready);
+ assert_eq!(
+ notified[0].1.result.as_deref(),
+ Some("the materialized result")
+ );
}
#[tokio::test]
@@ -348,25 +633,59 @@ async fn materialize_skips_when_already_processing() {
..Default::default()
};
let generator = MockGenerator::default();
- let service =
- AiProjectionServiceImpl::new(repo.clone(), MockQueue::default(), generator.clone());
+ let notifier = MockNotifier::default();
+ let service = AiProjectionServiceImpl::new(
+ repo.clone(),
+ MockQueue::default(),
+ generator.clone(),
+ notifier.clone(),
+ );
service.materialize(materialize_message()).await.unwrap();
- // The generator never ran and nothing was stored or released.
+ // The generator never ran and nothing was stored, released, or pushed.
assert!(generator.calls.lock().unwrap().is_empty());
assert!(repo.statuses.lock().unwrap().is_empty());
assert!(repo.finished.lock().unwrap().is_empty());
+ assert!(notifier.notified.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn materialize_skips_stale_version_messages() {
+ let repo = MockRepo::default();
+ let generator = MockGenerator::default();
+ let service = AiProjectionServiceImpl::new(
+ repo.clone(),
+ MockQueue::default(),
+ generator.clone(),
+ MockNotifier::default(),
+ );
+
+ // The definition's hash (test_hash) no longer matches this older message.
+ let mut message = materialize_message();
+ message.prompt_hash = hash_projection_version("an older prompt", None, None);
+
+ service.materialize(message).await.unwrap();
+
+ // The claim was never taken and the generator never ran.
+ assert!(repo.started.lock().unwrap().is_empty());
+ assert!(generator.calls.lock().unwrap().is_empty());
}
#[tokio::test]
-async fn materialize_on_error_records_error_releases_claim_and_returns_err() {
+async fn materialize_on_error_records_error_notifies_and_returns_err() {
let repo = MockRepo::default();
let generator = MockGenerator {
fail: true,
..Default::default()
};
- let service = AiProjectionServiceImpl::new(repo.clone(), MockQueue::default(), generator);
+ let notifier = MockNotifier::default();
+ let service = AiProjectionServiceImpl::new(
+ repo.clone(),
+ MockQueue::default(),
+ generator,
+ notifier.clone(),
+ );
let err = service
.materialize(materialize_message())
@@ -382,6 +701,11 @@ async fn materialize_on_error_records_error_releases_claim_and_returns_err() {
repo.statuses.lock().unwrap().as_slice(),
[ProjectionStatus::Loading, ProjectionStatus::Error]
);
+
+ // Connected clients were pushed the errored instance.
+ let notified = notifier.notified.lock().unwrap();
+ assert_eq!(notified.len(), 1);
+ assert_eq!(notified[0].1.status, ProjectionStatus::Error);
}
#[tokio::test]
@@ -402,6 +726,10 @@ async fn upsert_projection_resolves_team_target_from_user() {
target_type: TargetType::Team,
refresh_cadence: RefreshCadence::Medium,
expiry: Expiry::Week,
+ model: None,
+ output_schema: None,
+ await_generation: false,
+ regenerate: false,
},
)
.await
@@ -412,19 +740,22 @@ async fn upsert_projection_resolves_team_target_from_user() {
#[tokio::test]
async fn upsert_projection_team_target_errors_without_exactly_one_team() {
+ let team_params = || UpsertProjectionParams {
+ id: "team/focus".to_string(),
+ prompt: "What is my team focused on?".to_string(),
+ target_type: TargetType::Team,
+ refresh_cadence: RefreshCadence::Medium,
+ expiry: Expiry::Week,
+ model: None,
+ output_schema: None,
+ await_generation: false,
+ regenerate: false,
+ };
+
// Zero teams -> bad request.
let service = service_with(MockRepo::default());
let err = service
- .upsert_projection(
- &user_id(),
- UpsertProjectionParams {
- id: "team/focus".to_string(),
- prompt: "What is my team focused on?".to_string(),
- target_type: TargetType::Team,
- refresh_cadence: RefreshCadence::Medium,
- expiry: Expiry::Week,
- },
- )
+ .upsert_projection(&user_id(), team_params())
.await
.unwrap_err();
assert!(matches!(err, UpsertProjectionError::BadRequest(_)));
@@ -435,16 +766,7 @@ async fn upsert_projection_team_target_errors_without_exactly_one_team() {
..Default::default()
});
let err = service
- .upsert_projection(
- &user_id(),
- UpsertProjectionParams {
- id: "team/focus".to_string(),
- prompt: "What is my team focused on?".to_string(),
- target_type: TargetType::Team,
- refresh_cadence: RefreshCadence::Medium,
- expiry: Expiry::Week,
- },
- )
+ .upsert_projection(&user_id(), team_params())
.await
.unwrap_err();
assert!(matches!(err, UpsertProjectionError::BadRequest(_)));
diff --git a/rust/cloud-storage/ai_projections/src/domain/model.rs b/rust/cloud-storage/ai_projections/src/domain/model.rs
index 3e601ef4f3..d7d2399a87 100644
--- a/rust/cloud-storage/ai_projections/src/domain/model.rs
+++ b/rust/cloud-storage/ai_projections/src/domain/model.rs
@@ -196,7 +196,8 @@ pub struct AiProjection {
pub id: String,
/// The prompt used to materialize the projection.
pub prompt: String,
- /// A hash of the prompt, used to version cached instances.
+ /// A hash of the generation recipe (prompt, model, and output schema), used
+ /// to version cached instances.
pub prompt_hash: String,
/// Whether this projection is materialized per user or per team.
pub target_type: TargetType,
@@ -204,6 +205,12 @@ pub struct AiProjection {
pub refresh_cadence: RefreshCadence,
/// How long the projection remains active without being requested.
pub expiry: Expiry,
+ /// Optional `provider/model` id used for generation (e.g.
+ /// `cerebras/llama-3.3-70b`). Falls back to the default model when absent.
+ pub model: Option<String>,
+ /// Optional JSON schema the generated result must conform to. When set the
+ /// result is the JSON serialization of a value matching this schema.
+ pub output_schema: Option<serde_json::Value>,
/// When the definition was created.
pub created_at: DateTime<Utc>,
/// When the definition was last updated.
@@ -248,6 +255,15 @@ pub struct UpsertProjectionParams {
pub refresh_cadence: RefreshCadence,
/// How long the projection remains active without being requested.
pub expiry: Expiry,
+ /// Optional `provider/model` id used for generation.
+ pub model: Option<String>,
+ /// Optional JSON schema the generated result must conform to.
+ pub output_schema: Option<serde_json::Value>,
+ /// When `true` and the instance needs generation, materialize inline and
+ /// return the finished state instead of enqueueing and returning early.
+ pub await_generation: bool,
+ /// When `true`, regenerate even if a cached result already exists.
+ pub regenerate: bool,
}
/// Errors for ai projection storage operations.
diff --git a/rust/cloud-storage/ai_projections/src/domain/projection_generator.rs b/rust/cloud-storage/ai_projections/src/domain/projection_generator.rs
index 9788a0442a..293a63a43a 100644
--- a/rust/cloud-storage/ai_projections/src/domain/projection_generator.rs
+++ b/rust/cloud-storage/ai_projections/src/domain/projection_generator.rs
@@ -4,6 +4,21 @@ use macro_user_id::user_id::MacroUserIdStr;
use crate::domain::model::AiProjectionError;
+/// The inputs for a single projection generation run.
+#[derive(Debug, Clone, Copy)]
+pub struct GenerationRequest<'a> {
+ /// The projection definition id, used to name the output schema.
+ pub projection_id: &'a str,
+ /// The prompt to run against the AI toolset.
+ pub prompt: &'a str,
+ /// Optional `provider/model` id (e.g. `cerebras/llama-3.3-70b`). The
+ /// default model is used when absent or unroutable.
+ pub model: Option<&'a str>,
+ /// Optional JSON schema the result must conform to. When set, the returned
+ /// string is the JSON serialization of a value matching this schema.
+ pub output_schema: Option<&'a serde_json::Value>,
+}
+
/// Runs a projection's prompt against the AI toolset on behalf of a user and
/// returns the generated result text.
///
@@ -11,11 +26,11 @@ use crate::domain::model::AiProjectionError;
/// domain crate: the service depends on this trait, and an outbound adapter
/// (`outbound::agent_generator`) implements it using the shared agent loop.
pub trait ProjectionGenerator: Clone + Send + Sync + 'static {
- /// Runs `prompt` as `user_id` against the AI toolset, returning the
- /// generated result text.
+ /// Runs the request's prompt as `user_id` against the AI toolset, returning
+ /// the generated result text (or schema-conforming JSON).
fn generate(
&self,
user_id: &MacroUserIdStr<'_>,
- prompt: &str,
+ request: GenerationRequest<'_>,
) -> impl Future<Output = Result<String, AiProjectionError>> + Send;
}
diff --git a/rust/cloud-storage/ai_projections/src/domain/projection_notifier.rs b/rust/cloud-storage/ai_projections/src/domain/projection_notifier.rs
new file mode 100644
index 0000000000..7b02aafcde
--- /dev/null
+++ b/rust/cloud-storage/ai_projections/src/domain/projection_notifier.rs
@@ -0,0 +1,15 @@
+//! Outbound port for pushing projection state changes to connected clients.
+
+use crate::domain::model::{TargetType, UserAiProjection};
+
+/// Pushes a projection instance's latest state to the target's connected
+/// clients (e.g. through the connection gateway) after a materialization
+/// attempt completes, so the frontend can update without polling.
+pub trait ProjectionNotifier: Clone + Send + Sync + 'static {
+ /// Notifies the target's connected clients that `instance` changed.
+ fn notify_updated(
+ &self,
+ target_type: TargetType,
+ instance: &UserAiProjection,
+ ) -> impl Future<Output = anyhow::Result<()>> + Send;
+}
diff --git a/rust/cloud-storage/ai_projections/src/inbound/axum_router/test.rs b/rust/cloud-storage/ai_projections/src/inbound/axum_router/test.rs
index 18729ec3ed..3c0b848960 100644
--- a/rust/cloud-storage/ai_projections/src/inbound/axum_router/test.rs
+++ b/rust/cloud-storage/ai_projections/src/inbound/axum_router/test.rs
@@ -1,6 +1,6 @@
//! Integration tests for the ai projections axum router.
-use std::sync::Arc;
+use std::sync::{Arc, Mutex};
use axum::{Extension, http::StatusCode};
use http_body_util::BodyExt;
@@ -17,9 +17,10 @@ use crate::domain::{
},
};
-#[derive(Clone)]
+#[derive(Clone, Default)]
struct MockService {
has_permission: bool,
+ received_params: Arc<Mutex<Vec<UpsertProjectionParams>>>,
}
impl AiProjectionService for MockService {
@@ -28,8 +29,10 @@ impl AiProjectionService for MockService {
user_id: &MacroUserIdStr<'_>,
params: UpsertProjectionParams,
) -> Result<UserAiProjection, UpsertProjectionError> {
+ let id = params.id.clone();
+ self.received_params.lock().unwrap().push(params);
Ok(UserAiProjection {
- ai_projection_id: params.id,
+ ai_projection_id: id,
target_id: user_id.as_ref().to_string(),
prompt_hash: "hash".to_string(),
status: ProjectionStatus::Cold,
@@ -65,9 +68,14 @@ fn test_user_context() -> UserContext {
}
fn build_router(has_permission: bool) -> axum::Router {
- let state = AiProjectionRouterState {
- service: Arc::new(MockService { has_permission }),
- };
+ build_router_with(Arc::new(MockService {
+ has_permission,
+ ..Default::default()
+ }))
+}
+
+fn build_router_with(service: Arc<MockService>) -> axum::Router {
+ let state = AiProjectionRouterState { service };
ai_projections_router(state).layer(Extension(test_user_context()))
}
@@ -110,3 +118,45 @@ async fn upsert_projection_is_forbidden_without_professional_features() {
let response = app.oneshot(post_request()).await.unwrap();
assert_eq!(response.status(), StatusCode::FORBIDDEN);
}
+
+#[tokio::test]
+async fn upsert_projection_passes_optional_fields_to_the_service() {
+ let service = Arc::new(MockService {
+ has_permission: true,
+ ..Default::default()
+ });
+ let app = build_router_with(service.clone());
+
+ let request = axum::http::Request::builder()
+ .uri("/ai-projections")
+ .method("POST")
+ .header("content-type", "application/json")
+ .body(axum::body::Body::from(
+ serde_json::json!({
+ "id": "inbox/important",
+ "prompt": "What is important?",
+ "target_type": "user",
+ "refresh_cadence": "high",
+ "expiry": "day",
+ "model": "cerebras/llama-3.3-70b",
+ "output_schema": {"type": "object"},
+ "await": true,
+ "regenerate": true
+ })
+ .to_string(),
+ ))
+ .unwrap();
+
+ let response = app.oneshot(request).await.unwrap();
+ assert_eq!(response.status(), StatusCode::OK);
+
+ let received = service.received_params.lock().unwrap();
+ assert_eq!(received.len(), 1);
+ assert_eq!(received[0].model.as_deref(), Some("cerebras/llama-3.3-70b"));
+ assert_eq!(
+ received[0].output_schema,
+ Some(serde_json::json!({"type": "object"}))
+ );
+ assert!(received[0].await_generation);
+ assert!(received[0].regenerate);
+}
diff --git a/rust/cloud-storage/ai_projections/src/inbound/axum_router/upsert_projection.rs b/rust/cloud-storage/ai_projections/src/inbound/axum_router/upsert_projection.rs
index 8e243e151f..cb23a0da8e 100644
--- a/rust/cloud-storage/ai_projections/src/inbound/axum_router/upsert_projection.rs
+++ b/rust/cloud-storage/ai_projections/src/inbound/axum_router/upsert_projection.rs
@@ -28,6 +28,25 @@ pub struct UpsertProjectionRequest {
pub refresh_cadence: RefreshCadence,
/// How long the projection remains active without being requested.
pub expiry: Expiry,
+ /// Optional `provider/model` id used for generation (e.g.
+ /// `cerebras/llama-3.3-70b`). The default model is used when absent.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub model: Option<String>,
+ /// Optional JSON schema the generated result must conform to. When set,
+ /// `data` holds the JSON serialization of a conforming value. Enforcement
+ /// is prompted (non-strict), so it works across providers.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ #[schema(value_type = Option<Object>)]
+ pub output_schema: Option<serde_json::Value>,
+ /// When `true` and generation is needed (cold instance or `regenerate`),
+ /// the server generates inline and responds with the finished result
+ /// instead of returning immediately and pushing an update through the
+ /// connection gateway.
+ #[serde(default, rename = "await")]
+ pub await_generation: bool,
+ /// When `true`, regenerate even if a cached result exists.
+ #[serde(default)]
+ pub regenerate: bool,
}
/// The current state of a user's projection instance.
@@ -37,8 +56,11 @@ pub struct ProjectionStateResponse {
pub id: String,
/// The materialization status.
pub status: ProjectionStatus,
- /// The cached result, if any.
+ /// The cached result, if any. JSON-encoded when the projection defines an
+ /// `output_schema`.
pub data: Option<String>,
+ /// The most recent materialization error, if any.
+ pub error: Option<String>,
/// When the result was generated.
pub generated_at: Option<DateTime<Utc>>,
/// When the result becomes stale.
@@ -51,13 +73,15 @@ impl From<UserAiProjection> for ProjectionStateResponse {
id: instance.ai_projection_id,
status: instance.status,
data: instance.result,
+ error: instance.error,
generated_at: instance.generated_at,
stale_at: instance.stale_at,
}
}
}
-/// Gets or creates an ai projection and the requesting user's cold instance.
+/// Gets or creates an ai projection and the requesting user's instance,
+/// triggering (or awaiting) materialization when needed.
#[utoipa::path(
post,
path = "/ai-projections",
@@ -86,6 +110,10 @@ pub async fn handler<T: AiProjectionService>(
target_type: req.target_type,
refresh_cadence: req.refresh_cadence,
expiry: req.expiry,
+ model: req.model,
+ output_schema: req.output_schema,
+ await_generation: req.await_generation,
+ regenerate: req.regenerate,
},
)
.await?;
diff --git a/rust/cloud-storage/ai_projections/src/lib.rs b/rust/cloud-storage/ai_projections/src/lib.rs
index 7f1eb3034a..8e3f9319a7 100644
--- a/rust/cloud-storage/ai_projections/src/lib.rs
+++ b/rust/cloud-storage/ai_projections/src/lib.rs
@@ -7,10 +7,34 @@
//! `ai_projection` table, while each user's cached instance lives in the
//! `user_ai_projection` table.
//!
+//! # Lifecycle
+//!
+//! `POST /ai-projections` is both create and read: it upserts the definition
+//! and the caller's instance, returning the cached state. A cold instance (or
+//! a `regenerate: true` request) triggers materialization — asynchronously via
+//! `ai_projection_queue` by default, or inline when the request sets
+//! `await: true`. Completed (or failed) materializations are pushed to the
+//! target's connected clients through the connection gateway as
+//! `ai_projection_updated` messages, so the frontend never polls.
+//!
+//! The definition's `prompt_hash` versions the whole generation recipe
+//! (prompt, optional `model` override, optional `output_schema`): re-upserting
+//! with any of those changed revises the definition and resets instances to
+//! cold on their next request. Worker writes are scoped to the message's hash
+//! so results for outdated versions are discarded. A scheduled refresh lambda
+//! (`ai_projections_refresh_handler`) deletes inactive instances and
+//! re-enqueues stale ones per cadence.
+//!
+//! When `output_schema` is set, generation is two-phase: the tool-enabled
+//! agent loop gathers context, then a prompted (non-strict) structured
+//! completion distills it into schema-conforming JSON — this works across all
+//! routed providers (Anthropic, OpenAI, Cerebras, ...).
+//!
//! # Architecture
//!
//! - **domain**: Domain models, ports (traits), and the service implementation
-//! - **outbound**: Adapters for external dependencies (PostgreSQL)
+//! - **outbound**: Adapters for external dependencies (PostgreSQL, SQS, the
+//! agent loop, the connection gateway)
//! - **inbound**: Adapters for incoming requests (Axum handlers)
/// The domain module contains the domain logic for ai projections
diff --git a/rust/cloud-storage/ai_projections/src/outbound.rs b/rust/cloud-storage/ai_projections/src/outbound.rs
index 9d0f5644f0..058c29f830 100644
--- a/rust/cloud-storage/ai_projections/src/outbound.rs
+++ b/rust/cloud-storage/ai_projections/src/outbound.rs
@@ -3,4 +3,5 @@
#[cfg(feature = "agent")]
pub mod agent_generator;
pub mod ai_projection_repo;
+pub mod gateway_notifier;
pub mod sqs_queue;
diff --git a/rust/cloud-storage/ai_projections/src/outbound/agent_generator.rs b/rust/cloud-storage/ai_projections/src/outbound/agent_generator.rs
index 8cc4223da3..392e8264a6 100644
--- a/rust/cloud-storage/ai_projections/src/outbound/agent_generator.rs
+++ b/rust/cloud-storage/ai_projections/src/outbound/agent_generator.rs
@@ -4,21 +4,32 @@
//! Mirrors `channel_bots::outbound::AgentLoopResponder`: it runs the projection
//! prompt through the same agent loop and toolset used by channel bots and the
//! document storage service, attributing usage to [`AiFeature::AiProjection`].
+//!
+//! When the projection defines an `output_schema`, generation is two-phase
+//! (mirroring the `/structured-completion` endpoint): the agent loop first
+//! gathers information with tools, then a prompted structured completion
+//! (`agent::structured_output`) distills the gathered context into JSON
+//! conforming to the schema. Prompted JSON works with every routed provider —
+//! Anthropic, OpenAI, and OpenAI-compatible providers like Cerebras — without
+//! requiring strict schema support.
use std::sync::Arc;
-use agent::{AgentLoop, StreamPart, to_rig_messages};
+use agent::{AgentLoop, StreamAccumulator, to_rig_messages};
+use agent::{PredefinedModel, structured_output::DynamicSchema};
use ai_tools::{AiToolSet, ToolServiceContext, ToolSetWithPrompt};
use ai_usage::{AiFeature, UsageContext};
use futures::StreamExt;
use macro_user_id::{cowlike::CowLike, user_id::MacroUserIdStr};
-use crate::domain::{model::AiProjectionError, projection_generator::ProjectionGenerator};
+use crate::domain::{
+ model::AiProjectionError,
+ projection_generator::{GenerationRequest, ProjectionGenerator},
+};
/// [`ProjectionGenerator`] backed by the in-process agent loop and AI toolset.
#[derive(Clone)]
pub struct AgentProjectionGenerator {
- agent_loop: Arc<AgentLoop>,
tool_context: Arc<ToolServiceContext>,
toolset: Arc<AiToolSet>,
system_prompt: Arc<str>,
@@ -30,21 +41,19 @@ impl AgentProjectionGenerator {
/// [`ai_tools::all_tools`].
pub fn new(tool_context: ToolServiceContext, tools: ToolSetWithPrompt) -> Self {
Self {
- agent_loop: Arc::new(AgentLoop::new(tool_context.recorder.clone())),
tool_context: Arc::new(tool_context),
toolset: tools.toolset,
system_prompt: tools.prompt.to_string().into(),
}
}
-}
-impl ProjectionGenerator for AgentProjectionGenerator {
- #[tracing::instrument(skip(self, prompt), fields(user_id = %user_id.as_ref()), err)]
- async fn generate(
+ /// Runs the agent loop over the prompt as `user_id`, returning the yielded
+ /// stream parts (text, tool calls/responses) for downstream use.
+ async fn run_agent_loop(
&self,
user_id: &MacroUserIdStr<'_>,
- prompt: &str,
- ) -> Result<String, AiProjectionError> {
+ request: &GenerationRequest<'_>,
+ ) -> Result<StreamAccumulator, AiProjectionError> {
let usage_ctx = UsageContext::new(AiFeature::AiProjection, user_id.clone().into_owned());
// Carry the feature on the context so tool-spawned subagents attribute
@@ -55,8 +64,12 @@ impl ProjectionGenerator for AgentProjectionGenerator {
let toolset: Arc<dyn ai_toolset::ToolSet<ToolServiceContext> + Send + Sync> =
self.toolset.clone();
- let mut session = self
- .agent_loop
+ let mut agent_loop = AgentLoop::new(self.tool_context.recorder.clone());
+ if let Some(model) = request.model {
+ agent_loop = agent_loop.with_model(model);
+ }
+
+ let mut session = agent_loop
.session(
toolset,
Arc::new(tool_context),
@@ -67,7 +80,7 @@ impl ProjectionGenerator for AgentProjectionGenerator {
let messages = vec![agent::types::ChatMessage {
role: agent::types::Role::User,
- content: agent::types::ChatMessageContent::Text(prompt.to_string()),
+ content: agent::types::ChatMessageContent::Text(request.prompt.to_string()),
attachments: None,
}];
@@ -76,14 +89,107 @@ impl ProjectionGenerator for AgentProjectionGenerator {
.await
.map_err(|e| AiProjectionError::Generation(e.to_string()))?;
- let mut text = String::new();
+ let mut accumulator = StreamAccumulator::new();
while let Some(part) = stream.next().await {
let part = part.map_err(|e| AiProjectionError::Generation(e.to_string()))?;
- if let StreamPart::Content(chunk) = part {
- text.push_str(&chunk);
- }
+ accumulator.push(part);
+ }
+
+ Ok(accumulator)
+ }
+
+ /// Distills the agent loop's gathered context into JSON conforming to
+ /// `output_schema` via a prompted (non-strict) structured completion.
+ async fn structured_result(
+ &self,
+ user_id: &MacroUserIdStr<'_>,
+ request: &GenerationRequest<'_>,
+ accumulator: StreamAccumulator,
+ ) -> Result<String, AiProjectionError> {
+ let output_schema = request
+ .output_schema
+ .expect("structured_result requires an output schema");
+
+ let conversation = vec![
+ agent::types::ChatMessage {
+ role: agent::types::Role::User,
+ content: agent::types::ChatMessageContent::Text(request.prompt.to_string()),
+ attachments: None,
+ },
+ agent::types::ChatMessage {
+ role: agent::types::Role::Assistant,
+ content: agent::types::ChatMessageContent::AssistantMessageParts(
+ accumulator.into_parts(),
+ ),
+ attachments: None,
+ },
+ agent::types::ChatMessage {
+ role: agent::types::Role::User,
+ content: agent::types::ChatMessageContent::Text(
+ "Based on the information gathered above, produce a structured response \
+ matching the required schema."
+ .to_string(),
+ ),
+ attachments: None,
+ },
+ ];
+
+ let model = request
+ .model
+ .map(str::to_string)
+ .unwrap_or_else(|| PredefinedModel::default().to_string());
+
+ let value = agent::structured_output::dynamic_structured_completion(
+ model,
+ &self.system_prompt,
+ to_rig_messages(&conversation),
+ DynamicSchema {
+ schema: output_schema.clone(),
+ name: request.projection_id.to_string(),
+ description: None,
+ },
+ self.tool_context.recorder.as_ref(),
+ UsageContext::new(AiFeature::AiProjection, user_id.clone().into_owned()),
+ )
+ .await
+ .map_err(|e| AiProjectionError::Generation(e.to_string()))?;
+
+ serde_json::to_string(&value).map_err(|e| AiProjectionError::Generation(e.to_string()))
+ }
+}
+
+impl ProjectionGenerator for AgentProjectionGenerator {
+ #[tracing::instrument(
+ skip(self, request),
+ fields(
+ user_id = %user_id.as_ref(),
+ projection_id = %request.projection_id,
+ model = ?request.model,
+ structured = request.output_schema.is_some(),
+ ),
+ err
+ )]
+ async fn generate(
+ &self,
+ user_id: &MacroUserIdStr<'_>,
+ request: GenerationRequest<'_>,
+ ) -> Result<String, AiProjectionError> {
+ let accumulator = self.run_agent_loop(user_id, &request).await?;
+
+ if request.output_schema.is_some() {
+ return self.structured_result(user_id, &request, accumulator).await;
}
+ // Free-text projection: concatenate the loop's text content.
+ let text: String = accumulator
+ .into_parts()
+ .into_iter()
+ .filter_map(|part| match part {
+ agent::types::AssistantMessagePart::Text { text } => Some(text),
+ _ => None,
+ })
+ .collect();
+
Ok(text.trim().to_string())
}
}
diff --git a/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo.rs b/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo.rs
index 3102e2a6a7..3d767386e0 100644
--- a/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo.rs
+++ b/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo.rs
@@ -30,8 +30,8 @@ impl AiProjectionRepositoryImpl {
}
impl AiProjectionRepository for AiProjectionRepositoryImpl {
- #[tracing::instrument(skip(self), err)]
- async fn get_or_create_projection(
+ #[tracing::instrument(skip(self, prompt, output_schema), err)]
+ async fn upsert_projection_definition(
&self,
id: &str,
prompt: &str,
@@ -39,14 +39,28 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
target_type: TargetType,
refresh_cadence: RefreshCadence,
expiry: Expiry,
+ model: Option<&str>,
+ output_schema: Option<&serde_json::Value>,
) -> Result<AiProjection, AiProjectionError> {
- // Get-or-create: insert if absent, leave existing rows untouched, then
- // read back the canonical row.
+ // Insert if absent; revise an existing definition only when something
+ // actually changed so routine requests don't churn the row.
sqlx::query!(
r#"
- INSERT INTO ai_projection (id, prompt, prompt_hash, target_type, refresh_cadence, expiry)
- VALUES ($1, $2, $3, $4, $5, $6)
- ON CONFLICT (id) DO NOTHING
+ INSERT INTO ai_projection (id, prompt, prompt_hash, target_type, refresh_cadence, expiry, model, output_schema)
+ VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+ ON CONFLICT (id) DO UPDATE SET
+ prompt = EXCLUDED.prompt,
+ prompt_hash = EXCLUDED.prompt_hash,
+ target_type = EXCLUDED.target_type,
+ refresh_cadence = EXCLUDED.refresh_cadence,
+ expiry = EXCLUDED.expiry,
+ model = EXCLUDED.model,
+ output_schema = EXCLUDED.output_schema,
+ updated_at = NOW()
+ WHERE ai_projection.prompt_hash IS DISTINCT FROM EXCLUDED.prompt_hash
+ OR ai_projection.target_type IS DISTINCT FROM EXCLUDED.target_type
+ OR ai_projection.refresh_cadence IS DISTINCT FROM EXCLUDED.refresh_cadence
+ OR ai_projection.expiry IS DISTINCT FROM EXCLUDED.expiry
"#,
id,
prompt,
@@ -54,6 +68,8 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
target_type.to_string(),
refresh_cadence.to_string(),
expiry.to_string(),
+ model,
+ output_schema,
)
.execute(&self.pool)
.await
@@ -61,7 +77,7 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
let row = sqlx::query!(
r#"
- SELECT id, prompt, prompt_hash, target_type, refresh_cadence, expiry, created_at, updated_at
+ SELECT id, prompt, prompt_hash, target_type, refresh_cadence, expiry, model, output_schema, created_at, updated_at
FROM ai_projection
WHERE id = $1
"#,
@@ -78,6 +94,8 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
target_type: row.target_type.parse()?,
refresh_cadence: row.refresh_cadence.parse()?,
expiry: row.expiry.parse()?,
+ model: row.model,
+ output_schema: row.output_schema,
created_at: row.created_at,
updated_at: row.updated_at,
})
@@ -93,15 +111,23 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
// A request for a projection bumps `last_requested_at` so the background
// refresh handler can tell active instances apart from abandoned ones
// (which it eventually deletes once they fall outside their expiry
- // window). The prompt and status are intentionally left untouched on
- // conflict: the definition's prompt is immutable and the materialization
- // lifecycle is owned by the worker.
+ // window). An instance created for an older prompt version is reset to
+ // cold — its previous result stays visible until regeneration
+ // overwrites it — while a same-version instance keeps its status.
sqlx::query!(
r#"
INSERT INTO user_ai_projection (ai_projection_id, target_id, prompt_hash, status)
VALUES ($1, $2, $3, $4)
ON CONFLICT (target_id, ai_projection_id)
- DO UPDATE SET last_requested_at = NOW(), updated_at = NOW()
+ DO UPDATE SET
+ last_requested_at = NOW(),
+ updated_at = NOW(),
+ status = CASE
+ WHEN user_ai_projection.prompt_hash IS DISTINCT FROM EXCLUDED.prompt_hash
+ THEN 'cold'
+ ELSE user_ai_projection.status
+ END,
+ prompt_hash = EXCLUDED.prompt_hash
"#,
ai_projection_id,
target_id,
@@ -112,6 +138,16 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
.await
.map_err(sqlx_err)?;
+ self.get_target_projection(ai_projection_id, target_id)
+ .await
+ }
+
+ #[tracing::instrument(skip(self), err)]
+ async fn get_target_projection(
+ &self,
+ ai_projection_id: &str,
+ target_id: &str,
+ ) -> Result<UserAiProjection, AiProjectionError> {
let row = sqlx::query!(
r#"
SELECT ai_projection_id, target_id, prompt_hash, status,
@@ -142,7 +178,7 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
async fn get_projection(&self, id: &str) -> Result<AiProjection, AiProjectionError> {
let row = sqlx::query!(
r#"
- SELECT id, prompt, prompt_hash, target_type, refresh_cadence, expiry, created_at, updated_at
+ SELECT id, prompt, prompt_hash, target_type, refresh_cadence, expiry, model, output_schema, created_at, updated_at
FROM ai_projection
WHERE id = $1
"#,
@@ -159,6 +195,8 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
target_type: row.target_type.parse()?,
refresh_cadence: row.refresh_cadence.parse()?,
expiry: row.expiry.parse()?,
+ model: row.model,
+ output_schema: row.output_schema,
created_at: row.created_at,
updated_at: row.updated_at,
})
@@ -228,6 +266,31 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
&self,
ai_projection_id: &str,
target_id: &str,
+ prompt_hash: &str,
+ ) -> Result<(), AiProjectionError> {
+ sqlx::query!(
+ r#"
+ UPDATE user_ai_projection
+ SET status = $4, updated_at = NOW()
+ WHERE ai_projection_id = $1 AND target_id = $2 AND prompt_hash = $3
+ "#,
+ ai_projection_id,
+ target_id,
+ prompt_hash,
+ ProjectionStatus::Loading.to_string(),
+ )
+ .execute(&self.pool)
+ .await
+ .map_err(sqlx_err)?;
+
+ Ok(())
+ }
+
+ #[tracing::instrument(skip(self), err)]
+ async fn set_projection_refreshing(
+ &self,
+ ai_projection_id: &str,
+ target_id: &str,
) -> Result<(), AiProjectionError> {
sqlx::query!(
r#"
@@ -237,7 +300,7 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
"#,
ai_projection_id,
target_id,
- ProjectionStatus::Loading.to_string(),
+ ProjectionStatus::Refreshing.to_string(),
)
.execute(&self.pool)
.await
@@ -251,6 +314,7 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
&self,
ai_projection_id: &str,
target_id: &str,
+ prompt_hash: &str,
result: &str,
generated_at: chrono::DateTime<chrono::Utc>,
stale_at: chrono::DateTime<chrono::Utc>,
@@ -258,12 +322,13 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
sqlx::query!(
r#"
UPDATE user_ai_projection
- SET status = $3, result = $4, error = NULL,
- generated_at = $5, stale_at = $6, updated_at = NOW()
- WHERE ai_projection_id = $1 AND target_id = $2
+ SET status = $4, result = $5, error = NULL,
+ generated_at = $6, stale_at = $7, updated_at = NOW()
+ WHERE ai_projection_id = $1 AND target_id = $2 AND prompt_hash = $3
"#,
ai_projection_id,
target_id,
+ prompt_hash,
ProjectionStatus::Ready.to_string(),
result,
generated_at,
@@ -281,16 +346,18 @@ impl AiProjectionRepository for AiProjectionRepositoryImpl {
&self,
ai_projection_id: &str,
target_id: &str,
+ prompt_hash: &str,
error: &str,
) -> Result<(), AiProjectionError> {
sqlx::query!(
r#"
UPDATE user_ai_projection
- SET status = $3, error = $4, updated_at = NOW()
- WHERE ai_projection_id = $1 AND target_id = $2
+ SET status = $4, error = $5, updated_at = NOW()
+ WHERE ai_projection_id = $1 AND target_id = $2 AND prompt_hash = $3
"#,
ai_projection_id,
target_id,
+ prompt_hash,
ProjectionStatus::Error.to_string(),
error,
)
diff --git a/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo/test.rs b/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo/test.rs
index 6282ebe70f..4f3c96a3ae 100644
--- a/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo/test.rs
+++ b/rust/cloud-storage/ai_projections/src/outbound/ai_projection_repo/test.rs
@@ -7,42 +7,79 @@ use sqlx::{Pool, Postgres};
use super::*;
use crate::domain::ai_projection_service::READ_PROFESSIONAL_FEATURES;
+/// Upserts a plain user-targeted definition with the given id and hash.
+async fn upsert_definition(
+ repo: &AiProjectionRepositoryImpl,
+ id: &str,
+ prompt: &str,
+ prompt_hash: &str,
+) -> Result<AiProjection, AiProjectionError> {
+ repo.upsert_projection_definition(
+ id,
+ prompt,
+ prompt_hash,
+ TargetType::User,
+ RefreshCadence::High,
+ Expiry::Day,
+ None,
+ None,
+ )
+ .await
+}
+
#[sqlx::test(
migrator = "MACRO_DB_MIGRATIONS",
fixtures(path = "../../../fixtures", scripts("ai_projections"))
)]
-async fn get_or_create_projection_is_idempotent(pool: Pool<Postgres>) -> anyhow::Result<()> {
+async fn upsert_projection_definition_is_idempotent_for_same_version(
+ pool: Pool<Postgres>,
+) -> anyhow::Result<()> {
let repo = AiProjectionRepositoryImpl::new(pool);
- let first = repo
- .get_or_create_projection(
- "inbox/important",
- "What is important?",
- "hash_v1",
- TargetType::User,
- RefreshCadence::High,
- Expiry::Day,
- )
- .await?;
+ let first =
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
+ let second =
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
- // A second call with a different prompt/target_type must NOT update the existing row.
- let second = repo
- .get_or_create_projection(
+ assert_eq!(first, second);
+ assert_eq!(second.prompt, "What is important?");
+ assert_eq!(second.prompt_hash, "hash_v1");
+
+ Ok(())
+}
+
+#[sqlx::test(
+ migrator = "MACRO_DB_MIGRATIONS",
+ fixtures(path = "../../../fixtures", scripts("ai_projections"))
+)]
+async fn upsert_projection_definition_revises_on_version_change(
+ pool: Pool<Postgres>,
+) -> anyhow::Result<()> {
+ let repo = AiProjectionRepositoryImpl::new(pool);
+
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
+
+ // A new prompt hash revises the stored definition in place.
+ let schema = serde_json::json!({"type": "object"});
+ let revised = repo
+ .upsert_projection_definition(
"inbox/important",
"A totally different prompt",
"hash_v2",
- TargetType::Team,
+ TargetType::User,
RefreshCadence::Low,
Expiry::Month,
+ Some("cerebras/llama-3.3-70b"),
+ Some(&schema),
)
.await?;
- assert_eq!(first, second);
- assert_eq!(second.prompt, "What is important?");
- assert_eq!(second.prompt_hash, "hash_v1");
- assert_eq!(second.target_type, TargetType::User);
- assert_eq!(second.refresh_cadence, RefreshCadence::High);
- assert_eq!(second.expiry, Expiry::Day);
+ assert_eq!(revised.prompt, "A totally different prompt");
+ assert_eq!(revised.prompt_hash, "hash_v2");
+ assert_eq!(revised.refresh_cadence, RefreshCadence::Low);
+ assert_eq!(revised.expiry, Expiry::Month);
+ assert_eq!(revised.model.as_deref(), Some("cerebras/llama-3.3-70b"));
+ assert_eq!(revised.output_schema.as_ref(), Some(&schema));
Ok(())
}
@@ -55,15 +92,7 @@ async fn get_or_create_target_projection_is_idempotent(pool: Pool<Postgres>) ->
let repo = AiProjectionRepositoryImpl::new(pool);
let user = MacroUserIdStr::parse_from_str("macro|[email protected]")?;
- repo.get_or_create_projection(
- "inbox/important",
- "What is important?",
- "hash_v1",
- TargetType::User,
- RefreshCadence::High,
- Expiry::Day,
- )
- .await?;
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
let first = repo
.get_or_create_target_projection("inbox/important", user.as_ref(), "hash_v1")
@@ -87,22 +116,52 @@ async fn get_or_create_target_projection_is_idempotent(pool: Pool<Postgres>) ->
migrator = "MACRO_DB_MIGRATIONS",
fixtures(path = "../../../fixtures", scripts("ai_projections"))
)]
-async fn get_or_create_target_projection_bumps_last_requested_at(
+async fn get_or_create_target_projection_resets_to_cold_on_version_change(
pool: Pool<Postgres>,
) -> anyhow::Result<()> {
- let repo = AiProjectionRepositoryImpl::new(pool.clone());
+ let repo = AiProjectionRepositoryImpl::new(pool);
let user = MacroUserIdStr::parse_from_str("macro|[email protected]")?;
- repo.get_or_create_projection(
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
+ repo.get_or_create_target_projection("inbox/important", user.as_ref(), "hash_v1")
+ .await?;
+
+ // Materialize the v1 instance.
+ let generated_at = chrono::Utc::now();
+ repo.set_projection_result(
"inbox/important",
- "What is important?",
+ user.as_ref(),
"hash_v1",
- TargetType::User,
- RefreshCadence::High,
- Expiry::Day,
+ "v1 result",
+ generated_at,
+ generated_at + Expiry::Day.to_duration(),
)
.await?;
+ // Requesting the instance under a new version resets it to cold but keeps
+ // the previous result visible until regeneration overwrites it.
+ let reset = repo
+ .get_or_create_target_projection("inbox/important", user.as_ref(), "hash_v2")
+ .await?;
+ assert_eq!(reset.status, ProjectionStatus::Cold);
+ assert_eq!(reset.prompt_hash, "hash_v2");
+ assert_eq!(reset.result.as_deref(), Some("v1 result"));
+
+ Ok(())
+}
+
+#[sqlx::test(
+ migrator = "MACRO_DB_MIGRATIONS",
+ fixtures(path = "../../../fixtures", scripts("ai_projections"))
+)]
+async fn get_or_create_target_projection_bumps_last_requested_at(
+ pool: Pool<Postgres>,
+) -> anyhow::Result<()> {
+ let repo = AiProjectionRepositoryImpl::new(pool.clone());
+ let user = MacroUserIdStr::parse_from_str("macro|[email protected]")?;
+
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
+
repo.get_or_create_target_projection("inbox/important", user.as_ref(), "hash_v1")
.await?;
@@ -154,13 +213,15 @@ async fn get_or_create_target_projection_supports_team_targets(
) -> anyhow::Result<()> {
let repo = AiProjectionRepositoryImpl::new(pool);
- repo.get_or_create_projection(
+ repo.upsert_projection_definition(
"team/focus",
"What is my team focused on?",
"hash_v1",
TargetType::Team,
RefreshCadence::Medium,
Expiry::Week,
+ None,
+ None,
)
.await?;
@@ -176,6 +237,35 @@ async fn get_or_create_target_projection_supports_team_targets(
Ok(())
}
+#[sqlx::test(
+ migrator = "MACRO_DB_MIGRATIONS",
+ fixtures(path = "../../../fixtures", scripts("ai_projections"))
+)]
+async fn get_target_projection_returns_instance_or_not_found(
+ pool: Pool<Postgres>,
+) -> anyhow::Result<()> {
+ let repo = AiProjectionRepositoryImpl::new(pool);
+ let user = MacroUserIdStr::parse_from_str("macro|[email protected]")?;
+
+ assert!(matches!(
+ repo.get_target_projection("inbox/important", user.as_ref())
+ .await,
+ Err(AiProjectionError::NotFound)
+ ));
+
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
+ repo.get_or_create_target_projection("inbox/important", user.as_ref(), "hash_v1")
+ .await?;
+
+ let instance = repo
+ .get_target_projection("inbox/important", user.as_ref())
+ .await?;
+ assert_eq!(instance.ai_projection_id, "inbox/important");
+ assert_eq!(instance.status, ProjectionStatus::Cold);
+
+ Ok(())
+}
+
#[sqlx::test(
migrator = "MACRO_DB_MIGRATIONS",
fixtures(path = "../../../fixtures", scripts("ai_projections"))
@@ -212,15 +302,7 @@ async fn get_projection_returns_definition_or_not_found(
Err(AiProjectionError::NotFound)
));
- repo.get_or_create_projection(
- "inbox/important",
- "What is important?",
- "hash_v1",
- TargetType::User,
- RefreshCadence::High,
- Expiry::Day,
- )
- .await?;
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
let projection = repo.get_projection("inbox/important").await?;
assert_eq!(projection.prompt, "What is important?");
@@ -236,15 +318,7 @@ async fn get_projection_returns_definition_or_not_found(
async fn processing_claim_is_exclusive_and_releasable(pool: Pool<Postgres>) -> anyhow::Result<()> {
let repo = AiProjectionRepositoryImpl::new(pool);
- repo.get_or_create_projection(
- "inbox/important",
- "What is important?",
- "hash_v1",
- TargetType::User,
- RefreshCadence::High,
- Expiry::Day,
- )
- .await?;
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
let target = "macro|[email protected]";
@@ -267,15 +341,7 @@ async fn set_projection_result_and_error_update_status(pool: Pool<Postgres>) ->
let repo = AiProjectionRepositoryImpl::new(pool);
let target = "macro|[email protected]";
- repo.get_or_create_projection(
- "inbox/important",
- "What is important?",
- "hash_v1",
- TargetType::User,
- RefreshCadence::High,
- Expiry::Day,
- )
- .await?;
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
repo.get_or_create_target_projection("inbox/important", target, "hash_v1")
.await?;
@@ -284,6 +350,7 @@ async fn set_projection_result_and_error_update_status(pool: Pool<Postgres>) ->
repo.set_projection_result(
"inbox/important",
target,
+ "hash_v1",
"the result",
generated_at,
stale_at,
@@ -291,16 +358,16 @@ async fn set_projection_result_and_error_update_status(pool: Pool<Postgres>) ->
.await?;
let ready = repo
- .get_or_create_target_projection("inbox/important", target, "hash_v1")
+ .get_target_projection("inbox/important", target)
.await?;
assert_eq!(ready.status, ProjectionStatus::Ready);
assert_eq!(ready.result.as_deref(), Some("the result"));
assert!(ready.generated_at.is_some());
- repo.set_projection_error("inbox/important", target, "it broke")
+ repo.set_projection_error("inbox/important", target, "hash_v1", "it broke")
.await?;
let errored = repo
- .get_or_create_target_projection("inbox/important", target, "hash_v1")
+ .get_target_projection("inbox/important", target)
.await?;
assert_eq!(errored.status, ProjectionStatus::Error);
assert_eq!(errored.error.as_deref(), Some("it broke"));
@@ -308,6 +375,73 @@ async fn set_projection_result_and_error_update_status(pool: Pool<Postgres>) ->
Ok(())
}
+#[sqlx::test(
+ migrator = "MACRO_DB_MIGRATIONS",
+ fixtures(path = "../../../fixtures", scripts("ai_projections"))
+)]
+async fn projection_writes_are_scoped_to_the_message_version(
+ pool: Pool<Postgres>,
+) -> anyhow::Result<()> {
+ let repo = AiProjectionRepositoryImpl::new(pool);
+ let target = "macro|[email protected]";
+
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
+ repo.get_or_create_target_projection("inbox/important", target, "hash_v1")
+ .await?;
+
+ // The instance moved to v2 (e.g. the prompt changed mid-flight); writes
+ // carrying the old v1 hash must not clobber it.
+ repo.get_or_create_target_projection("inbox/important", target, "hash_v2")
+ .await?;
+
+ let generated_at = chrono::Utc::now();
+ repo.set_projection_result(
+ "inbox/important",
+ target,
+ "hash_v1",
+ "stale v1 result",
+ generated_at,
+ generated_at + Expiry::Day.to_duration(),
+ )
+ .await?;
+ repo.set_projection_error("inbox/important", target, "hash_v1", "stale v1 error")
+ .await?;
+ repo.set_projection_loading("inbox/important", target, "hash_v1")
+ .await?;
+
+ let instance = repo
+ .get_target_projection("inbox/important", target)
+ .await?;
+ assert_eq!(instance.status, ProjectionStatus::Cold);
+ assert!(instance.result.is_none());
+ assert!(instance.error.is_none());
+
+ Ok(())
+}
+
+#[sqlx::test(
+ migrator = "MACRO_DB_MIGRATIONS",
+ fixtures(path = "../../../fixtures", scripts("ai_projections"))
+)]
+async fn set_projection_refreshing_updates_status(pool: Pool<Postgres>) -> anyhow::Result<()> {
+ let repo = AiProjectionRepositoryImpl::new(pool);
+ let target = "macro|[email protected]";
+
+ upsert_definition(&repo, "inbox/important", "What is important?", "hash_v1").await?;
+ repo.get_or_create_target_projection("inbox/important", target, "hash_v1")
+ .await?;
+
+ repo.set_projection_refreshing("inbox/important", target)
+ .await?;
+
+ let instance = repo
+ .get_target_projection("inbox/important", target)
+ .await?;
+ assert_eq!(instance.status, ProjectionStatus::Refreshing);
+
+ Ok(())
+}
+
#[sqlx::test(
migrator = "MACRO_DB_MIGRATIONS",
fixtures(path = "../../../fixtures", scripts("ai_projections"))
diff --git a/rust/cloud-storage/ai_projections/src/outbound/gateway_notifier.rs b/rust/cloud-storage/ai_projections/src/outbound/gateway_notifier.rs
new file mode 100644
index 0000000000..a343e27aec
--- /dev/null
+++ b/rust/cloud-storage/ai_projections/src/outbound/gateway_notifier.rs
@@ -0,0 +1,71 @@
+//! Connection-gateway adapter that pushes projection updates to clients.
+
+use std::sync::Arc;
+
+use connection_gateway_client::ConnectionGatewayClient;
+use model_entity::EntityType;
+
+use crate::domain::{
+ model::{TargetType, UserAiProjection},
+ projection_notifier::ProjectionNotifier,
+};
+
+/// The websocket `message_type` for projection state updates. The payload
+/// mirrors the upsert endpoint's `ProjectionStateResponse` (plus `type` and
+/// `target_type`) so the frontend can write it straight into its query cache.
+pub const AI_PROJECTION_UPDATED_MESSAGE_TYPE: &str = "ai_projection_updated";
+
+/// [`ProjectionNotifier`] that pushes updates through the connection gateway.
+#[derive(Clone)]
+pub struct GatewayProjectionNotifier {
+ client: Arc<ConnectionGatewayClient>,
+}
+
+impl GatewayProjectionNotifier {
+ /// Creates a notifier over an existing connection gateway client.
+ pub fn new(client: Arc<ConnectionGatewayClient>) -> Self {
+ Self { client }
+ }
+}
+
+impl ProjectionNotifier for GatewayProjectionNotifier {
+ #[tracing::instrument(
+ skip(self, instance),
+ fields(
+ ai_projection_id = %instance.ai_projection_id,
+ target_id = %instance.target_id,
+ ),
+ err
+ )]
+ async fn notify_updated(
+ &self,
+ target_type: TargetType,
+ instance: &UserAiProjection,
+ ) -> anyhow::Result<()> {
+ let entity = match target_type {
+ TargetType::User => EntityType::User.with_entity_str(&instance.target_id),
+ TargetType::Team => EntityType::Team.with_entity_str(&instance.target_id),
+ };
+
+ let payload = serde_json::json!({
+ "type": AI_PROJECTION_UPDATED_MESSAGE_TYPE,
+ "id": instance.ai_projection_id,
+ "target_type": target_type,
+ "status": instance.status,
+ "data": instance.result,
+ "error": instance.error,
+ "generated_at": instance.generated_at,
+ "stale_at": instance.stale_at,
+ });
+
+ self.client
+ .send_message(
+ entity,
+ AI_PROJECTION_UPDATED_MESSAGE_TYPE.to_string(),
+ payload,
+ )
+ .await?;
+
+ Ok(())
+ }
+}
diff --git a/rust/cloud-storage/ai_projections_refresh_handler/src/refresh.rs b/rust/cloud-storage/ai_projections_refresh_handler/src/refresh.rs
index e4d5417638..79a9434a1d 100644
--- a/rust/cloud-storage/ai_projections_refresh_handler/src/refresh.rs
+++ b/rust/cloud-storage/ai_projections_refresh_handler/src/refresh.rs
@@ -1,11 +1,12 @@
//! The refresh sweep: for a single cadence, decide per `user_ai_projection`
//! instance whether to delete it, refresh it, or leave it untouched.
//!
-//! Decision rules (see `ai_projections.md`):
+//! Decision rules:
//! - **Delete** when an instance has not been requested within its expiry window
//! (`now() - last_requested_at > expiry`). A future request recreates it.
//! - **Refresh** when an instance is still active but its cached result is stale
-//! (`now() > stale_at`) and it is not already in flight.
+//! (`now() > stale_at`) — or errored without ever producing a result — and it
+//! is not already in flight.
//! - **Leave** everything else ("hot") alone.
//!
//! All queries live here in the lambda crate. The `expiry` window is expressed
@@ -106,6 +107,11 @@ async fn delete_inactive(db: &Pool<Postgres>, cadence: RefreshCadence) -> anyhow
/// `refreshing` for more than 15 minutes (e.g. a previous sweep that failed to
/// enqueue) are reclaimed, mirroring the `processing_ai_projections` lease
/// reclaim convention used by the worker.
+///
+/// Claimed instances are also moved onto the definition's current
+/// `prompt_hash`: the worker's writes are scoped to the message's hash, so a
+/// refresh enqueued for an instance still on an older prompt version would
+/// otherwise be discarded on completion.
#[tracing::instrument(skip(db), err)]
async fn claim_stale(
db: &Pool<Postgres>,
@@ -114,12 +120,14 @@ async fn claim_stale(
let rows = sqlx::query!(
r#"
UPDATE user_ai_projection u
- SET status = 'refreshing', updated_at = NOW()
+ SET status = 'refreshing', prompt_hash = p.prompt_hash, updated_at = NOW()
FROM ai_projection p
WHERE u.ai_projection_id = p.id
AND p.refresh_cadence = $1
- AND u.stale_at IS NOT NULL
- AND u.stale_at < NOW()
+ AND (
+ (u.stale_at IS NOT NULL AND u.stale_at < NOW())
+ OR (u.status = 'error' AND u.stale_at IS NULL)
+ )
AND u.last_requested_at >= NOW() - (
CASE p.expiry
WHEN 'day' THEN INTERVAL '1 day'
diff --git a/rust/cloud-storage/ai_projections_refresh_handler/src/refresh/test.rs b/rust/cloud-storage/ai_projections_refresh_handler/src/refresh/test.rs
index f02ecd2602..57cf01d8bf 100644
--- a/rust/cloud-storage/ai_projections_refresh_handler/src/refresh/test.rs
+++ b/rust/cloud-storage/ai_projections_refresh_handler/src/refresh/test.rs
@@ -192,6 +192,19 @@ async fn claim_stale_selects_and_marks_refreshing(pool: Pool<Postgres>) -> anyho
now,
)
.await?;
+ // errored before ever producing a result (stale_at is NULL) + active ->
+ // claimed, so failed first materializations are retried by the sweep.
+ insert_instance(
+ &pool,
+ "high/day",
+ "error_never_generated",
+ "error",
+ None,
+ None,
+ active,
+ now,
+ )
+ .await?;
// stale + active + loading -> in flight, skipped.
insert_instance(
&pool,
@@ -271,13 +284,23 @@ async fn claim_stale_selects_and_marks_refreshing(pool: Pool<Postgres>) -> anyho
let claimed_ids: Vec<&str> = claimed.iter().map(|t| t.target_id.as_str()).collect();
assert_eq!(
claimed_ids,
- vec!["error_stale", "ready_stale", "stuck_refreshing"]
+ vec![
+ "error_never_generated",
+ "error_stale",
+ "ready_stale",
+ "stuck_refreshing"
+ ]
);
// The returned prompt_hash comes from the definition.
assert!(claimed.iter().all(|t| t.prompt_hash == "hash_v1"));
// Claimed instances are now marked refreshing.
- for id in ["ready_stale", "error_stale", "stuck_refreshing"] {
+ for id in [
+ "ready_stale",
+ "error_stale",
+ "error_never_generated",
+ "stuck_refreshing",
+ ] {
assert_eq!(
status_of(&pool, "high/day", id).await?.as_deref(),
Some("refreshing"),
@@ -315,6 +338,49 @@ async fn claim_stale_selects_and_marks_refreshing(pool: Pool<Postgres>) -> anyho
Ok(())
}
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn claim_stale_moves_instance_onto_current_version(
+ pool: Pool<Postgres>,
+) -> anyhow::Result<()> {
+ insert_projection(&pool, "high/day", "high", "day").await?;
+
+ let now = Utc::now();
+ insert_instance(
+ &pool,
+ "high/day",
+ "old_version",
+ "ready",
+ Some(now - Duration::hours(2)),
+ Some(now - Duration::hours(1)),
+ now,
+ now,
+ )
+ .await?;
+
+ // The definition was revised since the instance materialized.
+ sqlx::query!("UPDATE ai_projection SET prompt_hash = 'hash_v2' WHERE id = 'high/day'")
+ .execute(&pool)
+ .await?;
+
+ let claimed = claim_stale(&pool, RefreshCadence::High).await?;
+ assert_eq!(claimed.len(), 1);
+ assert_eq!(claimed[0].prompt_hash, "hash_v2");
+
+ // The claimed instance was moved onto the definition's version so the
+ // worker's hash-scoped writes land.
+ let instance_hash = sqlx::query_scalar!(
+ r#"
+ SELECT prompt_hash FROM user_ai_projection
+ WHERE ai_projection_id = 'high/day' AND target_id = 'old_version'
+ "#,
+ )
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(instance_hash, "hash_v2");
+
+ Ok(())
+}
+
#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
async fn expiry_window_scales_with_definition(pool: Pool<Postgres>) -> anyhow::Result<()> {
// Same cadence, different expiry windows.
diff --git a/rust/cloud-storage/document_cognition_service/Cargo.toml b/rust/cloud-storage/document_cognition_service/Cargo.toml
index 870f71b652..819245fd6e 100644
--- a/rust/cloud-storage/document_cognition_service/Cargo.toml
+++ b/rust/cloud-storage/document_cognition_service/Cargo.toml
@@ -46,6 +46,7 @@ chat = { path = "../chat", features = ["attachment"] }
channels = { path = "../channels", features = ["outbound", "attachment"] }
chrono = { workspace = true }
connection_gateway = { path = "../connection_gateway" }
+connection_gateway_client = { path = "../connection_gateway_client" }
cookie = { workspace = true }
crm = { path = "../crm" }
document_storage_service_client = { path = "../document_storage_service_client" }
diff --git a/rust/cloud-storage/document_cognition_service/src/api/context/mod.rs b/rust/cloud-storage/document_cognition_service/src/api/context/mod.rs
index eba48a0f10..2bcc845dd1 100644
--- a/rust/cloud-storage/document_cognition_service/src/api/context/mod.rs
+++ b/rust/cloud-storage/document_cognition_service/src/api/context/mod.rs
@@ -57,13 +57,14 @@ pub type DcsMemoryService =
pub type DcsUsageService =
ai_usage::domain::service::UsageServiceImpl<ai_usage::outbound::PgUsageRepo>;
-/// The AI projections service wired to the Postgres projection repo and the SQS
-/// materialization queue.
+/// The AI projections service wired to the Postgres projection repo, the SQS
+/// materialization queue, and the connection-gateway update notifier.
pub type DcsAiProjectionService =
ai_projections::domain::ai_projection_service::AiProjectionServiceImpl<
ai_projections::outbound::ai_projection_repo::AiProjectionRepositoryImpl,
sqs_client::SQS,
ai_projections::outbound::agent_generator::AgentProjectionGenerator,
+ ai_projections::outbound::gateway_notifier::GatewayProjectionNotifier,
>;
/// Concrete MCP router state for DCS.
diff --git a/rust/cloud-storage/document_cognition_service/src/api/context/test.rs b/rust/cloud-storage/document_cognition_service/src/api/context/test.rs
index ac0355ca79..6998152fc3 100644
--- a/rust/cloud-storage/document_cognition_service/src/api/context/test.rs
+++ b/rust/cloud-storage/document_cognition_service/src/api/context/test.rs
@@ -353,6 +353,14 @@ pub async fn test_api_context(pool: sqlx::Pool<sqlx::Postgres>) -> std::sync::Ar
ai_tools::all_tools(),
);
+ let projection_notifier =
+ ai_projections::outbound::gateway_notifier::GatewayProjectionNotifier::new(Arc::new(
+ connection_gateway_client::ConnectionGatewayClient::new(
+ "testing".to_string(),
+ "http://localhost".to_string(),
+ ),
+ ));
+
let ai_projections_service = Arc::new(
ai_projections::domain::ai_projection_service::AiProjectionServiceImpl::new(
ai_projections::outbound::ai_projection_repo::AiProjectionRepositoryImpl::new(
@@ -360,6 +368,7 @@ pub async fn test_api_context(pool: sqlx::Pool<sqlx::Postgres>) -> std::sync::Ar
),
sqs_client.clone(),
projection_generator,
+ projection_notifier,
),
);
diff --git a/rust/cloud-storage/document_cognition_service/src/main.rs b/rust/cloud-storage/document_cognition_service/src/main.rs
index 37d067ae91..e005306660 100644
--- a/rust/cloud-storage/document_cognition_service/src/main.rs
+++ b/rust/cloud-storage/document_cognition_service/src/main.rs
@@ -430,6 +430,15 @@ async fn main() -> anyhow::Result<()> {
tool_service_context.clone(),
ai_tools::all_tools(),
);
+ // Notifier that pushes finished materializations to the target's connected
+ // clients through the connection gateway.
+ let projection_notifier =
+ ai_projections::outbound::gateway_notifier::GatewayProjectionNotifier::new(Arc::new(
+ connection_gateway_client::ConnectionGatewayClient::new(
+ internal_api_key.clone(),
+ ConnectionGatewayUrl::new()?.to_string(),
+ ),
+ ));
let ai_projections_service_impl =
ai_projections::domain::ai_projection_service::AiProjectionServiceImpl::new(
ai_projections::outbound::ai_projection_repo::AiProjectionRepositoryImpl::new(
@@ -437,6 +446,7 @@ async fn main() -> anyhow::Result<()> {
),
sqs_client.clone(),
projection_generator,
+ projection_notifier,
);
// Spawn the inbound worker that polls ai_projection_queue and materializes
diff --git a/rust/cloud-storage/macro_db_client/migrations/20260702014503_add_ai_projection_model_and_output_schema.sql b/rust/cloud-storage/macro_db_client/migrations/20260702014503_add_ai_projection_model_and_output_schema.sql
new file mode 100644
index 0000000000..e76f118753
--- /dev/null
+++ b/rust/cloud-storage/macro_db_client/migrations/20260702014503_add_ai_projection_model_and_output_schema.sql
@@ -0,0 +1,6 @@
+-- AI projections: optional model override and structured-output schema on the
+-- projection definition. Both participate in the version hash (prompt_hash),
+-- so changing either regenerates cached instances.
+ALTER TABLE ai_projection
+ ADD COLUMN model TEXT,
+ ADD COLUMN output_schema JSONB;