@babav/knowledge-core-client 0.38.1 → 0.40.0

package/dist/index.d.ts

@@ -211,6 +211,40 @@ export interface Corpus {
     name: string;
     description: string | null;
     custom_metadata: Record<string, unknown>;
+    profile_id: UUID | null;
+}
+/** 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. */
+export interface IngestionProfileParams {
+    chunker: string;
+    chunk_child_max_tokens: number;
+    chunk_parent_max_tokens: number;
+    contextualize: boolean;
+    embedding_provider: string;
+    embedding_model: string;
+    embedding_dimensions: number;
+    distance: string;
+    sparse: boolean;
+    quantization: string;
+    hnsw_m: number | null;
+    hnsw_ef_construct: number | null;
+}
+export interface IngestionProfile {
+    id: UUID;
+    tenant_id: UUID;
+    name: string;
+    params: IngestionProfileParams;
+    fingerprint: string;
+    is_default: boolean;
+}
+/** Fields settable when creating/updating a profile. `params` may be partial on create
+ *  (omitted knobs take the blessed default). The owning tenant is the key's — never in the body. */
+export interface IngestionProfileWrite {
+    name?: string;
+    params?: Partial<IngestionProfileParams>;
+    is_default?: boolean;
 }
 export interface Folder {
     id: UUID;
@@ -342,16 +376,22 @@ export interface ChunkHeat {
         bbox: [number, number, number, number];
     }[] | null;
 }
-/** Everything to overlay retrieval heat on the original document: a signed view-PDF URL
- * (render with pdf.js), its per-page geometry, and every chunk's heat + boxes. */
+/** Everything to overlay retrieval heat on the original document. Fetch the view-PDF BYTES
+ * via `analytics.documentViewPdf(id)` from YOUR BACKEND (KC serves them; the browser never
+ * touches GCS), render with pdf.js, and shade chunks by heat. `insufficient_data` (with
+ * `retrieval_events` as the sample size) is the document-level analogue of the corpus heat
+ * view's insufficient_data band — show a clear "not enough data yet" indication instead of
+ * misleading shading when it's true. */
 export interface ChunkHeatmapResponse {
     document_id: UUID;
-    view_pdf_url: string | null;
+    has_view_pdf: boolean;
     page_dims: {
         w: number;
         h: number;
         rotation: number;
     }[] | null;
+    retrieval_events: number;
+    insufficient_data: boolean;
     chunks: ChunkHeat[];
 }
 export interface MonthlyCorpus {
@@ -563,6 +603,8 @@ declare class HttpBase {
     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>;
+    /** GET binary bytes as a Blob (error bodies are JSON, so decode+throw on !ok). */
+    protected rawBytes(method: string, path: string, signal?: AbortSignal): Promise<Blob>;
     /** Auto-paginate a list endpoint into a single array. */
     protected pageAll<T>(path: string, query?: RequestOpts["query"]): Promise<T[]>;
 }
@@ -673,6 +715,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
             name: string;
             description?: string;
             custom_metadata?: Record<string, unknown>;
+            profile_id?: UUID;
         }) => Promise<Corpus>;
         list: (q?: {
             limit?: number;
@@ -686,11 +729,13 @@ export declare class KnowledgeCoreClient extends HttpBase {
             cursor?: string;
         }) => Promise<Page<Corpus>>;
         get: (id: UUID) => Promise<Corpus>;
-        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
+        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). `profile_id`
+         *  reassigns the ingestion profile (does NOT re-index; applies on next (re)ingest). */
         update: (id: UUID, b: {
             name?: string;
             description?: string;
             custom_metadata?: Record<string, unknown>;
+            profile_id?: UUID | null;
         }) => Promise<Corpus>;
         delete: (id: UUID, confirmName: string) => Promise<void>;
         listFolders: (id: UUID) => Promise<Folder[]>;
@@ -940,6 +985,25 @@ export declare class KnowledgeCoreClient extends HttpBase {
          *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
         modelOptions: () => Promise<ModelOptions>;
     };
+    /** Ingestion profiles — the build-side config object (counterpart to `agents`). A profile
+     *  DEFINES an index (chunking + embedding + sparse + quant); its `fingerprint` is the physical
+     *  collection identity. Attach one to a corpus via `corpora.create/update({ profile_id })`. */
+    profiles: {
+        /** List this tenant's ingestion profiles. */
+        list: (q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<IngestionProfile>>;
+        listAll: () => Promise<IngestionProfile[]>;
+        get: (id: UUID) => Promise<IngestionProfile>;
+        /** Create a profile owned by this tenant. Omit `params` for the blessed profile (all defaults). */
+        create: (b: IngestionProfileWrite & {
+            name: string;
+        }) => Promise<IngestionProfile>;
+        update: (id: UUID, b: IngestionProfileWrite) => Promise<IngestionProfile>;
+        /** Delete a profile. 409 if any corpus still references it. */
+        delete: (id: UUID) => Promise<void>;
+    };
     analytics: {
         /** Query-volume time series for a corpus (the denominator for everything). */
         corpusUsage: (corpusId: UUID, q?: {
@@ -962,9 +1026,15 @@ export declare class KnowledgeCoreClient extends HttpBase {
         document: (documentId: UUID) => Promise<DocumentAnalytics>;
         /** Parent-section grain for a document (never exposes chunk ids). */
         documentSections: (documentId: UUID) => Promise<SectionsResponse>;
-        /** Per-chunk retrieval heat + position in the document's view-PDF, plus a signed
-         * view-PDF URL — everything to overlay heat on the ORIGINAL document with pdf.js. */
+        /** Per-chunk retrieval heat + position + `has_view_pdf` + the `insufficient_data`
+         * indication — everything to overlay heat on the ORIGINAL document with pdf.js. Fetch the
+         * view-PDF bytes with `documentViewPdf(id)` (below). */
         documentChunks: (documentId: UUID) => Promise<ChunkHeatmapResponse>;
+        /** Fetch the document's canonical view-PDF BYTES (the surface for the heat overlay).
+         * Call this from YOUR BACKEND — KC serves the bytes, so the browser never fetches from
+         * GCS (no bucket CORS). Returns a Blob (Node: `Buffer.from(await blob.arrayBuffer())`;
+         * browser: `URL.createObjectURL(blob)`). Rejects 404 when `has_view_pdf` is false. */
+        documentViewPdf: (documentId: UUID, signal?: AbortSignal) => Promise<Blob>;
         /** Whole-corpus scatter payload: every document with x=retrieved_reach, y=conversion,
          *  bubble=chunk_count, and a server-computed quadrant. No pagination (`truncated` if capped). */
         corpusScatter: (corpusId: UUID) => Promise<ScatterResponse>;

package/dist/index.js

@@ -102,6 +102,15 @@ class HttpBase {
             throw new KnowledgeCoreError(res.status, parsed ?? text, path);
         return parsed;
     }
+    /** GET binary bytes as a Blob (error bodies are JSON, so decode+throw on !ok). */
+    async rawBytes(method, path, signal) {
+        const res = await this.raw(method, path, { signal });
+        if (!res.ok) {
+            const t = await res.text();
+            throw new KnowledgeCoreError(res.status, safeJson(t), path);
+        }
+        return await res.blob();
+    }
     /** Auto-paginate a list endpoint into a single array. */
     async pageAll(path, query = {}) {
         const out = [];
@@ -259,7 +268,8 @@ export class KnowledgeCoreClient extends HttpBase {
         /** Filter corpora by custom_metadata using the same metadata filter as documents. */
         search: (b) => this.request("POST", "/v1/corpora/search", { json: b }),
         get: (id) => this.request("GET", `/v1/corpora/${id}`),
-        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
+        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). `profile_id`
+         *  reassigns the ingestion profile (does NOT re-index; applies on next (re)ingest). */
         update: (id, b) => this.request("PATCH", `/v1/corpora/${id}`, { json: b }),
         delete: (id, confirmName) => this.request("DELETE", `/v1/corpora/${id}`, { query: { confirm: confirmName } }),
         listFolders: (id) => this.pageAll(`/v1/corpora/${id}/folders`),
@@ -458,6 +468,20 @@ export class KnowledgeCoreClient extends HttpBase {
          *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
         modelOptions: () => this.request("GET", "/v1/agents/model-options"),
     };
+    /** Ingestion profiles — the build-side config object (counterpart to `agents`). A profile
+     *  DEFINES an index (chunking + embedding + sparse + quant); its `fingerprint` is the physical
+     *  collection identity. Attach one to a corpus via `corpora.create/update({ profile_id })`. */
+    profiles = {
+        /** List this tenant's ingestion profiles. */
+        list: (q) => this.request("GET", "/v1/profiles", { query: q }),
+        listAll: () => this.pageAll("/v1/profiles"),
+        get: (id) => this.request("GET", `/v1/profiles/${id}`),
+        /** Create a profile owned by this tenant. Omit `params` for the blessed profile (all defaults). */
+        create: (b) => this.request("POST", "/v1/profiles", { json: b }),
+        update: (id, b) => this.request("PATCH", `/v1/profiles/${id}`, { json: b }),
+        /** Delete a profile. 409 if any corpus still references it. */
+        delete: (id) => this.request("DELETE", `/v1/profiles/${id}`),
+    };
     // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
     analytics = {
         /** Query-volume time series for a corpus (the denominator for everything). */
@@ -468,9 +492,15 @@ export class KnowledgeCoreClient extends HttpBase {
         document: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}`),
         /** Parent-section grain for a document (never exposes chunk ids). */
         documentSections: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}/sections`),
-        /** Per-chunk retrieval heat + position in the document's view-PDF, plus a signed
-         * view-PDF URL — everything to overlay heat on the ORIGINAL document with pdf.js. */
+        /** Per-chunk retrieval heat + position + `has_view_pdf` + the `insufficient_data`
+         * indication — everything to overlay heat on the ORIGINAL document with pdf.js. Fetch the
+         * view-PDF bytes with `documentViewPdf(id)` (below). */
         documentChunks: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}/chunks`),
+        /** Fetch the document's canonical view-PDF BYTES (the surface for the heat overlay).
+         * Call this from YOUR BACKEND — KC serves the bytes, so the browser never fetches from
+         * GCS (no bucket CORS). Returns a Blob (Node: `Buffer.from(await blob.arrayBuffer())`;
+         * browser: `URL.createObjectURL(blob)`). Rejects 404 when `has_view_pdf` is false. */
+        documentViewPdf: (documentId, signal) => this.rawBytes("GET", `/v1/analytics/documents/${documentId}/view-pdf`, signal),
         /** Whole-corpus scatter payload: every document with x=retrieved_reach, y=conversion,
          *  bubble=chunk_count, and a server-computed quadrant. No pagination (`truncated` if capped). */
         corpusScatter: (corpusId) => this.request("GET", `/v1/analytics/corpora/${corpusId}/scatter`),

package/package.json

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

@@ -244,6 +244,43 @@ export interface Corpus {
   name: string;
   description: string | null;
   custom_metadata: Record<string, unknown>;
+  profile_id: UUID | null;   // ingestion profile the corpus is indexed under (null => tenant's blessed default)
+}
+
+/** 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. */
+export interface IngestionProfileParams {
+  chunker: string;                     // "hybrid"
+  chunk_child_max_tokens: number;
+  chunk_parent_max_tokens: number;
+  contextualize: boolean;
+  embedding_provider: string;          // "voyage_context" | "voyage" | "gemini"
+  embedding_model: string;
+  embedding_dimensions: number;
+  distance: string;                    // "cosine" | "dot" | "euclid"
+  sparse: boolean;
+  quantization: string;                // "int8" | "none"
+  hnsw_m: number | null;               // null => Qdrant default
+  hnsw_ef_construct: number | null;    // null => Qdrant default
+}
+
+export interface IngestionProfile {
+  id: UUID;
+  tenant_id: UUID;                     // owning tenant (every profile belongs to one; no globals)
+  name: string;
+  params: IngestionProfileParams;
+  fingerprint: string;                 // stable hash of params — the physical collection identity
+  is_default: boolean;                 // at most one blessed profile per tenant
+}
+
+/** Fields settable when creating/updating a profile. `params` may be partial on create
+ *  (omitted knobs take the blessed default). The owning tenant is the key's — never in the body. */
+export interface IngestionProfileWrite {
+  name?: string;
+  params?: Partial<IngestionProfileParams>;
+  is_default?: boolean;
 }
 export interface Folder {
   id: UUID;
@@ -346,12 +383,18 @@ export interface ChunkHeat {
   method: string | null;
   regions: { page: number; bbox: [number, number, number, number] }[] | null;
 }
-/** Everything to overlay retrieval heat on the original document: a signed view-PDF URL
- * (render with pdf.js), its per-page geometry, and every chunk's heat + boxes. */
+/** Everything to overlay retrieval heat on the original document. Fetch the view-PDF BYTES
+ * via `analytics.documentViewPdf(id)` from YOUR BACKEND (KC serves them; the browser never
+ * touches GCS), render with pdf.js, and shade chunks by heat. `insufficient_data` (with
+ * `retrieval_events` as the sample size) is the document-level analogue of the corpus heat
+ * view's insufficient_data band — show a clear "not enough data yet" indication instead of
+ * misleading shading when it's true. */
 export interface ChunkHeatmapResponse {
   document_id: UUID;
-  view_pdf_url: string | null;
+  has_view_pdf: boolean;      // a view-PDF exists -> fetch bytes with analytics.documentViewPdf(id)
   page_dims: { w: number; h: number; rotation: number }[] | null;
+  retrieval_events: number;   // distinct retrievals this doc appeared in (heat sample size)
+  insufficient_data: boolean; // too few retrievals to trust per-chunk heat yet
   chunks: ChunkHeat[];
 }
 export interface MonthlyCorpus {
@@ -589,6 +632,16 @@ class HttpBase {
     return parsed as T;
   }
 
+  /** GET binary bytes as a Blob (error bodies are JSON, so decode+throw on !ok). */
+  protected async rawBytes(method: string, path: string, signal?: AbortSignal): Promise<Blob> {
+    const res = await this.raw(method, path, { signal });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new KnowledgeCoreError(res.status, safeJson(t), path);
+    }
+    return await res.blob();
+  }
+
   /** Auto-paginate a list endpoint into a single array. */
   protected async pageAll<T>(path: string, query: RequestOpts["query"] = {}): Promise<T[]> {
     const out: T[] = [];
@@ -803,7 +856,7 @@ export class KnowledgeCoreClient extends HttpBase {
 
   // --- corpora ---
   corpora = {
-    create: (b: { name: string; description?: string; custom_metadata?: Record<string, unknown> }) =>
+    create: (b: { name: string; description?: string; custom_metadata?: Record<string, unknown>; profile_id?: UUID }) =>
       this.request<Corpus>("POST", "/v1/corpora", { json: b }),
     list: (q?: { limit?: number; cursor?: string }) => this.request<Page<Corpus>>("GET", "/v1/corpora", { query: q }),
     listAll: () => this.pageAll<Corpus>("/v1/corpora"),
@@ -811,8 +864,9 @@ export class KnowledgeCoreClient extends HttpBase {
     search: (b: { filter?: MetadataFilter; limit?: number; cursor?: string }) =>
       this.request<Page<Corpus>>("POST", "/v1/corpora/search", { json: b }),
     get: (id: UUID) => this.request<Corpus>("GET", `/v1/corpora/${id}`),
-    /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
-    update: (id: UUID, b: { name?: string; description?: string; custom_metadata?: Record<string, unknown> }) =>
+    /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). `profile_id`
+     *  reassigns the ingestion profile (does NOT re-index; applies on next (re)ingest). */
+    update: (id: UUID, b: { name?: string; description?: string; custom_metadata?: Record<string, unknown>; profile_id?: UUID | null }) =>
       this.request<Corpus>("PATCH", `/v1/corpora/${id}`, { json: b }),
     delete: (id: UUID, confirmName: string) => this.request<void>("DELETE", `/v1/corpora/${id}`, { query: { confirm: confirmName } }),
     listFolders: (id: UUID) => this.pageAll<Folder>(`/v1/corpora/${id}/folders`),
@@ -1076,6 +1130,24 @@ export class KnowledgeCoreClient extends HttpBase {
     modelOptions: () => this.request<ModelOptions>("GET", "/v1/agents/model-options"),
   };
 
+  /** Ingestion profiles — the build-side config object (counterpart to `agents`). A profile
+   *  DEFINES an index (chunking + embedding + sparse + quant); its `fingerprint` is the physical
+   *  collection identity. Attach one to a corpus via `corpora.create/update({ profile_id })`. */
+  profiles = {
+    /** List this tenant's ingestion profiles. */
+    list: (q?: { limit?: number; cursor?: string }) =>
+      this.request<Page<IngestionProfile>>("GET", "/v1/profiles", { query: q }),
+    listAll: () => this.pageAll<IngestionProfile>("/v1/profiles"),
+    get: (id: UUID) => this.request<IngestionProfile>("GET", `/v1/profiles/${id}`),
+    /** Create a profile owned by this tenant. Omit `params` for the blessed profile (all defaults). */
+    create: (b: IngestionProfileWrite & { name: string }) =>
+      this.request<IngestionProfile>("POST", "/v1/profiles", { json: b }),
+    update: (id: UUID, b: IngestionProfileWrite) =>
+      this.request<IngestionProfile>("PATCH", `/v1/profiles/${id}`, { json: b }),
+    /** Delete a profile. 409 if any corpus still references it. */
+    delete: (id: UUID) => this.request<void>("DELETE", `/v1/profiles/${id}`),
+  };
+
   // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
   analytics = {
     /** Query-volume time series for a corpus (the denominator for everything). */
@@ -1088,9 +1160,16 @@ export class KnowledgeCoreClient extends HttpBase {
     document: (documentId: UUID) => this.request<DocumentAnalytics>("GET", `/v1/analytics/documents/${documentId}`),
     /** Parent-section grain for a document (never exposes chunk ids). */
     documentSections: (documentId: UUID) => this.request<SectionsResponse>("GET", `/v1/analytics/documents/${documentId}/sections`),
-    /** Per-chunk retrieval heat + position in the document's view-PDF, plus a signed
-     * view-PDF URL — everything to overlay heat on the ORIGINAL document with pdf.js. */
+    /** Per-chunk retrieval heat + position + `has_view_pdf` + the `insufficient_data`
+     * indication — everything to overlay heat on the ORIGINAL document with pdf.js. Fetch the
+     * view-PDF bytes with `documentViewPdf(id)` (below). */
     documentChunks: (documentId: UUID) => this.request<ChunkHeatmapResponse>("GET", `/v1/analytics/documents/${documentId}/chunks`),
+    /** Fetch the document's canonical view-PDF BYTES (the surface for the heat overlay).
+     * Call this from YOUR BACKEND — KC serves the bytes, so the browser never fetches from
+     * GCS (no bucket CORS). Returns a Blob (Node: `Buffer.from(await blob.arrayBuffer())`;
+     * browser: `URL.createObjectURL(blob)`). Rejects 404 when `has_view_pdf` is false. */
+    documentViewPdf: (documentId: UUID, signal?: AbortSignal): Promise<Blob> =>
+      this.rawBytes("GET", `/v1/analytics/documents/${documentId}/view-pdf`, signal),
     /** Whole-corpus scatter payload: every document with x=retrieved_reach, y=conversion,
      *  bubble=chunk_count, and a server-computed quadrant. No pagination (`truncated` if capped). */
     corpusScatter: (corpusId: UUID) => this.request<ScatterResponse>("GET", `/v1/analytics/corpora/${corpusId}/scatter`),