@babav/knowledge-core-client 0.43.0 → 0.45.0

package/README.md

@@ -39,15 +39,15 @@ const kc = new KnowledgeCoreClient({
 });
 
 // One-shot grounded query
-const r = await kc.query(agentId, { corpus_ids: [corpusId], query: "..." });
+const r = await kc.query(profileId, { corpus_ids: [corpusId], query: "..." });
 console.log(r.answer, r.retrieval_contents, r.citations, r.groundedness);
 
 // Conversational (persisted, history-aware)
 const convo = await kc.conversations.create({ title: "Contract review", custom_metadata: { account_id } });
-const turn = await kc.query(agentId, { corpus_ids: [corpusId], query: "...", conversation_id: convo.id });
+const turn = await kc.query(profileId, { corpus_ids: [corpusId], query: "...", conversation_id: convo.id });
 
 // Streaming (SSE)
-await kc.queryStream(agentId, { corpus_ids: [corpusId], query: "..." }, {
+await kc.queryStream(profileId, { corpus_ids: [corpusId], query: "..." }, {
   onSources: (s) => render(s.retrieval_contents),
   onToken: (t) => append(t),
   onFinal: (f) => done(f),
@@ -57,7 +57,7 @@ await kc.queryStream(agentId, { corpus_ids: [corpusId], query: "..." }, {
 // Attachment-backed review
 const att = await kc.attachments.upload(convo.id, { filename: "c.pdf", content_type: "application/pdf", data: bytes });
 await kc.attachments.waitReady(convo.id, att.id);
-const review = await kc.query(agentId, { corpus_ids: [corpusId], conversation_id: convo.id, query: "Review the attached contract." });
+const review = await kc.query(profileId, { corpus_ids: [corpusId], conversation_id: convo.id, query: "Review the attached contract." });
 
 // View/download a stored doc (signed URL)
 const { content_url, content_type } = await kc.documents.contentUrl(documentId, "inline");
@@ -65,7 +65,7 @@ const { content_url, content_type } = await kc.documents.contentUrl(documentId,
 
 ### Error handling (structured guards)
 ```ts
-try { await kc.query(agentId, body); }
+try { await kc.query(profileId, body); }
 catch (e) {
   if (e instanceof KnowledgeCoreError) {
     if (e.code === "attachments_pending") { /* a document is still parsing */ }
@@ -75,7 +75,7 @@ catch (e) {
 }
 ```
 
-## Admin client (tenant + key + agent management — ADMIN key)
+## Admin client (tenant + key + profile management — ADMIN key)
 ```ts
 import { AdminClient } from "@babav/knowledge-core-client";
 const admin = new AdminClient({ baseUrl, apiKey: ADMIN_KEY });
@@ -90,5 +90,5 @@ const created = await admin.tenants.createApiKey(tenantId, "label"); // created.
 - `conversations` (CRUD, search, listMessages)
 - `attachments` (upload, list, get, contentUrl, delete, waitReady)
 - `messages` (get, createFeedback, listFeedback), `feedback` (get, delete)
-- `parseJobs` (list, get), `agents` (list, get)
-- `AdminClient`: `tenants` (CRUD + api-keys), `agents` (create/update/delete)
+- `parseJobs` (list, get), `profiles` (list, get)
+- `AdminClient`: `tenants` (CRUD + api-keys), `profiles` (create/update/delete)

package/dist/index.d.ts

@@ -10,7 +10,7 @@
  *
  * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient with a TENANT
  * 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.
+ * profile management. The key is server-side only — never ship it to a browser.
  *
  * Configuration — the CALLER supplies credentials at construction; the SDK never reads
  * the environment or defaults/derives a key itself:
@@ -44,6 +44,7 @@ export interface RetrievalContent {
     parent_id: string;
     document_id: string;
     corpus_id: string;
+    chunk_id?: string | null;
     source_type: "corpus" | "conversation_attachment";
     visibility: Visibility | string;
     metadata: Record<string, unknown>;
@@ -77,7 +78,7 @@ export interface VisualOverrides {
     claims_check_model?: string;
     vision_judge_model?: string;
 }
-/** Per-request visual control. Absent => mode resolves from the agent default. All visual
+/** Per-request visual control. Absent => mode resolves from the profile default. All visual
  * PROCESSING is server-side; the client only displays the result. */
 export interface VisualRequest {
     mode?: "off" | "on";
@@ -539,13 +540,13 @@ export interface QueryProfile {
     visual_combine_generation_and_concept: boolean | null;
     concept_model_mode: string | null;
 }
-/** Fields settable when creating/updating an agent. All optional except `name` on create
+/** Fields settable when creating/updating a query profile. 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 —
+ *  `profiles.modelOptions().fields[field].supported`. The owning tenant is the caller's key —
  *  it is never part of the body. */
 export type QueryProfileWrite = Partial<Omit<QueryProfile, "id" | "tenant_id">>;
 /** Model catalog for the query-profile-config UI (GET /v1/query-profiles/model-options). `models` maps id → its
- *  capabilities; `fields` gives each agent model-field its supported ids + default (+ usage metadata);
+ *  capabilities; `fields` gives each profile model-field its supported ids + default (+ usage metadata);
  *  `modes` says which model field governs each mode (reasoning is valid only if that model's
  *  supports_reasoning is true). KC provides the data; the UI decides presentation. */
 export interface ModelOptions {
@@ -778,6 +779,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
             visibility?: Visibility;
             folder_id?: UUID;
             custom_metadata?: Record<string, unknown>;
+            profile_id?: UUID;
         }) => Promise<Document>;
         /** Mint a signed PUT URL to upload a large file straight to GCS (bypasses the
          *  ~32 MB request limit). PUT the bytes to upload_url, then ingestFromUpload. */
@@ -794,6 +796,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
             visibility?: Visibility;
             folder_id?: UUID;
             custom_metadata?: Record<string, unknown>;
+            profile_id?: UUID;
         }) => Promise<Document>;
         /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
          *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
@@ -804,6 +807,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
             visibility?: Visibility;
             folder_id?: UUID;
             custom_metadata?: Record<string, unknown>;
+            profile_id?: UUID;
         }) => Promise<Document>;
         /** Ingest MANY files in ONE go — any size, no 429, no client backoff. Mints all signed URLs in
          *  one request, PUTs the bytes straight to GCS (bounded concurrency; never touches the KC), then
@@ -819,6 +823,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
             visibility?: Visibility;
             custom_metadata?: Record<string, unknown>;
             concurrency?: number;
+            profile_id?: UUID;
         }) => Promise<Document[]>;
         /** (server-side) Mint one RESUMABLE GCS upload session per file. Return only the sessions to the
          *  browser; the browser PUTs bytes to each `upload_url` and needs NO KC/tenant credential (the
@@ -845,6 +850,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
             folder_id?: UUID;
             visibility?: Visibility;
             custom_metadata?: Record<string, unknown>;
+            profile_id?: UUID;
         }) => Promise<{
             results: FinalizeResult[];
         }>;
@@ -1003,7 +1009,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
         modelOptions: () => Promise<ModelOptions>;
     };
     /** Ingestion profiles — the build-side config object (counterpart to query profiles): a tenant-owned,
-     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike a query profile
      *  (chosen per query), a profile binds at the TENANT/COLLECTION level — the tenant's one
      *  `is_default` profile governs how ALL its documents are ingested; swapping it re-indexes.
      *  A corpus's content is a RESULT of ingestion, so a corpus never selects a profile. */

package/dist/index.js

@@ -10,7 +10,7 @@
  *
  * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient with a TENANT
  * 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.
+ * profile management. The key is server-side only — never ship it to a browser.
  *
  * Configuration — the CALLER supplies credentials at construction; the SDK never reads
  * the environment or defaults/derives a key itself:
@@ -303,6 +303,7 @@ export class KnowledgeCoreClient extends HttpBase {
             return this.corpora.ingestFromUpload(id, {
                 document_id: u.document_id, filename: a.filename, content_type: a.content_type,
                 visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
+                profile_id: a.profile_id,
             });
         },
         /** Ingest MANY files in ONE go — any size, no 429, no client backoff. Mints all signed URLs in
@@ -328,6 +329,7 @@ export class KnowledgeCoreClient extends HttpBase {
             });
             const res = await this.request("POST", `/v1/corpora/${id}/documents/batch`, { json: {
                     folder_id: opts?.folder_id, visibility: opts?.visibility, custom_metadata: opts?.custom_metadata,
+                    profile_id: opts?.profile_id,
                     items: items.map((it) => ({ document_id: it.document_id, filename: it.filename })),
                 } });
             return res.documents;
@@ -353,7 +355,7 @@ export class KnowledgeCoreClient extends HttpBase {
          *  items. `document_id` is stable from createUploadSessions, so documents.events (SSE) tracks it. */
         finalizeUploads: (id, items, opts) => this.request("POST", `/v1/corpora/${id}/documents/finalize`, { json: {
                 items, folder_id: opts?.folder_id, visibility: opts?.visibility,
-                custom_metadata: opts?.custom_metadata,
+                custom_metadata: opts?.custom_metadata, profile_id: opts?.profile_id,
             } }),
         /** (server-side) Cancel upload sessions the browser gave up on (idempotent cleanup). Pass the
          *  `upload_url` from createUploadSessions so the resumable session is dropped; any pending row is
@@ -468,7 +470,7 @@ export class KnowledgeCoreClient extends HttpBase {
         modelOptions: () => this.request("GET", "/v1/query-profiles/model-options"),
     };
     /** Ingestion profiles — the build-side config object (counterpart to query profiles): a tenant-owned,
-     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike a query profile
      *  (chosen per query), a profile binds at the TENANT/COLLECTION level — the tenant's one
      *  `is_default` profile governs how ALL its documents are ingested; swapping it re-indexes.
      *  A corpus's content is a RESULT of ingestion, so a corpus never selects a profile. */

package/package.json

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

@@ -10,7 +10,7 @@
  *
  * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient with a TENANT
  * 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.
+ * profile management. The key is server-side only — never ship it to a browser.
  *
  * Configuration — the CALLER supplies credentials at construction; the SDK never reads
  * the environment or defaults/derives a key itself:
@@ -64,6 +64,7 @@ export interface RetrievalContent {
   parent_id: string;
   document_id: string;
   corpus_id: string;
+  chunk_id?: string | null;  // Qdrant point id of the best-matching child chunk ("{document_id}::{seq}")
   source_type: "corpus" | "conversation_attachment";
   visibility: Visibility | string;
   metadata: Record<string, unknown>;
@@ -100,7 +101,7 @@ export interface VisualOverrides {
   vision_judge_model?: string;
 }
 
-/** Per-request visual control. Absent => mode resolves from the agent default. All visual
+/** Per-request visual control. Absent => mode resolves from the profile default. All visual
  * PROCESSING is server-side; the client only displays the result. */
 export interface VisualRequest {
   mode?: "off" | "on";
@@ -474,12 +475,12 @@ export interface Feedback {
 }
 export interface QueryProfile {
   id: UUID;
-  tenant_id: UUID;                   // the owning tenant (every agent belongs to exactly one; no globals)
+  tenant_id: UUID;                   // the owning tenant (every profile 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)
   generation_model: string | null;
-  generation_model_mode: string | null;  // "reasoning" (adaptive thinking) | "standard"; per-agent
+  generation_model_mode: string | null;  // "reasoning" (adaptive thinking) | "standard"; per-profile
   max_response_tokens: number | null;
   top_k_retrieved_chunks: number | null;
   top_k_reranked_chunks: number | null;
@@ -507,14 +508,14 @@ export interface QueryProfile {
   concept_model_mode: string | null;         // "reasoning" | "standard"; overrules gen mode when combining
 }
 
-/** Fields settable when creating/updating an agent. All optional except `name` on create
+/** Fields settable when creating/updating a query profile. 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 —
+ *  `profiles.modelOptions().fields[field].supported`. The owning tenant is the caller's key —
  *  it is never part of the body. */
 export type QueryProfileWrite = Partial<Omit<QueryProfile, "id" | "tenant_id">>;
 
 /** Model catalog for the query-profile-config UI (GET /v1/query-profiles/model-options). `models` maps id → its
- *  capabilities; `fields` gives each agent model-field its supported ids + default (+ usage metadata);
+ *  capabilities; `fields` gives each profile model-field its supported ids + default (+ usage metadata);
  *  `modes` says which model field governs each mode (reasoning is valid only if that model's
  *  supports_reasoning is true). KC provides the data; the UI decides presentation. */
 export interface ModelOptions {
@@ -893,7 +894,7 @@ export class KnowledgeCoreClient extends HttpBase {
      *  `pending` (HTTP 202); track via documents.events()/get() or the tenant webhook.
      *  ALWAYS uploads the bytes straight to GCS via a signed URL (uploadUrl → PUT → ingestFromUpload),
      *  regardless of size — so there is NO request-size cap, ever. One method, any size. */
-    ingestDocument: (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }) =>
+    ingestDocument: (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown>; profile_id?: UUID }) =>
       this.corpora.uploadDocument(id, a),
     /** Mint a signed PUT URL to upload a large file straight to GCS (bypasses the
      *  ~32 MB request limit). PUT the bytes to upload_url, then ingestFromUpload. */
@@ -901,11 +902,11 @@ export class KnowledgeCoreClient extends HttpBase {
       this.request<UploadUrl>("POST", `/v1/corpora/${id}/documents/upload-url`, { json: a }),
     /** Ingest a file already PUT to GCS via uploadUrl. Resolves with the `pending`
      *  document (202); track via documents.get() / webhook. */
-    ingestFromUpload: (id: UUID, a: { document_id: UUID; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }) =>
+    ingestFromUpload: (id: UUID, a: { document_id: UUID; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown>; profile_id?: UUID }) =>
       this.request<Document>("POST", `/v1/corpora/${id}/documents/from-upload`, { json: a }),
     /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
      *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
-    uploadDocument: async (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }): Promise<Document> => {
+    uploadDocument: async (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown>; profile_id?: UUID }): Promise<Document> => {
       const u = await this.corpora.uploadUrl(id, { filename: a.filename, content_type: a.content_type });
       const put = await this._fetch(u.upload_url, {
         method: "PUT",
@@ -918,6 +919,7 @@ export class KnowledgeCoreClient extends HttpBase {
       return this.corpora.ingestFromUpload(id, {
         document_id: u.document_id, filename: a.filename, content_type: a.content_type,
         visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
+        profile_id: a.profile_id,
       });
     },
     /** Ingest MANY files in ONE go — any size, no 429, no client backoff. Mints all signed URLs in
@@ -928,7 +930,7 @@ export class KnowledgeCoreClient extends HttpBase {
     uploadMany: async (
       id: UUID,
       files: Array<{ file: FileData; filename: string; content_type?: string }>,
-      opts?: { folder_id?: UUID; visibility?: Visibility; custom_metadata?: Record<string, unknown>; concurrency?: number },
+      opts?: { folder_id?: UUID; visibility?: Visibility; custom_metadata?: Record<string, unknown>; concurrency?: number; profile_id?: UUID },
     ): Promise<Document[]> => {
       if (files.length === 0) return [];
       const urls = await this.request<BatchUploadUrls>(
@@ -950,6 +952,7 @@ export class KnowledgeCoreClient extends HttpBase {
         "POST", `/v1/corpora/${id}/documents/batch`,
         { json: {
             folder_id: opts?.folder_id, visibility: opts?.visibility, custom_metadata: opts?.custom_metadata,
+            profile_id: opts?.profile_id,
             items: items.map((it) => ({ document_id: it.document_id, filename: it.filename })),
         } },
       );
@@ -988,13 +991,13 @@ export class KnowledgeCoreClient extends HttpBase {
     finalizeUploads: (
       id: UUID,
       items: Array<{ document_id: UUID; filename: string; content_type?: string }>,
-      opts?: { folder_id?: UUID; visibility?: Visibility; custom_metadata?: Record<string, unknown> },
+      opts?: { folder_id?: UUID; visibility?: Visibility; custom_metadata?: Record<string, unknown>; profile_id?: UUID },
     ): Promise<{ results: FinalizeResult[] }> =>
       this.request<{ results: FinalizeResult[] }>(
         "POST", `/v1/corpora/${id}/documents/finalize`,
         { json: {
             items, folder_id: opts?.folder_id, visibility: opts?.visibility,
-            custom_metadata: opts?.custom_metadata,
+            custom_metadata: opts?.custom_metadata, profile_id: opts?.profile_id,
         } },
       ),
 
@@ -1142,7 +1145,7 @@ export class KnowledgeCoreClient extends HttpBase {
   };
 
   /** Ingestion profiles — the build-side config object (counterpart to query profiles): a tenant-owned,
-   *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+   *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike a query profile
    *  (chosen per query), a profile binds at the TENANT/COLLECTION level — the tenant's one
    *  `is_default` profile governs how ALL its documents are ingested; swapping it re-indexes.
    *  A corpus's content is a RESULT of ingestion, so a corpus never selects a profile. */