@babav/knowledge-core-client 0.32.0 → 0.34.0

package/dist/index.d.ts

@@ -94,30 +94,37 @@ export interface QueryRequest {
  * "free" = renderer's judgment / not a declared arrangement (also the value for non-conceptual
  * registers). */
 export type VisualLayout = "linear-flow" | "ring-cycle" | "nesting" | "radial-hub" | "side-by-side" | "stacked-layers" | "two-state" | "free";
-/** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
- * system as citations).
+/** A visual attached to a response.
  *
  * IDs-ONLY: the API never returns a URL. Every visual (chart / structural / conceptual / scenic) is
- * a PNG served by KC and identified by its `id`. To display it, fetch the bytes by id:
- * `getVisualImage(visual.id)` (or GET /v1/visuals/{id}/image with your API key). `image` carries only
- * the pixel DIMENSIONS, for layout. The image is authenticated + tenant-scoped exactly like every
- * other KC call; there is no URL, no signed GCS link, and nothing to expire. */
+ * a PNG served by KC and identified by its `id`. To display it, fetch the bytes by id —
+ * `getVisualImage(visual.id)` for one, or `getVisualImages([...ids])` to fetch a whole answer's
+ * visuals in a SINGLE call (no per-visual fan-out). The image is authenticated + tenant-scoped
+ * exactly like every other KC call; there is no URL, no signed GCS link. */
 export interface Visual {
     id: string;
-    anchor: {
+    /** Char offsets into `answer` (SAME coordinate system as citations). OPTIONAL: a visual may be
+     *  anchorless (belongs in the trailing strip) — when absent, place it after the answer. */
+    anchor?: {
         start: number;
         end: number;
     };
     register: "chart" | "structural" | "conceptual" | "scenic";
-    priority: number;
+    /** Client display ordering (higher first). OPTIONAL — default to 0 / arrival order if absent. */
+    priority?: number;
     payload: Record<string, unknown>;
     /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
     layout: VisualLayout;
-    /** Pixel dimensions of the PNG (for layout). Fetch the bytes with getVisualImage(id). */
-    image?: {
+    /** Pixel dimensions of the PNG — ALWAYS present on a shipped visual, so the UI can reserve space
+     *  before the bytes arrive (no layout shift). Fetch the bytes with getVisualImage(id). */
+    image: {
         width: number;
         height: number;
     };
+    /** Short KC-authored figure caption (the idea the visual carries). Present when authored. */
+    caption?: string;
+    /** Plain-text description for screen readers / accessible PDF·DOCX·LaTeX export. Present when authored. */
+    alt?: string;
 }
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with
  *  `pending: null` (started, count unknown), then again with the ACCURATE post-vet count before
@@ -126,8 +133,24 @@ export interface VisualsPending {
     pending: number | null;
 }
 export interface VisualsMeta {
+    /** Visuals that shipped (authoritative — always matches the number of `visual` events). */
     count: number;
+    /** Concepts accepted by the vet but not shipped (render_failed + timeout). */
     dropped: number;
+    /** Counts-by-cause for every PROPOSED concept that did not become a visible visual, so a missing
+     *  visual is explainable rather than silent. Keys (zero causes omitted):
+     *   - `declined`      the vet declined/trimmed the concept (never promised; reduces the pending count)
+     *   - `render_failed` accepted but authoring/rendering/vision-review dropped it
+     *   - `timeout`       accepted but the post-answer render budget cut it off
+     *  `dropped` = render_failed + timeout; `declined` is extra context beyond `dropped`. */
+    dropped_reasons?: Record<string, number>;
+}
+/** One image returned by getVisualImages(). `blob` is the PNG (browser: `URL.createObjectURL(blob)`). */
+export interface VisualImage {
+    id: string;
+    blob: Blob;
+    width: number;
+    height: number;
 }
 export interface QueryResponse {
     conversation_id: UUID | null;
@@ -394,6 +417,7 @@ export interface Feedback {
 }
 export interface Agent {
     id: UUID;
+    tenant_id: UUID | null;
     name: string;
     identity_prompt: string | null;
     response_prompt: string | null;
@@ -412,6 +436,41 @@ export interface Agent {
     groundedness_threshold: number | null;
     grounding_enabled: boolean | null;
     citations_enabled: boolean | null;
+    visual_mode_default: string | null;
+    visual_concept_model: string | null;
+    visual_concept_vet_model: string | null;
+    visual_proposer_model: string | null;
+    visual_claims_check_model: string | null;
+    visual_vision_judge_model: string | null;
+    visual_max_revisions: number | null;
+    visual_combine_generation_and_concept: boolean | null;
+    concept_model_mode: string | null;
+}
+/** Fields settable when creating/updating an agent. All optional (null/omit => server default); model
+ *  fields must be one of `getModelOptions().fields[field].supported`. `tenant_id` is create-only. */
+export type AgentWrite = Partial<Omit<Agent, "id" | "tenant_id">>;
+/** Model catalog for the agent-config UI (GET /v1/agents/model-options). `models` maps id → its
+ *  capabilities; `fields` gives each agent model-field its supported ids + default (+ usage metadata);
+ *  `modes` says which model field governs each mode (reasoning is valid only if that model's
+ *  supports_reasoning is true). KC provides the data; the UI decides presentation. */
+export interface ModelOptions {
+    models: Record<string, {
+        label: string;
+        provider: "anthropic" | "vertex";
+        kind: "text" | "vision";
+        supports_reasoning: boolean;
+    }>;
+    fields: Record<string, {
+        supported: string[];
+        default: string;
+        applies_when?: string;
+        applies_to?: string[];
+        note?: string;
+    }>;
+    modes: Record<string, {
+        depends_on: string;
+        values: string[];
+    }>;
 }
 export interface Tenant {
     id: UUID;
@@ -540,6 +599,15 @@ export declare class KnowledgeCoreClient extends HttpBase {
      *  response / streamed `visual` event / persisted message. Returns a Blob (browser: `URL.
      *  createObjectURL(blob)` for an <img>; Node: `Buffer.from(await blob.arrayBuffer())`). */
     getVisualImage(visualId: UUID | string, signal?: AbortSignal): Promise<Blob>;
+    /** Fetch MANY visual PNGs in ONE call — the way to load all of an answer's (or a conversation's)
+     *  visuals without a per-visual round trip. Pass up to 32 ids; over that, split into chunks (the
+     *  API returns 400 `too_many_ids`). Returns the found images (as Blobs, ready for
+     *  `URL.createObjectURL`) plus `missing` — ids with no stored image (reaped/expired), which the UI
+     *  can show as "visual no longer available". Order of `images` is not guaranteed; key by `id`. */
+    getVisualImages(visualIds: Array<UUID | string>, signal?: AbortSignal): Promise<{
+        images: VisualImage[];
+        missing: string[];
+    }>;
     /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
      *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
      *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
@@ -891,28 +959,15 @@ export declare class AdminClient extends HttpBase {
         revokeApiKey: (tenantId: UUID, keyId: UUID) => Promise<void>;
     };
     agents: {
-        create: (b: {
+        create: (b: AgentWrite & {
             name: string;
-            identity_prompt?: string;
-            response_prompt?: string;
-            generation_model?: string;
-            generation_model_mode?: string;
-            max_response_tokens?: number;
-            top_k_retrieved_chunks?: number;
-            top_k_reranked_chunks?: number;
-            sibling_window?: number;
-            rerank_instruction?: string;
-            max_subqueries?: number;
-            max_reasoning_rounds?: number;
-            decomposition_model?: string;
-            reasoning_inspect_model?: string;
-            groundedness_verifier_model?: string;
-            groundedness_threshold?: number;
-            grounding_enabled?: boolean;
-            citations_enabled?: boolean;
+            tenant_id?: UUID | null;
         }) => Promise<Agent>;
-        update: (id: UUID, b: Partial<Omit<Agent, "id">>) => Promise<Agent>;
+        update: (id: UUID, b: AgentWrite) => Promise<Agent>;
         delete: (id: UUID) => Promise<void>;
+        /** The model catalog for an agent-config UI: supported models + default per field, per-model
+         *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
+        modelOptions: () => Promise<ModelOptions>;
     };
 }
 export interface ChatSendOptions extends StreamHandlers {

package/dist/index.js

@@ -190,6 +190,21 @@ export class KnowledgeCoreClient extends HttpBase {
         }
         return await res.blob();
     }
+    /** Fetch MANY visual PNGs in ONE call — the way to load all of an answer's (or a conversation's)
+     *  visuals without a per-visual round trip. Pass up to 32 ids; over that, split into chunks (the
+     *  API returns 400 `too_many_ids`). Returns the found images (as Blobs, ready for
+     *  `URL.createObjectURL`) plus `missing` — ids with no stored image (reaped/expired), which the UI
+     *  can show as "visual no longer available". Order of `images` is not guaranteed; key by `id`. */
+    async getVisualImages(visualIds, signal) {
+        if (visualIds.length === 0)
+            return { images: [], missing: [] };
+        const r = await this.request("POST", "/v1/visuals/images", { json: { ids: visualIds }, signal });
+        const images = r.images.map((im) => {
+            const bytes = Uint8Array.from(atob(im.png_base64), (c) => c.charCodeAt(0));
+            return { id: im.id, blob: new Blob([bytes], { type: "image/png" }), width: im.width, height: im.height };
+        });
+        return { images, missing: r.missing ?? [] };
+    }
     /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
      *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
      *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
@@ -475,11 +490,15 @@ export class AdminClient extends HttpBase {
         listApiKeys: (tenantId, q) => this.request("GET", `/v1/tenants/${tenantId}/api-keys`, { query: q }),
         revokeApiKey: (tenantId, keyId) => this.request("DELETE", `/v1/tenants/${tenantId}/api-keys/${keyId}`),
     };
-    // Agents are query agents, global for now.
+    // Agent provisioning (query agents). Pass `tenant_id` on create for a per-tenant agent; omit (or
+    // null) for a Babav-global one. Model fields are validated against the model registry server-side.
     agents = {
         create: (b) => this.request("POST", "/v1/agents", { json: b }),
         update: (id, b) => this.request("PATCH", `/v1/agents/${id}`, { json: b }),
         delete: (id) => this.request("DELETE", `/v1/agents/${id}`),
+        /** The model catalog for an agent-config UI: supported models + default per field, per-model
+         *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
+        modelOptions: () => this.request("GET", "/v1/agents/model-options"),
     };
 }
 /** A chat session bound to ONE conversation (created via `kc.chat(...)`). Every `send()` is ALWAYS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps). Includes the babav.visual grammar TYPES at the ./visual subpath (types only; all visual rendering is server-side).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -128,24 +128,31 @@ export type VisualLayout =
   | "two-state"
   | "free";
 
-/** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
- * system as citations).
+/** A visual attached to a response.
  *
  * IDs-ONLY: the API never returns a URL. Every visual (chart / structural / conceptual / scenic) is
- * a PNG served by KC and identified by its `id`. To display it, fetch the bytes by id:
- * `getVisualImage(visual.id)` (or GET /v1/visuals/{id}/image with your API key). `image` carries only
- * the pixel DIMENSIONS, for layout. The image is authenticated + tenant-scoped exactly like every
- * other KC call; there is no URL, no signed GCS link, and nothing to expire. */
+ * a PNG served by KC and identified by its `id`. To display it, fetch the bytes by id —
+ * `getVisualImage(visual.id)` for one, or `getVisualImages([...ids])` to fetch a whole answer's
+ * visuals in a SINGLE call (no per-visual fan-out). The image is authenticated + tenant-scoped
+ * exactly like every other KC call; there is no URL, no signed GCS link. */
 export interface Visual {
   id: string;
-  anchor: { start: number; end: number };
+  /** Char offsets into `answer` (SAME coordinate system as citations). OPTIONAL: a visual may be
+   *  anchorless (belongs in the trailing strip) — when absent, place it after the answer. */
+  anchor?: { start: number; end: number };
   register: "chart" | "structural" | "conceptual" | "scenic";
-  priority: number;
+  /** Client display ordering (higher first). OPTIONAL — default to 0 / arrival order if absent. */
+  priority?: number;
   payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"image", ...}
   /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
   layout: VisualLayout;
-  /** Pixel dimensions of the PNG (for layout). Fetch the bytes with getVisualImage(id). */
-  image?: { width: number; height: number };
+  /** Pixel dimensions of the PNG — ALWAYS present on a shipped visual, so the UI can reserve space
+   *  before the bytes arrive (no layout shift). Fetch the bytes with getVisualImage(id). */
+  image: { width: number; height: number };
+  /** Short KC-authored figure caption (the idea the visual carries). Present when authored. */
+  caption?: string;
+  /** Plain-text description for screen readers / accessible PDF·DOCX·LaTeX export. Present when authored. */
+  alt?: string;
 }
 
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with
@@ -156,8 +163,25 @@ export interface VisualsPending {
 }
 
 export interface VisualsMeta {
+  /** Visuals that shipped (authoritative — always matches the number of `visual` events). */
   count: number;
+  /** Concepts accepted by the vet but not shipped (render_failed + timeout). */
   dropped: number;
+  /** Counts-by-cause for every PROPOSED concept that did not become a visible visual, so a missing
+   *  visual is explainable rather than silent. Keys (zero causes omitted):
+   *   - `declined`      the vet declined/trimmed the concept (never promised; reduces the pending count)
+   *   - `render_failed` accepted but authoring/rendering/vision-review dropped it
+   *   - `timeout`       accepted but the post-answer render budget cut it off
+   *  `dropped` = render_failed + timeout; `declined` is extra context beyond `dropped`. */
+  dropped_reasons?: Record<string, number>;
+}
+
+/** One image returned by getVisualImages(). `blob` is the PNG (browser: `URL.createObjectURL(blob)`). */
+export interface VisualImage {
+  id: string;
+  blob: Blob;
+  width: number;
+  height: number;
 }
 
 export interface QueryResponse {
@@ -355,7 +379,7 @@ export interface Message {
   groundedness: Record<string, unknown> | null;
   retrieval_contents: unknown[] | null;
   usage: Record<string, unknown> | null;
-  visuals?: { items: Visual[]; meta: VisualsMeta } | null; // post-generation visuals (re-signed URLs on read)
+  visuals?: { items: Visual[]; meta: VisualsMeta } | null; // persisted visuals; fetch bytes by id (getVisualImages)
 }
 export interface Attachment {
   id: UUID;
@@ -375,6 +399,7 @@ export interface Feedback {
 }
 export interface Agent {
   id: UUID;
+  tenant_id: UUID | null;            // null => Babav-global agent; a tenant id => per-tenant
   name: string;
   identity_prompt: string | null;   // answer-system: who/purpose (null => server default)
   response_prompt: string | null;   // answer-system: output guidelines (null => server default)
@@ -393,6 +418,30 @@ export interface Agent {
   groundedness_threshold: number | null;
   grounding_enabled: boolean | null;
   citations_enabled: boolean | null;
+  // Visual pipeline defaults (null => server default; overridable per request).
+  visual_mode_default: string | null;        // "off" | "on"
+  visual_concept_model: string | null;
+  visual_concept_vet_model: string | null;
+  visual_proposer_model: string | null;      // authors the HTML figure + chart/structural/scene specs
+  visual_claims_check_model: string | null;
+  visual_vision_judge_model: string | null;  // Vertex Gemini model
+  visual_max_revisions: number | null;
+  visual_combine_generation_and_concept: boolean | null;
+  concept_model_mode: string | null;         // "reasoning" | "standard"; overrules gen mode when combining
+}
+
+/** Fields settable when creating/updating an agent. All optional (null/omit => server default); model
+ *  fields must be one of `getModelOptions().fields[field].supported`. `tenant_id` is create-only. */
+export type AgentWrite = Partial<Omit<Agent, "id" | "tenant_id">>;
+
+/** Model catalog for the agent-config UI (GET /v1/agents/model-options). `models` maps id → its
+ *  capabilities; `fields` gives each agent model-field its supported ids + default (+ usage metadata);
+ *  `modes` says which model field governs each mode (reasoning is valid only if that model's
+ *  supports_reasoning is true). KC provides the data; the UI decides presentation. */
+export interface ModelOptions {
+  models: Record<string, { label: string; provider: "anthropic" | "vertex"; kind: "text" | "vision"; supports_reasoning: boolean }>;
+  fields: Record<string, { supported: string[]; default: string; applies_when?: string; applies_to?: string[]; note?: string }>;
+  modes: Record<string, { depends_on: string; values: string[] }>;
 }
 export interface Tenant {
   id: UUID;
@@ -664,6 +713,26 @@ export class KnowledgeCoreClient extends HttpBase {
     return await res.blob();
   }
 
+  /** Fetch MANY visual PNGs in ONE call — the way to load all of an answer's (or a conversation's)
+   *  visuals without a per-visual round trip. Pass up to 32 ids; over that, split into chunks (the
+   *  API returns 400 `too_many_ids`). Returns the found images (as Blobs, ready for
+   *  `URL.createObjectURL`) plus `missing` — ids with no stored image (reaped/expired), which the UI
+   *  can show as "visual no longer available". Order of `images` is not guaranteed; key by `id`. */
+  async getVisualImages(
+    visualIds: Array<UUID | string>,
+    signal?: AbortSignal,
+  ): Promise<{ images: VisualImage[]; missing: string[] }> {
+    if (visualIds.length === 0) return { images: [], missing: [] };
+    const r = await this.request<{ images: Array<{ id: string; png_base64: string; width: number; height: number }>; missing: string[] }>(
+      "POST", "/v1/visuals/images", { json: { ids: visualIds }, signal },
+    );
+    const images = r.images.map((im) => {
+      const bytes = Uint8Array.from(atob(im.png_base64), (c) => c.charCodeAt(0));
+      return { id: im.id, blob: new Blob([bytes], { type: "image/png" }), width: im.width, height: im.height };
+    });
+    return { images, missing: r.missing ?? [] };
+  }
+
   /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
    *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
    *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
@@ -1021,13 +1090,17 @@ export class AdminClient extends HttpBase {
     revokeApiKey: (tenantId: UUID, keyId: UUID) => this.request<void>("DELETE", `/v1/tenants/${tenantId}/api-keys/${keyId}`),
   };
 
-  // Agents are query agents, global for now.
+  // Agent provisioning (query agents). Pass `tenant_id` on create for a per-tenant agent; omit (or
+  // null) for a Babav-global one. Model fields are validated against the model registry server-side.
   agents = {
-    create: (b: { name: string; identity_prompt?: string; response_prompt?: string; generation_model?: string; generation_model_mode?: string; max_response_tokens?: number; top_k_retrieved_chunks?: number; top_k_reranked_chunks?: number; sibling_window?: number; rerank_instruction?: string; max_subqueries?: number; max_reasoning_rounds?: number; decomposition_model?: string; reasoning_inspect_model?: string; groundedness_verifier_model?: string; groundedness_threshold?: number; grounding_enabled?: boolean; citations_enabled?: boolean }) =>
+    create: (b: AgentWrite & { name: string; tenant_id?: UUID | null }) =>
       this.request<Agent>("POST", "/v1/agents", { json: b }),
-    update: (id: UUID, b: Partial<Omit<Agent, "id">>) =>
+    update: (id: UUID, b: AgentWrite) =>
       this.request<Agent>("PATCH", `/v1/agents/${id}`, { json: b }),
     delete: (id: UUID) => this.request<void>("DELETE", `/v1/agents/${id}`),
+    /** The model catalog for an agent-config UI: supported models + default per field, per-model
+     *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
+    modelOptions: () => this.request<ModelOptions>("GET", "/v1/agents/model-options"),
   };
 }