@babav/knowledge-core-client 0.42.0 → 0.44.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:
@@ -77,7 +77,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";
@@ -215,7 +215,7 @@ export interface Corpus {
 /** Build-time knob bundle that DEFINES an index. Defaults are today's blessed config, so a
  *  profile created with no params is the blessed profile. Change any knob => different vectors
  *  => a different physical collection. Embedding/indexing/chunking is SYSTEM-level, never a
- *  query knob — this is the build-side counterpart to an Agent, not an agent. */
+ *  query knob — this is the build-side counterpart to a query profile. */
 export interface IngestionProfileParams {
     chunker: string;
     chunk_child_max_tokens: number;
@@ -477,7 +477,7 @@ export interface Conversation {
 export interface Message {
     id: UUID;
     conversation_id: UUID;
-    agent_id: UUID | null;
+    query_profile_id: UUID | null;
     corpus_ids: UUID[] | null;
     query: string;
     answer: string | null;
@@ -506,7 +506,7 @@ export interface Feedback {
     rating: number | null;
     comment: string | null;
 }
-export interface Agent {
+export interface QueryProfile {
     id: UUID;
     tenant_id: UUID;
     name: string;
@@ -539,13 +539,13 @@ export interface Agent {
     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 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);
+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 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 {
@@ -686,11 +686,11 @@ export interface DocumentEventHandlers {
 export declare class KnowledgeCoreClient extends HttpBase {
     /** @param opts.apiKey a TENANT key, supplied by the caller. */
     constructor(opts: ClientOptions);
-    query(agentId: UUID, body: QueryRequest): Promise<QueryResponse>;
+    query(profileId: UUID, body: QueryRequest): Promise<QueryResponse>;
     /** Streaming query (SSE). Resolves when the stream ends (the Promise resolving is normal, not an
      *  error). Pass `signal` and abort() on unmount / when the user cancels or navigates away so the
      *  connection doesn't linger. Transient (ends on `done`) — no reopen logic needed. */
-    queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
+    queryStream(profileId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
     /** Fetch a visual's PNG bytes BY ID. This is the ONLY way to get a visual image — the API never
      *  returns a URL. Authenticated + tenant-scoped like every call. Use `visual.id` from a query
      *  response / streamed `visual` event / persisted message. Returns a Blob (browser: `URL.
@@ -708,11 +708,11 @@ export declare class KnowledgeCoreClient extends HttpBase {
     /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
      *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
      *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
-     *    New chat:  const chat = kc.chat(agentId, corpusIds);
-     *    Resume:    const chat = kc.chat(agentId, corpusIds, { conversationId });
+     *    New chat:  const chat = kc.chat(profileId, corpusIds);
+     *    Resume:    const chat = kc.chat(profileId, corpusIds, { conversationId });
      *  The conversation is created LAZILY on the first `send()` (opening a "new chat" and never
      *  sending leaves nothing behind). See ChatSession.send. */
-    chat(agentId: UUID, corpusIds: UUID[], opts?: {
+    chat(profileId: UUID, corpusIds: UUID[], opts?: {
         conversationId?: UUID;
     }): ChatSession;
     /** Shared SSE reader for the document-status streams (documents.events / folders.events).
@@ -778,6 +778,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 +795,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 +806,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 +822,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 +849,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
             folder_id?: UUID;
             visibility?: Visibility;
             custom_metadata?: Record<string, unknown>;
+            profile_id?: UUID;
         }) => Promise<{
             results: FinalizeResult[];
         }>;
@@ -984,26 +989,26 @@ export declare class KnowledgeCoreClient extends HttpBase {
         get: (id: UUID) => Promise<Feedback>;
         delete: (id: UUID) => Promise<void>;
     };
-    agents: {
-        /** List this tenant's agents. */
+    queryProfiles: {
+        /** List this tenant's query profiles. */
         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 & {
+        }) => Promise<Page<QueryProfile>>;
+        listAll: () => Promise<QueryProfile[]>;
+        get: (id: UUID) => Promise<QueryProfile>;
+        /** Create a query profile owned by this tenant (the owning tenant is the key's — no tenant_id in the body). */
+        create: (b: QueryProfileWrite & {
             name: string;
-        }) => Promise<Agent>;
-        update: (id: UUID, b: AgentWrite) => Promise<Agent>;
+        }) => Promise<QueryProfile>;
+        update: (id: UUID, b: QueryProfileWrite) => Promise<QueryProfile>;
         delete: (id: UUID) => Promise<void>;
-        /** The model catalog for an agent-config UI: supported models + default per field, per-model
+        /** The model catalog for an query-profile-config UI: supported models + default per field, per-model
          *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
         modelOptions: () => Promise<ModelOptions>;
     };
-    /** Ingestion profiles — the build-side config object (counterpart to `agents`): a tenant-owned,
-     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+    /** Ingestion profiles — the build-side config object (counterpart to query profiles): a tenant-owned,
+     *  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. */
@@ -1024,7 +1029,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
         delete: (id: UUID) => Promise<void>;
         /** The config catalog for a profile UI: supported embedding models (+ provider/dims),
          *  chunkers, distances, quantizations, per-field defaults/bounds, and the standard params.
-         *  Build-side mirror of `agents.modelOptions()`. */
+         *  Build-side mirror of `queryProfiles.modelOptions()`. */
         modelOptions: () => Promise<IngestionProfileOptions>;
     };
     analytics: {
@@ -1123,7 +1128,7 @@ export declare class ChatSession {
     #private;
     /** The conversation id — null until the first `send()` (unless resumed). */
     conversationId: UUID | null;
-    constructor(kc: KnowledgeCoreClient, agentId: UUID, corpusIds: UUID[], conversationId: UUID | null);
+    constructor(kc: KnowledgeCoreClient, profileId: UUID, corpusIds: UUID[], conversationId: UUID | null);
     /** Send a chat message (streaming). Lazily creates the conversation on the first message and
      *  ALWAYS passes conversation_id, so the turn is persisted. `onConversationId` fires before the
      *  stream so you can show the conversation immediately. Pass `signal` to cancel on unmount. */

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:
@@ -156,18 +156,18 @@ export class KnowledgeCoreClient extends HttpBase {
     constructor(opts) {
         super(opts);
     }
-    // --- query (agent-anchored) ---
-    query(agentId, body) {
-        return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
+    // --- query (query-profile-anchored) ---
+    query(profileId, body) {
+        return this.request("POST", `/v1/query-profiles/${profileId}/query`, { json: body });
     }
     /** Streaming query (SSE). Resolves when the stream ends (the Promise resolving is normal, not an
      *  error). Pass `signal` and abort() on unmount / when the user cancels or navigates away so the
      *  connection doesn't linger. Transient (ends on `done`) — no reopen logic needed. */
-    async queryStream(agentId, body, handlers, signal) {
-        const res = await this.raw("POST", `/v1/agents/${agentId}/query/stream`, { json: body, signal });
+    async queryStream(profileId, body, handlers, signal) {
+        const res = await this.raw("POST", `/v1/query-profiles/${profileId}/query/stream`, { json: body, signal });
         if (!res.ok || !res.body) {
             const t = await res.text();
-            throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/agents/${agentId}/query/stream`);
+            throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/query-profiles/${profileId}/query/stream`);
         }
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
@@ -217,12 +217,12 @@ export class KnowledgeCoreClient extends HttpBase {
     /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
      *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
      *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
-     *    New chat:  const chat = kc.chat(agentId, corpusIds);
-     *    Resume:    const chat = kc.chat(agentId, corpusIds, { conversationId });
+     *    New chat:  const chat = kc.chat(profileId, corpusIds);
+     *    Resume:    const chat = kc.chat(profileId, corpusIds, { conversationId });
      *  The conversation is created LAZILY on the first `send()` (opening a "new chat" and never
      *  sending leaves nothing behind). See ChatSession.send. */
-    chat(agentId, corpusIds, opts) {
-        return new ChatSession(this, agentId, corpusIds, opts?.conversationId ?? null);
+    chat(profileId, corpusIds, opts) {
+        return new ChatSession(this, profileId, corpusIds, opts?.conversationId ?? null);
     }
     /** Shared SSE reader for the document-status streams (documents.events / folders.events).
      *  Resolves when the stream ends (server sends `complete` once nothing is in-flight, or the
@@ -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
@@ -453,22 +455,22 @@ export class KnowledgeCoreClient extends HttpBase {
         get: (id) => this.request("GET", `/v1/feedback/${id}`),
         delete: (id) => this.request("DELETE", `/v1/feedback/${id}`),
     };
-    // --- 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
+    // --- query profiles (tenant-owned query config; full CRUD with the tenant key) ---
+    queryProfiles = {
+        /** List this tenant's query profiles. */
+        list: (q) => this.request("GET", "/v1/query-profiles", { query: q }),
+        listAll: () => this.pageAll("/v1/query-profiles"),
+        get: (id) => this.request("GET", `/v1/query-profiles/${id}`),
+        /** Create a query profile owned by this tenant (the owning tenant is the key's — no tenant_id in the body). */
+        create: (b) => this.request("POST", "/v1/query-profiles", { json: b }),
+        update: (id, b) => this.request("PATCH", `/v1/query-profiles/${id}`, { json: b }),
+        delete: (id) => this.request("DELETE", `/v1/query-profiles/${id}`),
+        /** The model catalog for an query-profile-config UI: supported models + default per field, per-model
          *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
-        modelOptions: () => this.request("GET", "/v1/agents/model-options"),
+        modelOptions: () => this.request("GET", "/v1/query-profiles/model-options"),
     };
-    /** Ingestion profiles — the build-side config object (counterpart to `agents`): a tenant-owned,
-     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+    /** Ingestion profiles — the build-side config object (counterpart to query profiles): a tenant-owned,
+     *  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. */
@@ -484,7 +486,7 @@ export class KnowledgeCoreClient extends HttpBase {
         delete: (id) => this.request("DELETE", `/v1/profiles/${id}`),
         /** The config catalog for a profile UI: supported embedding models (+ provider/dims),
          *  chunkers, distances, quantizations, per-field defaults/bounds, and the standard params.
-         *  Build-side mirror of `agents.modelOptions()`. */
+         *  Build-side mirror of `queryProfiles.modelOptions()`. */
         modelOptions: () => this.request("GET", "/v1/profiles/model-options"),
     };
     // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
@@ -519,7 +521,7 @@ export class KnowledgeCoreClient extends HttpBase {
 }
 // ---------------------------------------------------------------------------
 // Admin client (tenant + API-key provisioning) — use the ADMIN key.
-// Agents are tenant data; manage them with the tenant client (KnowledgeCoreClient.agents).
+// Query profiles are tenant data; manage them with the tenant client (KnowledgeCoreClient.queryProfiles).
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
     /** @param opts.apiKey the ADMIN key, supplied by the caller. */
@@ -544,14 +546,14 @@ export class AdminClient extends HttpBase {
  *  a chat turn is never lost and a chat conversation is never left blank. */
 export class ChatSession {
     #kc;
-    #agentId;
+    #profileId;
     #corpusIds;
     #creating = null;
     /** The conversation id — null until the first `send()` (unless resumed). */
     conversationId;
-    constructor(kc, agentId, corpusIds, conversationId) {
+    constructor(kc, profileId, corpusIds, conversationId) {
         this.#kc = kc;
-        this.#agentId = agentId;
+        this.#profileId = profileId;
         this.#corpusIds = corpusIds;
         this.conversationId = conversationId;
     }
@@ -572,7 +574,7 @@ export class ChatSession {
     async send(text, o = {}) {
         const convId = await this.#ensure(o, text);
         o.onConversationId?.(convId);
-        await this.#kc.queryStream(this.#agentId, { corpus_ids: this.#corpusIds, query: text, conversation_id: convId,
+        await this.#kc.queryStream(this.#profileId, { corpus_ids: this.#corpusIds, query: text, conversation_id: convId,
             overrides: o.overrides, filter: o.filter, visual: o.visual }, o, o.signal);
     }
     /** The conversation history (messages), once it exists. Empty page before the first send. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.42.0",
+  "version": "0.44.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:
@@ -100,7 +100,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";
@@ -250,7 +250,7 @@ export interface Corpus {
 /** Build-time knob bundle that DEFINES an index. Defaults are today's blessed config, so a
  *  profile created with no params is the blessed profile. Change any knob => different vectors
  *  => a different physical collection. Embedding/indexing/chunking is SYSTEM-level, never a
- *  query knob — this is the build-side counterpart to an Agent, not an agent. */
+ *  query knob — this is the build-side counterpart to a query profile. */
 export interface IngestionProfileParams {
   chunker: string;                     // "hybrid"
   chunk_child_max_tokens: number;
@@ -446,7 +446,7 @@ export interface Conversation {
 export interface Message {
   id: UUID;
   conversation_id: UUID;
-  agent_id: UUID | null;
+  query_profile_id: UUID | null;
   corpus_ids: UUID[] | null;
   query: string;
   answer: string | null;
@@ -472,14 +472,14 @@ export interface Feedback {
   rating: number | null;
   comment: string | null;
 }
-export interface Agent {
+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 +507,14 @@ export interface Agent {
   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 AgentWrite = Partial<Omit<Agent, "id" | "tenant_id">>;
+export type QueryProfileWrite = Partial<Omit<QueryProfile, "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);
+/** Model catalog for the query-profile-config UI (GET /v1/query-profiles/model-options). `models` maps id → its
+ *  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 {
@@ -758,19 +758,19 @@ export class KnowledgeCoreClient extends HttpBase {
     super(opts);
   }
 
-  // --- query (agent-anchored) ---
-  query(agentId: UUID, body: QueryRequest): Promise<QueryResponse> {
-    return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
+  // --- query (query-profile-anchored) ---
+  query(profileId: UUID, body: QueryRequest): Promise<QueryResponse> {
+    return this.request("POST", `/v1/query-profiles/${profileId}/query`, { json: body });
   }
 
   /** Streaming query (SSE). Resolves when the stream ends (the Promise resolving is normal, not an
    *  error). Pass `signal` and abort() on unmount / when the user cancels or navigates away so the
    *  connection doesn't linger. Transient (ends on `done`) — no reopen logic needed. */
-  async queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void> {
-    const res = await this.raw("POST", `/v1/agents/${agentId}/query/stream`, { json: body, signal });
+  async queryStream(profileId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void> {
+    const res = await this.raw("POST", `/v1/query-profiles/${profileId}/query/stream`, { json: body, signal });
     if (!res.ok || !res.body) {
       const t = await res.text();
-      throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/agents/${agentId}/query/stream`);
+      throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/query-profiles/${profileId}/query/stream`);
     }
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
@@ -825,12 +825,12 @@ export class KnowledgeCoreClient extends HttpBase {
   /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
    *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
    *  `query`/`queryStream` ONLY for programmatic one-shots (tools).
-   *    New chat:  const chat = kc.chat(agentId, corpusIds);
-   *    Resume:    const chat = kc.chat(agentId, corpusIds, { conversationId });
+   *    New chat:  const chat = kc.chat(profileId, corpusIds);
+   *    Resume:    const chat = kc.chat(profileId, corpusIds, { conversationId });
    *  The conversation is created LAZILY on the first `send()` (opening a "new chat" and never
    *  sending leaves nothing behind). See ChatSession.send. */
-  chat(agentId: UUID, corpusIds: UUID[], opts?: { conversationId?: UUID }): ChatSession {
-    return new ChatSession(this, agentId, corpusIds, opts?.conversationId ?? null);
+  chat(profileId: UUID, corpusIds: UUID[], opts?: { conversationId?: UUID }): ChatSession {
+    return new ChatSession(this, profileId, corpusIds, opts?.conversationId ?? null);
   }
 
   /** Shared SSE reader for the document-status streams (documents.events / folders.events).
@@ -893,7 +893,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 +901,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 +918,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 +929,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 +951,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 +990,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,
         } },
       ),
 
@@ -1126,23 +1128,23 @@ export class KnowledgeCoreClient extends HttpBase {
     delete: (id: UUID) => this.request<void>("DELETE", `/v1/feedback/${id}`),
   };
 
-  // --- 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
+  // --- query profiles (tenant-owned query config; full CRUD with the tenant key) ---
+  queryProfiles = {
+    /** List this tenant's query profiles. */
+    list: (q?: { limit?: number; cursor?: string }) => this.request<Page<QueryProfile>>("GET", "/v1/query-profiles", { query: q }),
+    listAll: () => this.pageAll<QueryProfile>("/v1/query-profiles"),
+    get: (id: UUID) => this.request<QueryProfile>("GET", `/v1/query-profiles/${id}`),
+    /** Create a query profile owned by this tenant (the owning tenant is the key's — no tenant_id in the body). */
+    create: (b: QueryProfileWrite & { name: string }) => this.request<QueryProfile>("POST", "/v1/query-profiles", { json: b }),
+    update: (id: UUID, b: QueryProfileWrite) => this.request<QueryProfile>("PATCH", `/v1/query-profiles/${id}`, { json: b }),
+    delete: (id: UUID) => this.request<void>("DELETE", `/v1/query-profiles/${id}`),
+    /** The model catalog for an query-profile-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"),
+    modelOptions: () => this.request<ModelOptions>("GET", "/v1/query-profiles/model-options"),
   };
 
-  /** Ingestion profiles — the build-side config object (counterpart to `agents`): a tenant-owned,
-   *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+  /** Ingestion profiles — the build-side config object (counterpart to query profiles): a tenant-owned,
+   *  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. */
@@ -1161,7 +1163,7 @@ export class KnowledgeCoreClient extends HttpBase {
     delete: (id: UUID) => this.request<void>("DELETE", `/v1/profiles/${id}`),
     /** The config catalog for a profile UI: supported embedding models (+ provider/dims),
      *  chunkers, distances, quantizations, per-field defaults/bounds, and the standard params.
-     *  Build-side mirror of `agents.modelOptions()`. */
+     *  Build-side mirror of `queryProfiles.modelOptions()`. */
     modelOptions: () => this.request<IngestionProfileOptions>("GET", "/v1/profiles/model-options"),
   };
 
@@ -1202,7 +1204,7 @@ export class KnowledgeCoreClient extends HttpBase {
 
 // ---------------------------------------------------------------------------
 // Admin client (tenant + API-key provisioning) — use the ADMIN key.
-// Agents are tenant data; manage them with the tenant client (KnowledgeCoreClient.agents).
+// Query profiles are tenant data; manage them with the tenant client (KnowledgeCoreClient.queryProfiles).
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
   /** @param opts.apiKey the ADMIN key, supplied by the caller. */
@@ -1221,8 +1223,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}`),
   };
-  // Agents are TENANT data, not an admin surface — manage them with the tenant key via
-  // KnowledgeCoreClient.agents (create/update/delete/list/get/modelOptions).
+  // Query profiles are TENANT data, not an admin surface — manage them with the tenant key via
+  // KnowledgeCoreClient.queryProfiles (create/update/delete/list/get/modelOptions).
 }
 
 export interface ChatSendOptions extends StreamHandlers {
@@ -1247,15 +1249,15 @@ export interface ChatSendOptions extends StreamHandlers {
  *  a chat turn is never lost and a chat conversation is never left blank. */
 export class ChatSession {
   #kc: KnowledgeCoreClient;
-  #agentId: UUID;
+  #profileId: UUID;
   #corpusIds: UUID[];
   #creating: Promise<UUID> | null = null;
   /** The conversation id — null until the first `send()` (unless resumed). */
   conversationId: UUID | null;
 
-  constructor(kc: KnowledgeCoreClient, agentId: UUID, corpusIds: UUID[], conversationId: UUID | null) {
+  constructor(kc: KnowledgeCoreClient, profileId: UUID, corpusIds: UUID[], conversationId: UUID | null) {
     this.#kc = kc;
-    this.#agentId = agentId;
+    this.#profileId = profileId;
     this.#corpusIds = corpusIds;
     this.conversationId = conversationId;
   }
@@ -1278,7 +1280,7 @@ export class ChatSession {
     const convId = await this.#ensure(o, text);
     o.onConversationId?.(convId);
     await this.#kc.queryStream(
-      this.#agentId,
+      this.#profileId,
       { corpus_ids: this.#corpusIds, query: text, conversation_id: convId,
         overrides: o.overrides, filter: o.filter, visual: o.visual },
       o,