@babav/knowledge-core-client 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -90,6 +90,10 @@ export interface QueryRequest {
     filter?: MetadataFilter;
     visual?: VisualRequest;
 }
+/** The spatial arrangement a conceptual visual encodes (the geometry that carries the meaning).
+ * "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). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
 export interface Visual {
@@ -101,6 +105,8 @@ export interface Visual {
     register: "chart" | "structural" | "conceptual" | "scenic";
     priority: number;
     payload: Record<string, unknown>;
+    /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
+    layout: VisualLayout;
     rendered_svg?: string;
     image?: {
         url: string;
@@ -462,8 +468,12 @@ declare class HttpBase {
     protected pageAll<T>(path: string, query?: RequestOpts["query"]): Promise<T[]>;
 }
 export interface StreamHandlers {
+    /** Retrieval milestone. `retrieval_contents` is the reranked top_k (unchanged).
+     *  `retrieved_count` is the total distinct candidate chunks fetched across ALL corpora
+     *  (and sub-queries) BEFORE reranking/truncation — i.e. the recall-net size. */
     onSources?: (d: {
         retrieval_contents: RetrievalContent[];
+        retrieved_count: number;
     }) => void;
     onToken?: (text: string) => void;
     /** A citation, emitted inline as the answer streams (Claude/native path). Also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.26.0",
+  "version": "0.28.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

@@ -115,6 +115,19 @@ export interface QueryRequest {
   visual?: VisualRequest;
 }
 
+/** The spatial arrangement a conceptual visual encodes (the geometry that carries the meaning).
+ * "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). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
 export interface Visual {
@@ -123,6 +136,8 @@ export interface Visual {
   register: "chart" | "structural" | "conceptual" | "scenic";
   priority: number;
   payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"svg"|"image", ...}
+  /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
+  layout: VisualLayout;
   rendered_svg?: string;
   image?: { url: string; expires_at: number; width: number; height: number };
 }
@@ -536,7 +551,10 @@ const MULTIPART_MAX_BYTES = 30 * 1024 * 1024;
 // SSE handlers
 // ---------------------------------------------------------------------------
 export interface StreamHandlers {
-  onSources?: (d: { retrieval_contents: RetrievalContent[] }) => void;
+  /** Retrieval milestone. `retrieval_contents` is the reranked top_k (unchanged).
+   *  `retrieved_count` is the total distinct candidate chunks fetched across ALL corpora
+   *  (and sub-queries) BEFORE reranking/truncation — i.e. the recall-net size. */
+  onSources?: (d: { retrieval_contents: RetrievalContent[]; retrieved_count: number }) => void;
   onToken?: (text: string) => void;
   /** A citation, emitted inline as the answer streams (Claude/native path). Also
    *  present aggregated in the `final` event. */