@babav/knowledge-core-client 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -20,6 +20,7 @@
  * A missing baseUrl or apiKey throws at construction with a clear message.
  */
 export type UUID = string;
+export type { VisualEnvelope, VisualPayload, VisualElement, VisualComposition, VisualRegister, ChartBlockElement, } from "./visual/types.js";
 export interface Page<T> {
     items: T[];
     next_cursor: string | null;
@@ -64,12 +65,52 @@ export interface QueryOverrides {
     grounding_enabled?: boolean;
     citations_enabled?: boolean;
 }
+/** Per-request visual overrides (see VisualRequest). */
+export interface VisualOverrides {
+    concept_rounds_max?: number;
+    proposals_n?: number;
+    max_revisions?: number;
+    claims_check_model?: string;
+    vision_judge_model?: string;
+    scenic_enabled?: boolean;
+}
+/** Per-request visual control. Absent => mode resolves from the agent default. All visual
+ * PROCESSING is server-side; the client only displays the result. */
+export interface VisualRequest {
+    mode?: "off" | "on";
+    delivery?: "svg" | "json" | "both";
+    overrides?: VisualOverrides;
+}
 export interface QueryRequest {
     corpus_ids: UUID[];
     query: string;
     conversation_id?: UUID | null;
     overrides?: QueryOverrides;
     filter?: MetadataFilter;
+    visual?: VisualRequest;
+}
+/** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
+ * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
+export interface Visual {
+    id: string;
+    anchor: {
+        start: number;
+        end: number;
+    };
+    register: "chart" | "structural" | "conceptual" | "scenic";
+    priority: number;
+    payload: Record<string, unknown>;
+    rendered_svg?: string;
+    image?: {
+        url: string;
+        expires_at: number;
+        width: number;
+        height: number;
+    };
+}
+export interface VisualsMeta {
+    count: number;
+    dropped: number;
 }
 export interface QueryResponse {
     conversation_id: UUID | null;
@@ -80,6 +121,8 @@ export interface QueryResponse {
     groundedness: Groundedness | null;
     usage: Record<string, number | null>;
     standalone_query: string | null;
+    visuals?: Visual[];
+    visuals_meta?: VisualsMeta | null;
 }
 export interface Citation {
     /** Char span IN THE ANSWER this citation supports (for highlighting). */
@@ -182,6 +225,10 @@ export interface Message {
     groundedness: Record<string, unknown> | null;
     retrieval_contents: unknown[] | null;
     usage: Record<string, unknown> | null;
+    visuals?: {
+        items: Visual[];
+        meta: VisualsMeta;
+    } | null;
 }
 export interface Attachment {
     id: UUID;
@@ -290,6 +337,11 @@ export interface StreamHandlers {
      *  (native path). Also present in `final`. May be `{}` if scoring was unavailable. */
     onGroundedness?: (g: Groundedness | Record<string, never>) => void;
     onFinal?: (d: QueryResponse) => void;
+    /** A visual, emitted (out of anchor order) during the trailing visual phase when
+     *  visual.mode="on". Place by `anchor`, not arrival order. */
+    onVisual?: (v: Visual) => void;
+    /** Always emitted exactly once to close the visual phase (incl. count=0), before `done`. */
+    onVisualsComplete?: (m: VisualsMeta) => void;
     onError?: (d: unknown) => void;
     onDone?: () => void;
     /** Catch-all for any event (incl. unknown ones). */
@@ -528,4 +580,3 @@ export declare class AdminClient extends HttpBase {
         delete: (id: UUID) => Promise<void>;
     };
 }
-export {};

package/dist/index.js

@@ -364,6 +364,12 @@ function dispatchSse(frame, h) {
         case "final":
             h.onFinal?.(data);
             break;
+        case "visual":
+            h.onVisual?.(data);
+            break;
+        case "visuals_complete":
+            h.onVisualsComplete?.(data);
+            break;
         case "error":
             h.onError?.(data);
             break;

package/dist/visual/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@babav/knowledge-core-client/visual` — the babav.visual grammar TYPES.
+ *
+ * Types only (zero runtime, zero deps): they let a client type the visual payloads it may
+ * receive. All visual PROCESSING — grammar validation, layout, and SVG/PNG rendering — runs
+ * SERVER-SIDE in render-service; the client only displays the server-produced SVG/image.
+ * The schema + validators + renderers therefore live in render-service, not here.
+ */
+export * from "./types.js";

package/dist/visual/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@babav/knowledge-core-client/visual` — the babav.visual grammar TYPES.
+ *
+ * Types only (zero runtime, zero deps): they let a client type the visual payloads it may
+ * receive. All visual PROCESSING — grammar validation, layout, and SVG/PNG rendering — runs
+ * SERVER-SIDE in render-service; the client only displays the server-produced SVG/image.
+ * The schema + validators + renderers therefore live in render-service, not here.
+ */
+export * from "./types.js";

package/dist/visual/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `babav.visual` grammar — TypeScript types (WP1a).
+ *
+ * The typed structural-composition language the visual pipeline emits for the
+ * `structural` register (and the envelope that wraps every register's payload). Uses
+ * vocabulary models already know — nodes, connectors (edges), containers/panels
+ * (clusters), composition operators. LLMs compose in this grammar; a deterministic
+ * engine (ELK) does layout — models never emit coordinates.
+ *
+ * NB: the grammar uses its own camelCase convention (`chartBlock`, `vegaLiteSpec`,
+ * `focalElement`) per the visual spec — distinct from the KC API's snake_case wire
+ * shapes. Versioned from the first commit (`version: "1"`).
+ */
+export type VisualRegister = "chart" | "structural" | "conceptual" | "scenic";
+export type EmphasisLevel = "normal" | "strong" | "muted";
+export type ConnectorKind = "flow" | "dependency" | "association" | "containment" | "bidirectional";
+export interface NodeElement {
+    type: "node";
+    id: string;
+    label: string;
+    role?: string;
+    emphasis?: EmphasisLevel;
+}
+export interface ConnectorElement {
+    type: "connector";
+    id?: string;
+    from: string;
+    to: string;
+    label?: string;
+    kind: ConnectorKind;
+}
+export interface ContainerElement {
+    type: "container";
+    id: string;
+    label?: string;
+    children: string[];
+}
+export interface PanelElement {
+    type: "panel";
+    id: string;
+    title?: string;
+    children: string[];
+}
+export interface AnnotationElement {
+    type: "annotation";
+    id?: string;
+    target: string;
+    text: string;
+}
+export interface ChartBlockElement {
+    type: "chartBlock";
+    id: string;
+    vegaLiteSpec: Record<string, unknown>;
+}
+export type VisualElement = NodeElement | ConnectorElement | ContainerElement | PanelElement | AnnotationElement | ChartBlockElement;
+export interface NestComposition {
+    op: "nest";
+    parent: string;
+    children: string[];
+}
+export interface SequenceComposition {
+    op: "sequence";
+    items: string[];
+}
+export interface JuxtaposeComposition {
+    op: "juxtapose";
+    items: string[];
+}
+export interface LayerComposition {
+    op: "layer";
+    items: string[];
+}
+export interface LinkComposition {
+    op: "link";
+    from: string;
+    to: string;
+    label?: string;
+    kind?: ConnectorKind;
+}
+export type VisualComposition = NestComposition | SequenceComposition | JuxtaposeComposition | LayerComposition | LinkComposition;
+export type Orientation = "horizontal" | "vertical" | "radial";
+export type Density = "compact" | "comfortable" | "spacious";
+export interface LayoutIntent {
+    orientation?: Orientation;
+    density?: Density;
+    focalElement?: string;
+}
+export interface VisualPayload {
+    elements: VisualElement[];
+    composition?: VisualComposition[];
+    layout?: LayoutIntent;
+}
+/** Per-element source provenance. Present from v1; populated in Phase 2. */
+export interface VisualProvenance {
+    [k: string]: unknown;
+}
+/** The envelope wrapping every register's payload. */
+export interface VisualEnvelope {
+    schema: "babav.visual";
+    version: "1";
+    register: VisualRegister;
+    gist?: string;
+    provenance?: VisualProvenance[];
+    payload: VisualPayload;
+}

package/dist/visual/types.js

@@ -0,0 +1,14 @@
+/**
+ * `babav.visual` grammar — TypeScript types (WP1a).
+ *
+ * The typed structural-composition language the visual pipeline emits for the
+ * `structural` register (and the envelope that wraps every register's payload). Uses
+ * vocabulary models already know — nodes, connectors (edges), containers/panels
+ * (clusters), composition operators. LLMs compose in this grammar; a deterministic
+ * engine (ELK) does layout — models never emit coordinates.
+ *
+ * NB: the grammar uses its own camelCase convention (`chartBlock`, `vegaLiteSpec`,
+ * `focalElement`) per the visual spec — distinct from the KC API's snake_case wire
+ * shapes. Versioned from the first commit (`version: "1"`).
+ */
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.18.0",
-  "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps).",
+  "version": "0.20.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",
   "types": "./dist/index.d.ts",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./visual": {
+      "types": "./dist/visual/index.d.ts",
+      "import": "./dist/visual/index.js"
     }
   },
   "files": [

package/src/index.ts

@@ -25,6 +25,18 @@
 // ---------------------------------------------------------------------------
 export type UUID = string;
 
+// The babav.visual grammar (WP1a). Types are re-exported here for convenience; the full
+// grammar (schema + validators + fixtures) lives at the `./visual` subpath so it can pull
+// its optional `ajv` peer without adding any dependency to this main entry.
+export type {
+  VisualEnvelope,
+  VisualPayload,
+  VisualElement,
+  VisualComposition,
+  VisualRegister,
+  ChartBlockElement,
+} from "./visual/types.js";
+
 export interface Page<T> {
   items: T[];
   next_cursor: string | null;
@@ -75,12 +87,48 @@ export interface QueryOverrides {
   citations_enabled?: boolean;   // source attribution (default on)
 }
 
+/** Per-request visual overrides (see VisualRequest). */
+export interface VisualOverrides {
+  concept_rounds_max?: number;
+  proposals_n?: number;
+  max_revisions?: number;
+  claims_check_model?: string;
+  vision_judge_model?: string;
+  scenic_enabled?: boolean;
+}
+
+/** Per-request visual control. Absent => mode resolves from the agent default. All visual
+ * PROCESSING is server-side; the client only displays the result. */
+export interface VisualRequest {
+  mode?: "off" | "on";
+  delivery?: "svg" | "json" | "both";
+  overrides?: VisualOverrides;
+}
+
 export interface QueryRequest {
   corpus_ids: UUID[];
   query: string;
   conversation_id?: UUID | null; // present => conversational; absent => one-shot
   overrides?: QueryOverrides;
   filter?: MetadataFilter;
+  visual?: VisualRequest;
+}
+
+/** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
+ * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
+export interface Visual {
+  id: string;
+  anchor: { start: number; end: number };
+  register: "chart" | "structural" | "conceptual" | "scenic";
+  priority: number;
+  payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"svg"|"image", ...}
+  rendered_svg?: string;
+  image?: { url: string; expires_at: number; width: number; height: number };
+}
+
+export interface VisualsMeta {
+  count: number;
+  dropped: number;
 }
 
 export interface QueryResponse {
@@ -92,6 +140,8 @@ export interface QueryResponse {
   groundedness: Groundedness | null;
   usage: Record<string, number | null>;
   standalone_query: string | null;
+  visuals?: Visual[]; // [] when off/none
+  visuals_meta?: VisualsMeta | null;
 }
 
 export interface Citation {
@@ -195,6 +245,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)
 }
 export interface Attachment {
   id: UUID;
@@ -405,6 +456,11 @@ export interface StreamHandlers {
    *  (native path). Also present in `final`. May be `{}` if scoring was unavailable. */
   onGroundedness?: (g: Groundedness | Record<string, never>) => void;
   onFinal?: (d: QueryResponse) => void;
+  /** A visual, emitted (out of anchor order) during the trailing visual phase when
+   *  visual.mode="on". Place by `anchor`, not arrival order. */
+  onVisual?: (v: Visual) => void;
+  /** Always emitted exactly once to close the visual phase (incl. count=0), before `done`. */
+  onVisualsComplete?: (m: VisualsMeta) => void;
   onError?: (d: unknown) => void;
   onDone?: () => void;
   /** Catch-all for any event (incl. unknown ones). */
@@ -653,6 +709,8 @@ function dispatchSse(frame: string, h: StreamHandlers): void {
     case "citation": h.onCitation?.(data as Citation); break;
     case "groundedness": h.onGroundedness?.(data as never); break;
     case "final": h.onFinal?.(data as QueryResponse); break;
+    case "visual": h.onVisual?.(data as Visual); break;
+    case "visuals_complete": h.onVisualsComplete?.(data as VisualsMeta); break;
     case "error": h.onError?.(data); break;
     case "done": h.onDone?.(); break;
   }

package/src/visual/index.ts

@@ -0,0 +1,10 @@
+/**
+ * `@babav/knowledge-core-client/visual` — the babav.visual grammar TYPES.
+ *
+ * Types only (zero runtime, zero deps): they let a client type the visual payloads it may
+ * receive. All visual PROCESSING — grammar validation, layout, and SVG/PNG rendering — runs
+ * SERVER-SIDE in render-service; the client only displays the server-produced SVG/image.
+ * The schema + validators + renderers therefore live in render-service, not here.
+ */
+
+export * from "./types.js";

package/src/visual/types.ts

@@ -0,0 +1,132 @@
+/**
+ * `babav.visual` grammar — TypeScript types (WP1a).
+ *
+ * The typed structural-composition language the visual pipeline emits for the
+ * `structural` register (and the envelope that wraps every register's payload). Uses
+ * vocabulary models already know — nodes, connectors (edges), containers/panels
+ * (clusters), composition operators. LLMs compose in this grammar; a deterministic
+ * engine (ELK) does layout — models never emit coordinates.
+ *
+ * NB: the grammar uses its own camelCase convention (`chartBlock`, `vegaLiteSpec`,
+ * `focalElement`) per the visual spec — distinct from the KC API's snake_case wire
+ * shapes. Versioned from the first commit (`version: "1"`).
+ */
+
+export type VisualRegister = "chart" | "structural" | "conceptual" | "scenic";
+
+export type EmphasisLevel = "normal" | "strong" | "muted";
+export type ConnectorKind =
+  | "flow"
+  | "dependency"
+  | "association"
+  | "containment"
+  | "bidirectional";
+
+// --- Layer A: primitives (each drawable element; `type`-discriminated) --------
+export interface NodeElement {
+  type: "node";
+  id: string;
+  label: string;
+  role?: string;
+  emphasis?: EmphasisLevel;
+}
+export interface ConnectorElement {
+  type: "connector";
+  id?: string;
+  from: string; // node id
+  to: string; // node id
+  label?: string;
+  kind: ConnectorKind;
+}
+export interface ContainerElement {
+  type: "container";
+  id: string;
+  label?: string;
+  children: string[]; // element ids
+}
+export interface PanelElement {
+  type: "panel";
+  id: string;
+  title?: string;
+  children: string[]; // element ids
+}
+export interface AnnotationElement {
+  type: "annotation";
+  id?: string;
+  target: string; // element id
+  text: string;
+}
+export interface ChartBlockElement {
+  type: "chartBlock";
+  id: string;
+  vegaLiteSpec: Record<string, unknown>; // whitelisted subset enforced at render time
+}
+export type VisualElement =
+  | NodeElement
+  | ConnectorElement
+  | ContainerElement
+  | PanelElement
+  | AnnotationElement
+  | ChartBlockElement;
+
+// --- Layer B: composition (arrangement over element ids; `op`-discriminated) --
+export interface NestComposition {
+  op: "nest";
+  parent: string;
+  children: string[];
+}
+export interface SequenceComposition {
+  op: "sequence";
+  items: string[];
+}
+export interface JuxtaposeComposition {
+  op: "juxtapose";
+  items: string[];
+}
+export interface LayerComposition {
+  op: "layer";
+  items: string[];
+}
+export interface LinkComposition {
+  op: "link";
+  from: string;
+  to: string;
+  label?: string;
+  kind?: ConnectorKind;
+}
+export type VisualComposition =
+  | NestComposition
+  | SequenceComposition
+  | JuxtaposeComposition
+  | LayerComposition
+  | LinkComposition;
+
+// --- Layout intent: hints only; the engine decides -------------------------
+export type Orientation = "horizontal" | "vertical" | "radial";
+export type Density = "compact" | "comfortable" | "spacious";
+export interface LayoutIntent {
+  orientation?: Orientation;
+  density?: Density;
+  focalElement?: string; // element id
+}
+
+export interface VisualPayload {
+  elements: VisualElement[];
+  composition?: VisualComposition[];
+  layout?: LayoutIntent;
+}
+
+/** Per-element source provenance. Present from v1; populated in Phase 2. */
+export interface VisualProvenance {
+  [k: string]: unknown;
+}
+
+/** The envelope wrapping every register's payload. */
+export interface VisualEnvelope {
+  schema: "babav.visual";
+  version: "1";
+  register: VisualRegister;
+  gist?: string;
+  provenance?: VisualProvenance[];
+  payload: VisualPayload;
+}