@babav/knowledge-core-client 0.17.0 → 0.20.0

package/README.md

@@ -31,9 +31,11 @@ import { KnowledgeCoreClient } from "npm:@babav/knowledge-core-client";
 ## Usage
 
 ```ts
+// You supply baseUrl + your tenant key at construction (from wherever your app keeps
+// its config/secrets). The SDK never reads the environment or defaults a key itself.
 const kc = new KnowledgeCoreClient({
-  baseUrl: "https://babav-kc-api-gmtvlr3vta-uc.a.run.app",
-  apiKey: Deno.env.get("BABAV_KC_TENANT_KEY")!, // or process.env on Node
+  baseUrl: "https://knowledgecore.babav.ai",
+  apiKey: myTenantKey, // your tenant key, provided by your app
 });
 
 // One-shot grounded query

package/dist/index.d.ts

@@ -12,15 +12,15 @@
  * key for all data ops; use AdminClient with the ADMIN key for tenant / API-key /
  * agent management. The key is server-side only — never ship it to a browser.
  *
- * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
- *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
- *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
- * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
- * (the app is then responsible for supplying it). A missing value (no param AND no
- * env var) throws at construction with a clear message. In Deno, env access needs
- * `--allow-env` (without it, pass the values explicitly).
+ * Configuration — the CALLER supplies credentials at construction; the SDK never reads
+ * the environment or defaults/derives a key itself:
+ *   new KnowledgeCoreClient({ baseUrl, apiKey })   // apiKey = a TENANT key
+ *   new AdminClient({ baseUrl, apiKey })            // apiKey = the ADMIN key
+ * The app decides where its key comes from (its own env/secret store) and passes it in.
+ * 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;
@@ -65,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;
@@ -81,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). */
@@ -183,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;
@@ -251,11 +297,11 @@ export declare class KnowledgeCoreError extends Error {
     get code(): string | undefined;
 }
 export interface ClientOptions {
-    /** API base URL. Defaults to env BABAV_KC_BASE_URL when omitted. */
-    baseUrl?: string;
-    /** Tenant key (KnowledgeCoreClient) or admin key (AdminClient). Defaults to env
-     *  BABAV_KC_TENANT_KEY / BABAV_KC_ADMIN_KEY respectively when omitted. */
-    apiKey?: string;
+    /** API base URL — REQUIRED, supplied by the caller. */
+    baseUrl: string;
+    /** API key — REQUIRED, supplied by the caller (a TENANT key for KnowledgeCoreClient,
+     *  the ADMIN key for AdminClient). The SDK never reads it from the environment. */
+    apiKey: string;
     /** Optional default fetch timeout (ms). Streaming ignores this. */
     timeoutMs?: number;
     fetch?: typeof fetch;
@@ -272,7 +318,7 @@ declare class HttpBase {
     protected readonly apiKey: string;
     protected readonly timeoutMs?: number;
     protected readonly _fetch: typeof fetch;
-    constructor(opts?: ClientOptions, keyEnvVar?: string);
+    constructor(opts: ClientOptions);
     protected url(path: string, query?: RequestOpts["query"]): string;
     protected raw(method: string, path: string, opts?: RequestOpts): Promise<Response>;
     protected request<T>(method: string, path: string, opts?: RequestOpts): Promise<T>;
@@ -291,14 +337,19 @@ 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). */
     onEvent?: (event: string, data: unknown) => void;
 }
 export declare class KnowledgeCoreClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
-    constructor(opts?: ClientOptions);
+    /** @param opts.apiKey a TENANT key, supplied by the caller. */
+    constructor(opts: ClientOptions);
     query(agentId: UUID, body: QueryRequest): Promise<QueryResponse>;
     /** Streaming query (SSE). Resolves when the stream ends. */
     queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
@@ -484,8 +535,8 @@ export declare class KnowledgeCoreClient extends HttpBase {
     };
 }
 export declare class AdminClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
-    constructor(opts?: ClientOptions);
+    /** @param opts.apiKey the ADMIN key, supplied by the caller. */
+    constructor(opts: ClientOptions);
     tenants: {
         create: (b: Partial<Tenant> & {
             name: string;
@@ -529,4 +580,3 @@ export declare class AdminClient extends HttpBase {
         delete: (id: UUID) => Promise<void>;
     };
 }
-export {};

package/dist/index.js

@@ -12,13 +12,12 @@
  * key for all data ops; use AdminClient with the ADMIN key for tenant / API-key /
  * agent management. The key is server-side only — never ship it to a browser.
  *
- * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
- *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
- *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
- * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
- * (the app is then responsible for supplying it). A missing value (no param AND no
- * env var) throws at construction with a clear message. In Deno, env access needs
- * `--allow-env` (without it, pass the values explicitly).
+ * Configuration — the CALLER supplies credentials at construction; the SDK never reads
+ * the environment or defaults/derives a key itself:
+ *   new KnowledgeCoreClient({ baseUrl, apiKey })   // apiKey = a TENANT key
+ *   new AdminClient({ baseUrl, apiKey })            // apiKey = the ADMIN key
+ * The app decides where its key comes from (its own env/secret store) and passes it in.
+ * A missing baseUrl or apiKey throws at construction with a clear message.
  */
 // ---------------------------------------------------------------------------
 // Errors
@@ -43,37 +42,19 @@ export class KnowledgeCoreError extends Error {
         return d?.detail?.error ?? d?.error;
     }
 }
-/** Read an env var under Node (process.env) or Deno (Deno.env); undefined if unset
- *  or inaccessible (e.g. Deno without --allow-env). */
-function readEnv(name) {
-    const g = globalThis;
-    const fromNode = g.process?.env?.[name];
-    if (fromNode)
-        return fromNode;
-    try {
-        const fromDeno = g.Deno?.env?.get?.(name);
-        if (fromDeno)
-            return fromDeno;
-    }
-    catch {
-        /* Deno env access denied (no --allow-env) — treat as unset */
-    }
-    return undefined;
-}
 class HttpBase {
     baseUrl;
     apiKey;
     timeoutMs;
     _fetch;
-    constructor(opts = {}, keyEnvVar = "BABAV_KC_TENANT_KEY") {
-        const baseUrl = opts.baseUrl ?? readEnv("BABAV_KC_BASE_URL");
-        const apiKey = opts.apiKey ?? readEnv(keyEnvVar);
-        if (!baseUrl)
-            throw new Error("KnowledgeCore: no base URL — pass { baseUrl } or set BABAV_KC_BASE_URL");
-        if (!apiKey)
-            throw new Error(`KnowledgeCore: no API key — pass { apiKey } or set ${keyEnvVar}`);
-        this.baseUrl = baseUrl.replace(/\/+$/, "");
-        this.apiKey = apiKey;
+    constructor(opts) {
+        // Credentials come from the CALLER at init — the SDK never sources a key itself.
+        if (!opts?.baseUrl)
+            throw new Error("KnowledgeCore: { baseUrl } is required");
+        if (!opts?.apiKey)
+            throw new Error("KnowledgeCore: { apiKey } is required — the caller must supply the key at init");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
         this.timeoutMs = opts.timeoutMs;
         this._fetch = opts.fetch ?? fetch;
     }
@@ -162,9 +143,9 @@ const MULTIPART_MAX_BYTES = 30 * 1024 * 1024;
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
 export class KnowledgeCoreClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
-    constructor(opts = {}) {
-        super(opts, "BABAV_KC_TENANT_KEY");
+    /** @param opts.apiKey a TENANT key, supplied by the caller. */
+    constructor(opts) {
+        super(opts);
     }
     // --- query (agent-anchored) ---
     query(agentId, body) {
@@ -329,9 +310,9 @@ export class KnowledgeCoreClient extends HttpBase {
 // Admin client (tenant + key + agent management) — use the ADMIN key
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
-    constructor(opts = {}) {
-        super(opts, "BABAV_KC_ADMIN_KEY");
+    /** @param opts.apiKey the ADMIN key, supplied by the caller. */
+    constructor(opts) {
+        super(opts);
     }
     tenants = {
         create: (b) => this.request("POST", "/v1/tenants", { json: b }),
@@ -383,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.17.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,9 +9,16 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./visual": {
+      "types": "./dist/visual/index.d.ts",
+      "import": "./dist/visual/index.js"
     }
   },
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -23,12 +30,15 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/"
   },
   "devDependencies": {
     "typescript": "^5.6.0"
   },
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "sideEffects": false,
   "private": false,
   "license": "UNLICENSED"

package/src/index.ts

@@ -12,13 +12,12 @@
  * key for all data ops; use AdminClient with the ADMIN key for tenant / API-key /
  * agent management. The key is server-side only — never ship it to a browser.
  *
- * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
- *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
- *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
- * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
- * (the app is then responsible for supplying it). A missing value (no param AND no
- * env var) throws at construction with a clear message. In Deno, env access needs
- * `--allow-env` (without it, pass the values explicitly).
+ * Configuration — the CALLER supplies credentials at construction; the SDK never reads
+ * the environment or defaults/derives a key itself:
+ *   new KnowledgeCoreClient({ baseUrl, apiKey })   // apiKey = a TENANT key
+ *   new AdminClient({ baseUrl, apiKey })            // apiKey = the ADMIN key
+ * The app decides where its key comes from (its own env/secret store) and passes it in.
+ * A missing baseUrl or apiKey throws at construction with a clear message.
  */
 
 // ---------------------------------------------------------------------------
@@ -26,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;
@@ -76,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 {
@@ -93,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 {
@@ -196,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;
@@ -279,34 +329,16 @@ export class KnowledgeCoreError extends Error {
 // Base HTTP
 // ---------------------------------------------------------------------------
 export interface ClientOptions {
-  /** API base URL. Defaults to env BABAV_KC_BASE_URL when omitted. */
-  baseUrl?: string;
-  /** Tenant key (KnowledgeCoreClient) or admin key (AdminClient). Defaults to env
-   *  BABAV_KC_TENANT_KEY / BABAV_KC_ADMIN_KEY respectively when omitted. */
-  apiKey?: string;
+  /** API base URL — REQUIRED, supplied by the caller. */
+  baseUrl: string;
+  /** API key — REQUIRED, supplied by the caller (a TENANT key for KnowledgeCoreClient,
+   *  the ADMIN key for AdminClient). The SDK never reads it from the environment. */
+  apiKey: string;
   /** Optional default fetch timeout (ms). Streaming ignores this. */
   timeoutMs?: number;
   fetch?: typeof fetch; // override for tests
 }
 
-/** Read an env var under Node (process.env) or Deno (Deno.env); undefined if unset
- *  or inaccessible (e.g. Deno without --allow-env). */
-function readEnv(name: string): string | undefined {
-  const g = globalThis as {
-    process?: { env?: Record<string, string | undefined> };
-    Deno?: { env?: { get?: (n: string) => string | undefined } };
-  };
-  const fromNode = g.process?.env?.[name];
-  if (fromNode) return fromNode;
-  try {
-    const fromDeno = g.Deno?.env?.get?.(name);
-    if (fromDeno) return fromDeno;
-  } catch {
-    /* Deno env access denied (no --allow-env) — treat as unset */
-  }
-  return undefined;
-}
-
 interface RequestOpts {
   query?: Record<string, string | number | boolean | undefined>;
   json?: unknown;
@@ -321,13 +353,12 @@ class HttpBase {
   protected readonly timeoutMs?: number;
   protected readonly _fetch: typeof fetch;
 
-  constructor(opts: ClientOptions = {}, keyEnvVar = "BABAV_KC_TENANT_KEY") {
-    const baseUrl = opts.baseUrl ?? readEnv("BABAV_KC_BASE_URL");
-    const apiKey = opts.apiKey ?? readEnv(keyEnvVar);
-    if (!baseUrl) throw new Error("KnowledgeCore: no base URL — pass { baseUrl } or set BABAV_KC_BASE_URL");
-    if (!apiKey) throw new Error(`KnowledgeCore: no API key — pass { apiKey } or set ${keyEnvVar}`);
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
-    this.apiKey = apiKey;
+  constructor(opts: ClientOptions) {
+    // Credentials come from the CALLER at init — the SDK never sources a key itself.
+    if (!opts?.baseUrl) throw new Error("KnowledgeCore: { baseUrl } is required");
+    if (!opts?.apiKey) throw new Error("KnowledgeCore: { apiKey } is required — the caller must supply the key at init");
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
     this.timeoutMs = opts.timeoutMs;
     this._fetch = opts.fetch ?? fetch;
   }
@@ -425,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). */
@@ -435,9 +471,9 @@ export interface StreamHandlers {
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
 export class KnowledgeCoreClient extends HttpBase {
-  /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
-  constructor(opts: ClientOptions = {}) {
-    super(opts, "BABAV_KC_TENANT_KEY");
+  /** @param opts.apiKey a TENANT key, supplied by the caller. */
+  constructor(opts: ClientOptions) {
+    super(opts);
   }
 
   // --- query (agent-anchored) ---
@@ -627,9 +663,9 @@ export class KnowledgeCoreClient extends HttpBase {
 // Admin client (tenant + key + agent management) — use the ADMIN key
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
-  /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
-  constructor(opts: ClientOptions = {}) {
-    super(opts, "BABAV_KC_ADMIN_KEY");
+  /** @param opts.apiKey the ADMIN key, supplied by the caller. */
+  constructor(opts: ClientOptions) {
+    super(opts);
   }
 
   tenants = {
@@ -673,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;
+}