@babav/knowledge-core-client 0.31.0 → 0.33.0

package/dist/index.d.ts

@@ -94,36 +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.
  *
- * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
- * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
- * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
- * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
- * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
- * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
- * failed); prefer `image` and treat `rendered_svg` as a last resort. */
+ * 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)` 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;
-    /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
-    image?: {
-        url: string;
+    /** 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;
-        expires_at?: number;
     };
-    /** Fail-soft fallback only (rasterize/store failed); normally absent. */
-    rendered_svg?: string;
+    /** 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
@@ -132,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;
@@ -541,6 +558,20 @@ export declare class KnowledgeCoreClient extends HttpBase {
      *  error). Pass `signal` and abort() on unmount / when the user cancels or navigates away so the
      *  connection doesn't linger. Transient (ends on `done`) — no reopen logic needed. */
     queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
+    /** Fetch a visual's PNG bytes BY ID. This is the ONLY way to get a visual image — the API never
+     *  returns a URL. Authenticated + tenant-scoped like every call. Use `visual.id` from a query
+     *  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).

package/dist/index.js

@@ -178,6 +178,33 @@ export class KnowledgeCoreClient extends HttpBase {
         if (buf.trim())
             dispatchSse(buf, handlers);
     }
+    /** Fetch a visual's PNG bytes BY ID. This is the ONLY way to get a visual image — the API never
+     *  returns a URL. Authenticated + tenant-scoped like every call. Use `visual.id` from a query
+     *  response / streamed `visual` event / persisted message. Returns a Blob (browser: `URL.
+     *  createObjectURL(blob)` for an <img>; Node: `Buffer.from(await blob.arrayBuffer())`). */
+    async getVisualImage(visualId, signal) {
+        const res = await this.raw("GET", `/v1/visuals/${visualId}/image`, { signal });
+        if (!res.ok) {
+            const t = await res.text();
+            throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/visuals/${visualId}/image`);
+        }
+        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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.31.0",
+  "version": "0.33.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,28 +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.
  *
- * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
- * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
- * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
- * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
- * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
- * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
- * failed); prefer `image` and treat `rendered_svg` as a last resort. */
+ * 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)` 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;
-  payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"svg"|"image", ...}
+  /** 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;
-  /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
-  image?: { url: string; width: number; height: number; expires_at?: number };
-  /** Fail-soft fallback only (rasterize/store failed); normally absent. */
-  rendered_svg?: string;
+  /** 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
@@ -160,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 {
@@ -359,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;
@@ -655,6 +675,39 @@ export class KnowledgeCoreClient extends HttpBase {
     if (buf.trim()) dispatchSse(buf, handlers);
   }
 
+  /** Fetch a visual's PNG bytes BY ID. This is the ONLY way to get a visual image — the API never
+   *  returns a URL. Authenticated + tenant-scoped like every call. Use `visual.id` from a query
+   *  response / streamed `visual` event / persisted message. Returns a Blob (browser: `URL.
+   *  createObjectURL(blob)` for an <img>; Node: `Buffer.from(await blob.arrayBuffer())`). */
+  async getVisualImage(visualId: UUID | string, signal?: AbortSignal): Promise<Blob> {
+    const res = await this.raw("GET", `/v1/visuals/${visualId}/image`, { signal });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/visuals/${visualId}/image`);
+    }
+    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).