@babav/knowledge-core-client 0.39.0 → 0.41.0

package/dist/index.d.ts

@@ -212,6 +212,39 @@ export interface Corpus {
     description: string | null;
     custom_metadata: Record<string, unknown>;
 }
+/** 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;
     corpus_id: UUID;
@@ -948,6 +981,27 @@ 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 tenant-owned,
+     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+     *  (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. */
+    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?: {

package/dist/index.js

@@ -467,6 +467,22 @@ 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 tenant-owned,
+     *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+     *  (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. */
+    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). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.39.0",
+  "version": "0.41.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>;
+  // NB: the ingestion profile is TENANT-level (governs the whole collection), never per-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. */
+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;
@@ -1092,6 +1129,26 @@ 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 tenant-owned,
+   *  named bundle of pipeline config (chunking + embedding + sparse + quant). Unlike an agent
+   *  (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. */
+  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). */