@agent-native/creative-context 0.0.0-beta-20260820202238

package/src/actions/publish-brand-dna.ts

@@ -0,0 +1,25 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { publishBrandDna } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Publish an immutable brand DNA version pinned to exact evidence item versions and refresh transparent brand context.",
+  schema: z.object({
+    profileId: z.string().min(1),
+    proposalVersionId: z.string().min(1),
+    confirmation: z.object({
+      proposalVersionId: z.string().min(1),
+      contentHash: z.string().length(64),
+    }),
+  }),
+  needsApproval: true,
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: publishBrandDna,
+});

package/src/actions/recommend-context-roots.ts

@@ -0,0 +1,24 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { recommendContextRoots } from "../connectors/recommendations.js";
+import { getCreativeContext } from "../server/context.js";
+
+export default defineAction({
+  description:
+    "Return read-only provider-backed source recommendations for confirmation. Recommendations are never an import boundary and are not persisted.",
+  schema: z.object({
+    provider: z.enum(["notion", "google-slides", "figma"]),
+    connectionId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(50).default(15),
+    figmaProjectId: z.string().min(1).optional(),
+    figmaTeamId: z.string().min(1).optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const { connectorContext } = getCreativeContext();
+    return recommendContextRoots(args, connectorContext);
+  },
+});

package/src/actions/record-context-feedback.ts

@@ -0,0 +1,16 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { recordContextFeedback } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Record a usefulness, correctness, or freshness signal against an exact context item version.",
+  schema: z.object({
+    itemId: z.string().min(1),
+    itemVersionId: z.string().min(1).optional(),
+    signal: z.enum(["helpful", "not-helpful", "incorrect", "outdated"]),
+    note: z.string().max(5000).optional(),
+  }),
+  run: recordContextFeedback,
+});

package/src/actions/review-context-items.ts

@@ -0,0 +1,69 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { serializePublicReviewItems } from "../server/public-serialization.js";
+import { reviewContextItems } from "../store/index.js";
+
+const schema = z.discriminatedUnion("operation", [
+  z.object({
+    sourceId: z.string().min(1),
+    operation: z.literal("list"),
+    queue: z.enum(["restricted", "all"]).default("restricted"),
+    limit: z.coerce.number().int().min(1).max(500).default(100),
+  }),
+  z.object({
+    sourceId: z.string().min(1),
+    operation: z.enum([
+      "approve",
+      "exclude",
+      "exemplar",
+      "normal",
+      "ignore",
+      "star",
+      "unstar",
+      "deprecate",
+      "restore",
+    ]),
+    itemIds: z.array(z.string().min(1)).min(1).max(500),
+  }),
+]);
+
+const agentInputSchema = z.object({
+  sourceId: z.string().min(1),
+  operation: z.enum([
+    "list",
+    "approve",
+    "exclude",
+    "exemplar",
+    "normal",
+    "ignore",
+    "star",
+    "unstar",
+    "deprecate",
+    "restore",
+  ]),
+  queue: z.enum(["restricted", "all"]).optional(),
+  limit: z.coerce.number().int().min(1).max(500).optional(),
+  itemIds: z.array(z.string().min(1)).min(1).max(500).optional(),
+});
+
+export default defineAction({
+  description:
+    "List pending restricted metadata without content, or approve/exclude selected items after user confirmation.",
+  schema,
+  agentInputSchema,
+  needsApproval: (args) => args.operation !== "list",
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: async (input) => {
+    const result = await reviewContextItems(input);
+    return {
+      ...result,
+      items: serializePublicReviewItems(result.items),
+    };
+  },
+});

package/src/actions/run-embedding-bakeoff.ts

@@ -0,0 +1,90 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { availableEmbeddingFamilies } from "../embeddings/providers.js";
+import {
+  bakeOffEmbeddingFamilies,
+  CREATIVE_CONTEXT_GOLD_DOCUMENTS,
+  CREATIVE_CONTEXT_GOLD_TASKS,
+  embeddingBakeoffPasses,
+} from "../eval/index.js";
+import { createEmbeddingSet } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Run the checked-in retrieval bake-off across configured embedding families and persist the winning family/model/version/dimensions as the active corpus choice.",
+  schema: z.object({ confirmProviderCosts: z.literal(true) }),
+  needsApproval: true,
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: async () => {
+    const families = await availableEmbeddingFamilies();
+    if (!families.length) {
+      throw new Error(
+        "Configure at least one GEMINI_API_KEY, COHERE_API_KEY, or VOYAGE_API_KEY before running the embedding bake-off.",
+      );
+    }
+    const results = await bakeOffEmbeddingFamilies({
+      families,
+      documents: Object.fromEntries(
+        CREATIVE_CONTEXT_GOLD_DOCUMENTS.map((document) => [
+          document.key,
+          {
+            text: `${document.title}\n${document.text}`,
+            ...(document.imageBase64
+              ? {
+                  images: [
+                    {
+                      mimeType: "image/png" as const,
+                      base64: document.imageBase64,
+                    },
+                  ],
+                }
+              : {}),
+          },
+        ]),
+      ),
+      tasks: CREATIVE_CONTEXT_GOLD_TASKS,
+      allowedDocumentKeys: CREATIVE_CONTEXT_GOLD_DOCUMENTS.filter(
+        (document) =>
+          document.owner !== "other-organization" &&
+          document.status === "active",
+      ).map((document) => document.key),
+    });
+    const winner = results.find((result) =>
+      embeddingBakeoffPasses(result.metrics),
+    );
+    if (!winner) {
+      throw new Error(
+        "No embedding family passed the hard multimodal retrieval and zero-leak thresholds; no active winner was persisted.",
+      );
+    }
+    const set = await createEmbeddingSet({
+      name: `Creative context ${winner.family.provider} bake-off winner`,
+      provider: winner.family.provider,
+      family: winner.family.id,
+      model: winner.family.model,
+      version: winner.family.version,
+      dimensions: winner.family.dimensions,
+      metadata: {
+        metrics: winner.metrics,
+        evaluatedAt: new Date().toISOString(),
+      },
+    });
+    return {
+      winner: set,
+      results: results.map((result) => ({
+        family: result.family.id,
+        provider: result.family.provider,
+        model: result.family.model,
+        version: result.family.version,
+        dimensions: result.family.dimensions,
+        metrics: result.metrics,
+      })),
+    };
+  },
+});

package/src/actions/search-creative-context.ts

@@ -0,0 +1,48 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { performCreativeContextSearch } from "../server/retrieval.js";
+
+const schema = z
+  .object({
+    query: z.string().trim().min(1).max(1000).optional(),
+    imageBlobRef: z.string().min(1).max(20_000).optional(),
+    mediaId: z.string().min(1).optional(),
+    sourceIds: z.array(z.string().min(1)).max(100).optional(),
+    packId: z.string().min(1).optional(),
+    contextId: z.string().min(1).optional(),
+    kinds: z.array(z.string().min(1)).max(50).optional(),
+    tags: z.array(z.string().min(1)).max(100).optional(),
+    colors: z.array(z.string().min(1)).max(100).optional(),
+    updatedAfter: z.iso.datetime().optional(),
+    updatedBefore: z.iso.datetime().optional(),
+    statuses: z
+      .array(z.enum(["active", "deprecated"]))
+      .max(2)
+      .optional(),
+    matchMode: z
+      .enum(["allTerms", "anyTerm", "phrase", "regex"])
+      .default("allTerms"),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    cursor: z.string().optional(),
+    maxPerSource: z.coerce.number().int().min(1).max(20).default(5),
+    snapshot: z.boolean().default(true),
+    contextPackName: z.string().trim().min(1).max(200).optional(),
+  })
+  .refine(
+    (value) => Boolean(value.query || value.imageBlobRef || value.mediaId),
+    {
+      message: "Provide query, imageBlobRef, or mediaId",
+    },
+  )
+  .refine((value) => !(value.imageBlobRef && value.mediaId), {
+    message: "Provide imageBlobRef or mediaId, not both",
+  });
+
+export default defineAction({
+  description:
+    "Search accessible approved Creative Context evidence, optionally within one named context, through portable lexical, Postgres FTS, and same-database pgvector lanes; fuse and diversify results, collapse revisions, and snapshot exact evidence by default. A result with nativeArtifact set has a real source artifact behind it, so call get-context-item on that item/version to read version.nativeCode instead of reusing the text excerpt.",
+  schema,
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: performCreativeContextSearch,
+});

package/src/actions/set-brand-dna.ts

@@ -0,0 +1,22 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { saveBrandDnaCandidate } from "../store/index.js";
+
+const dna = z
+  .object({ summary: z.string().trim().min(1).max(20_000) })
+  .catchall(z.unknown());
+
+export default defineAction({
+  description:
+    "Save an immutable draft brand DNA version pinned to exact evidence versions without changing published context.",
+  schema: z.object({
+    profileId: z.string().min(1).optional(),
+    name: z.string().trim().min(1).max(200).optional(),
+    description: z.string().max(5000).nullable().optional(),
+    dna,
+    evidenceItemIds: z.array(z.string().min(1)).max(500).optional(),
+  }),
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: (args) => saveBrandDnaCandidate({ ...args, status: "draft" }),
+});

package/src/actions/start-context-enrichment.ts

@@ -0,0 +1,52 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { serializePublicJob } from "../server/public-serialization.js";
+import { createJob } from "../store/index.js";
+
+const schema = z.object({
+  sourceId: z.string().min(1).optional(),
+  operation: z.enum([
+    "rebuild-fts",
+    "rebuild-embeddings",
+    "enrich-media",
+    "infer-brand-dna",
+    "rank-canonical-logo",
+    "find-layout-suggestions",
+    "metadata-refresh",
+  ]),
+  itemIds: z.array(z.string().min(1)).max(10_000).optional(),
+  eagerLimit: z.coerce.number().int().min(1).max(500).default(25),
+});
+
+export default defineAction({
+  description:
+    "Queue a durable, budgeted creative-context rebuild or enrichment job; top brand inputs run eagerly and the remainder stays pending/on-demand.",
+  schema,
+  needsApproval: true,
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: async (args) => {
+    const job = await createJob({
+      sourceId: args.sourceId,
+      kind:
+        args.operation === "enrich-media"
+          ? "enrich-media"
+          : args.operation === "infer-brand-dna"
+            ? "brand-dna"
+            : args.operation === "rank-canonical-logo"
+              ? "canonical-logo"
+              : args.operation === "find-layout-suggestions"
+                ? "layout-suggestion"
+                : args.operation === "metadata-refresh"
+                  ? "metadata-refresh"
+                  : "embed",
+      request: args,
+      progressTotal: args.itemIds?.length,
+      budget: {
+        eagerLimit: args.eagerLimit,
+        remainingMode: "pending-on-demand",
+      },
+    });
+    return { job: serializePublicJob(job) };
+  },
+});

package/src/actions/start-context-import.ts

@@ -0,0 +1,38 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { dispatchCreativeContextImportJob } from "../jobs/index.js";
+import { getCreativeContext } from "../server/context.js";
+import { serializePublicJob } from "../server/public-serialization.js";
+import { createJob } from "../store/index.js";
+import { getContextSource } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Queue a durable creative-context import for a source. The background runner inventories, fetches, checkpoints, and ingests immutable versions.",
+  schema: z.object({
+    sourceId: z.string().min(1),
+    mode: z.enum(["incremental", "full"]).default("incremental"),
+    itemExternalIds: z.array(z.string().min(1)).max(10_000).optional(),
+  }),
+  needsApproval: true,
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: async (args) => {
+    const source = await getContextSource(args.sourceId);
+    if (!source) throw new Error("Context source not found or not accessible");
+    const job = await createJob({
+      sourceId: args.sourceId,
+      kind: "import",
+      mode: args.mode,
+      request: { itemExternalIds: args.itemExternalIds },
+      progressTotal: args.itemExternalIds?.length,
+    });
+    await dispatchCreativeContextImportJob({
+      jobId: job.id,
+      ownerEmail: source.ownerEmail,
+      orgId: job.orgId,
+      appId: getCreativeContext().connectorContext.appId,
+    });
+    return { job: serializePublicJob(job) };
+  },
+});

package/src/client/CreativeContextChip.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  hasCreativeContextConfiguration,
+  resolveCreativeContextChipSelection,
+} from "./CreativeContextChip.js";
+
+function context(memberCount: number) {
+  return { memberCount };
+}
+
+function pack(memberCount: number) {
+  return { memberCount };
+}
+
+describe("hasCreativeContextConfiguration", () => {
+  it("ignores an empty Default context and empty packs", () => {
+    expect(hasCreativeContextConfiguration([pack(0)], [context(0)])).toBe(
+      false,
+    );
+  });
+
+  it("shows the chip when a context has reusable resources", () => {
+    expect(hasCreativeContextConfiguration([], [context(1)])).toBe(true);
+  });
+
+  it("shows the chip when a pack has reusable resources", () => {
+    expect(hasCreativeContextConfiguration([pack(1)], [])).toBe(true);
+  });
+});
+
+describe("resolveCreativeContextChipSelection", () => {
+  it("keeps the documented precedence", () => {
+    expect(
+      resolveCreativeContextChipSelection({
+        contextMode: "off",
+        selectedContextId: "context-1",
+        pinnedPackId: "pack-1",
+      }),
+    ).toBe("off");
+    expect(
+      resolveCreativeContextChipSelection({
+        contextMode: "auto",
+        selectedContextId: "context-1",
+        pinnedPackId: "pack-1",
+      }),
+    ).toBe("pinned-pack");
+    expect(
+      resolveCreativeContextChipSelection({
+        contextMode: "auto",
+        selectedContextId: "context-1",
+        pinnedPackId: null,
+      }),
+    ).toBe("selected-context");
+    expect(resolveCreativeContextChipSelection({ contextMode: "auto" })).toBe(
+      "automatic",
+    );
+  });
+});

package/src/client/CreativeContextChip.tsx

@@ -0,0 +1,243 @@
+import { useT } from "@agent-native/core/client/i18n";
+import {
+  Badge,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from "@agent-native/toolkit/ui";
+import {
+  IconBrain,
+  IconCheck,
+  IconPin,
+  IconSettings,
+} from "@tabler/icons-react";
+
+import type { ContextPackSummary } from "../types.js";
+import {
+  parseCreativeContexts,
+  useCreativeContexts,
+  useCreativeContextPacks,
+  type CreativeContextSummary,
+} from "./actions.js";
+import { useCreativeContextState } from "./application-state.js";
+import type { CreativeContextApplicationState } from "./application-state.js";
+
+export interface CreativeContextChipProps {
+  state: CreativeContextApplicationState;
+  packs?: ContextPackSummary[];
+  contexts?: CreativeContextSummary[];
+  className?: string;
+}
+
+export type CreativeContextChipSelection =
+  | "off"
+  | "pinned-pack"
+  | "selected-context"
+  | "automatic";
+
+export function resolveCreativeContextChipSelection(
+  state: CreativeContextApplicationState,
+): CreativeContextChipSelection {
+  if (state.contextMode === "off") return "off";
+  if (state.pinnedPackId) return "pinned-pack";
+  if (state.selectedContextId) return "selected-context";
+  return "automatic";
+}
+
+export function hasCreativeContextConfiguration(
+  packs: ReadonlyArray<Pick<ContextPackSummary, "memberCount">>,
+  contexts: ReadonlyArray<Pick<CreativeContextSummary, "memberCount">>,
+): boolean {
+  return (
+    packs.some((pack) => pack.memberCount > 0) ||
+    contexts.some((context) => context.memberCount > 0)
+  );
+}
+
+export function CreativeContextChip({
+  state,
+  packs = [],
+  contexts = [],
+  className,
+}: CreativeContextChipProps) {
+  const t = useT();
+  const packId = state.pinnedPackId ?? state.currentPackId;
+  const pack = packs.find((candidate) => candidate.id === packId);
+  const context = contexts.find(
+    (candidate) => candidate.id === state.selectedContextId,
+  );
+  const selection = resolveCreativeContextChipSelection(state);
+  const label =
+    selection === "off"
+      ? t("creativeContext.off")
+      : selection === "pinned-pack"
+        ? pack?.name || packId
+        : selection === "selected-context"
+          ? context?.name || state.selectedContextId
+          : t("creativeContext.automatic");
+
+  return (
+    <Badge
+      variant="outline"
+      className={className}
+      title={pack?.description ?? undefined}
+    >
+      {state.pinnedPackId ? (
+        <IconPin className="me-1 size-3" />
+      ) : (
+        <IconBrain className="me-1 size-3" />
+      )}
+      <span className="max-w-44 truncate">{label}</span>
+    </Badge>
+  );
+}
+
+export function CreativeContextComposerChip({
+  href = "/settings/library",
+  className,
+}: {
+  href?: string;
+  className?: string;
+}) {
+  const t = useT();
+  const contextState = useCreativeContextState();
+  const packsQuery = useCreativeContextPacks();
+  const contextsQuery = useCreativeContexts();
+  const packs = packsQuery.data?.packs ?? [];
+  const contexts = parseCreativeContexts(contextsQuery.data);
+
+  if (!hasCreativeContextConfiguration(packs, contexts)) return null;
+
+  async function selectAutomatic() {
+    await contextState.setState({
+      ...contextState.state,
+      contextMode: "auto",
+      selectedContextId: null,
+      pinnedPackId: null,
+    });
+  }
+
+  async function selectOff() {
+    await contextState.setState({
+      contextMode: "off",
+      selectedContextId: null,
+      currentPackId: null,
+      pinnedPackId: null,
+    });
+  }
+
+  async function selectPack(packId: string) {
+    await contextState.setState({
+      ...contextState.state,
+      contextMode: "auto",
+      selectedContextId: null,
+      pinnedPackId: packId,
+    });
+  }
+
+  async function selectContext(contextId: string) {
+    await contextState.setState({
+      ...contextState.state,
+      contextMode: "auto",
+      selectedContextId: contextId,
+      pinnedPackId: null,
+    });
+  }
+
+  return (
+    <div className={className ?? "px-3 pb-1"}>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <button
+            type="button"
+            className="inline-flex max-w-full rounded-full outline-none ring-offset-background transition-opacity hover:opacity-80 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+          >
+            <CreativeContextChip
+              state={contextState.state}
+              packs={packs}
+              contexts={contexts}
+              className="max-w-full cursor-pointer bg-background/80"
+            />
+          </button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start" className="w-64">
+          <DropdownMenuLabel>
+            {t("creativeContext.modeLabel")}
+          </DropdownMenuLabel>
+          <DropdownMenuItem onSelect={() => void selectAutomatic()}>
+            {contextState.state.contextMode === "auto" &&
+            !contextState.state.pinnedPackId &&
+            !contextState.state.selectedContextId ? (
+              <IconCheck />
+            ) : (
+              <IconBrain />
+            )}
+            {t("creativeContext.automatic")}
+          </DropdownMenuItem>
+          <DropdownMenuItem onSelect={() => void selectOff()}>
+            {contextState.state.contextMode === "off" ? (
+              <IconCheck />
+            ) : (
+              <IconBrain />
+            )}
+            {t("creativeContext.off")}
+          </DropdownMenuItem>
+          {contexts.length ? (
+            <>
+              <DropdownMenuSeparator />
+              <DropdownMenuLabel>Contexts</DropdownMenuLabel>
+              {contexts.slice(0, 8).map((context) => (
+                <DropdownMenuItem
+                  key={context.id}
+                  onSelect={() => void selectContext(context.id)}
+                >
+                  {contextState.state.selectedContextId === context.id ? (
+                    <IconCheck />
+                  ) : (
+                    <IconBrain />
+                  )}
+                  <span className="truncate">{context.name}</span>
+                </DropdownMenuItem>
+              ))}
+            </>
+          ) : null}
+          {packs.length ? (
+            <DropdownMenuSub>
+              <DropdownMenuSubTrigger>
+                Advanced: pin an exact pack
+              </DropdownMenuSubTrigger>
+              <DropdownMenuSubContent className="w-64">
+                {packs.slice(0, 8).map((pack) => (
+                  <DropdownMenuItem
+                    key={pack.id}
+                    onSelect={() => void selectPack(pack.id)}
+                  >
+                    {contextState.state.pinnedPackId === pack.id ? (
+                      <IconCheck />
+                    ) : (
+                      <IconPin />
+                    )}
+                    <span className="truncate">{pack.name}</span>
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuSubContent>
+            </DropdownMenuSub>
+          ) : null}
+          <DropdownMenuSeparator />
+          <DropdownMenuItem asChild>
+            <a href={href}>
+              <IconSettings />
+              {t("creativeContext.title")}
+            </a>
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+}