@babav/knowledge-core-client 0.35.0 → 0.37.0

package/dist/index.d.ts

@@ -61,6 +61,8 @@ export interface QueryOverrides {
     max_reasoning_rounds?: number;
     decomposition_model?: string;
     reasoning_inspect_model?: string;
+    multi_query_model?: string;
+    citation_model?: string;
     groundedness_verifier_model?: string;
     groundedness_threshold?: number;
     grounding_enabled?: boolean;
@@ -417,7 +419,7 @@ export interface Feedback {
 }
 export interface Agent {
     id: UUID;
-    tenant_id: UUID | null;
+    tenant_id: UUID;
     name: string;
     identity_prompt: string | null;
     response_prompt: string | null;
@@ -432,6 +434,8 @@ export interface Agent {
     max_reasoning_rounds: number | null;
     decomposition_model: string | null;
     reasoning_inspect_model: string | null;
+    multi_query_model: string | null;
+    citation_model: string | null;
     groundedness_verifier_model: string | null;
     groundedness_threshold: number | null;
     grounding_enabled: boolean | null;
@@ -446,8 +450,10 @@ export interface Agent {
     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. */
+/** Fields settable when creating/updating an agent. All optional except `name` on create
+ *  (null/omit => server default); model fields must be one of
+ *  `agents.modelOptions().fields[field].supported`. The owning tenant is the caller's key —
+ *  it is never part of the body. */
 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);
@@ -888,12 +894,22 @@ export declare class KnowledgeCoreClient extends HttpBase {
         delete: (id: UUID) => Promise<void>;
     };
     agents: {
+        /** List this tenant's agents. */
         list: (q?: {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Agent>>;
         listAll: () => Promise<Agent[]>;
         get: (id: UUID) => Promise<Agent>;
+        /** Create an agent owned by this tenant (the owning tenant is the key's — no tenant_id in the body). */
+        create: (b: AgentWrite & {
+            name: string;
+        }) => 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>;
     };
     analytics: {
         /** Query-volume time series for a corpus (the denominator for everything). */
@@ -958,26 +974,6 @@ export declare class AdminClient extends HttpBase {
         }) => Promise<Page<ApiKey>>;
         revokeApiKey: (tenantId: UUID, keyId: UUID) => Promise<void>;
     };
-    agents: {
-        /** List agents (admin). Pass `tenant_id` for one tenant's agents (+ global); omit for all agents
-         *  across every tenant. (A tenant lists its own via KnowledgeCoreClient.agents.list.) */
-        list: (q?: {
-            tenant_id?: UUID;
-            limit?: number;
-            cursor?: string;
-        }) => Promise<Page<Agent>>;
-        listAll: (tenantId?: UUID) => Promise<Agent[]>;
-        get: (id: UUID) => Promise<Agent>;
-        create: (b: AgentWrite & {
-            name: string;
-            tenant_id?: UUID | null;
-        }) => 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 {
     overrides?: QueryRequest["overrides"];

package/dist/index.js

@@ -444,11 +444,19 @@ export class KnowledgeCoreClient extends HttpBase {
         get: (id) => this.request("GET", `/v1/feedback/${id}`),
         delete: (id) => this.request("DELETE", `/v1/feedback/${id}`),
     };
-    // --- agents (tenant read-only: choose an agent to query) ---
+    // --- agents (tenant-owned config the chat queries; full CRUD with the tenant key) ---
     agents = {
+        /** List this tenant's agents. */
         list: (q) => this.request("GET", "/v1/agents", { query: q }),
         listAll: () => this.pageAll("/v1/agents"),
         get: (id) => this.request("GET", `/v1/agents/${id}`),
+        /** Create an agent owned by this tenant (the owning tenant is the key's — no tenant_id in the body). */
+        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"),
     };
     // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
     analytics = {
@@ -472,7 +480,8 @@ export class KnowledgeCoreClient extends HttpBase {
     };
 }
 // ---------------------------------------------------------------------------
-// Admin client (tenant + key + agent management) — use the ADMIN key
+// Admin client (tenant + API-key provisioning) — use the ADMIN key.
+// Agents are tenant data; manage them with the tenant client (KnowledgeCoreClient.agents).
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
     /** @param opts.apiKey the ADMIN key, supplied by the caller. */
@@ -490,21 +499,6 @@ 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}`),
     };
-    // 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 = {
-        /** List agents (admin). Pass `tenant_id` for one tenant's agents (+ global); omit for all agents
-         *  across every tenant. (A tenant lists its own via KnowledgeCoreClient.agents.list.) */
-        list: (q) => this.request("GET", "/v1/agents", { query: q }),
-        listAll: (tenantId) => this.pageAll("/v1/agents", tenantId ? { tenant_id: tenantId } : {}),
-        get: (id) => this.request("GET", `/v1/agents/${id}`),
-        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
  *  conversational: the conversation_id is attached for you, so a chat turn can never be a

package/package.json

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

@@ -82,6 +82,8 @@ export interface QueryOverrides {
   max_reasoning_rounds?: number;    // iterative agentic-loop ceiling (1 = single pass; early-stops)
   decomposition_model?: string;     // model for query decomposition
   reasoning_inspect_model?: string; // model for the per-round sufficiency / next-query decision
+  multi_query_model?: string;       // model for multi-query expansion
+  citation_model?: string;          // model for the citation pass (non-native-citation providers)
   groundedness_verifier_model?: string;  // model for the groundedness LLM judge
   groundedness_threshold?: number;
   grounding_enabled?: boolean;   // groundedness score (default off)
@@ -399,7 +401,7 @@ export interface Feedback {
 }
 export interface Agent {
   id: UUID;
-  tenant_id: UUID | null;            // null => Babav-global agent; a tenant id => per-tenant
+  tenant_id: UUID;                   // the owning tenant (every agent belongs to exactly one; no globals)
   name: string;
   identity_prompt: string | null;   // answer-system: who/purpose (null => server default)
   response_prompt: string | null;   // answer-system: output guidelines (null => server default)
@@ -414,6 +416,8 @@ export interface Agent {
   max_reasoning_rounds: number | null;
   decomposition_model: string | null;
   reasoning_inspect_model: string | null;
+  multi_query_model: string | null;
+  citation_model: string | null;
   groundedness_verifier_model: string | null;
   groundedness_threshold: number | null;
   grounding_enabled: boolean | null;
@@ -430,8 +434,10 @@ export interface Agent {
   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. */
+/** Fields settable when creating/updating an agent. All optional except `name` on create
+ *  (null/omit => server default); model fields must be one of
+ *  `agents.modelOptions().fields[field].supported`. The owning tenant is the caller's key —
+ *  it is never part of the body. */
 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
@@ -1037,11 +1043,19 @@ export class KnowledgeCoreClient extends HttpBase {
     delete: (id: UUID) => this.request<void>("DELETE", `/v1/feedback/${id}`),
   };
 
-  // --- agents (tenant read-only: choose an agent to query) ---
+  // --- agents (tenant-owned config the chat queries; full CRUD with the tenant key) ---
   agents = {
+    /** List this tenant's agents. */
     list: (q?: { limit?: number; cursor?: string }) => this.request<Page<Agent>>("GET", "/v1/agents", { query: q }),
     listAll: () => this.pageAll<Agent>("/v1/agents"),
     get: (id: UUID) => this.request<Agent>("GET", `/v1/agents/${id}`),
+    /** Create an agent owned by this tenant (the owning tenant is the key's — no tenant_id in the body). */
+    create: (b: AgentWrite & { name: string }) => this.request<Agent>("POST", "/v1/agents", { json: b }),
+    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"),
   };
 
   // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
@@ -1070,7 +1084,8 @@ export class KnowledgeCoreClient extends HttpBase {
 }
 
 // ---------------------------------------------------------------------------
-// Admin client (tenant + key + agent management) — use the ADMIN key
+// Admin client (tenant + API-key provisioning) — use the ADMIN key.
+// Agents are tenant data; manage them with the tenant client (KnowledgeCoreClient.agents).
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
   /** @param opts.apiKey the ADMIN key, supplied by the caller. */
@@ -1089,25 +1104,8 @@ export class AdminClient extends HttpBase {
     listApiKeys: (tenantId: UUID, q?: { limit?: number; cursor?: string }) => this.request<Page<ApiKey>>("GET", `/v1/tenants/${tenantId}/api-keys`, { query: q }),
     revokeApiKey: (tenantId: UUID, keyId: UUID) => this.request<void>("DELETE", `/v1/tenants/${tenantId}/api-keys/${keyId}`),
   };
-
-  // 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 = {
-    /** List agents (admin). Pass `tenant_id` for one tenant's agents (+ global); omit for all agents
-     *  across every tenant. (A tenant lists its own via KnowledgeCoreClient.agents.list.) */
-    list: (q?: { tenant_id?: UUID; limit?: number; cursor?: string }) =>
-      this.request<Page<Agent>>("GET", "/v1/agents", { query: q }),
-    listAll: (tenantId?: UUID) => this.pageAll<Agent>("/v1/agents", tenantId ? { tenant_id: tenantId } : {}),
-    get: (id: UUID) => this.request<Agent>("GET", `/v1/agents/${id}`),
-    create: (b: AgentWrite & { name: string; tenant_id?: UUID | null }) =>
-      this.request<Agent>("POST", "/v1/agents", { json: b }),
-    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"),
-  };
+  // Agents are TENANT data, not an admin surface — manage them with the tenant key via
+  // KnowledgeCoreClient.agents (create/update/delete/list/get/modelOptions).
 }
 
 export interface ChatSendOptions extends StreamHandlers {