@babav/knowledge-core-client 0.16.0 → 0.18.0

package/README.md

@@ -31,9 +31,11 @@ import { KnowledgeCoreClient } from "npm:@babav/knowledge-core-client";
 ## Usage
 
 ```ts
+// You supply baseUrl + your tenant key at construction (from wherever your app keeps
+// its config/secrets). The SDK never reads the environment or defaults a key itself.
 const kc = new KnowledgeCoreClient({
-  baseUrl: "https://babav-kc-api-gmtvlr3vta-uc.a.run.app",
-  apiKey: Deno.env.get("BABAV_KC_TENANT_KEY")!, // or process.env on Node
+  baseUrl: "https://knowledgecore.babav.ai",
+  apiKey: myTenantKey, // your tenant key, provided by your app
 });
 
 // One-shot grounded query

package/dist/index.d.ts

@@ -12,13 +12,12 @@
  * 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.
  *
- * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
- *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
- *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
- * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
- * (the app is then responsible for supplying it). A missing value (no param AND no
- * env var) throws at construction with a clear message. In Deno, env access needs
- * `--allow-env` (without it, pass the values explicitly).
+ * Configuration — the CALLER supplies credentials at construction; the SDK never reads
+ * the environment or defaults/derives a key itself:
+ *   new KnowledgeCoreClient({ baseUrl, apiKey })   // apiKey = a TENANT key
+ *   new AdminClient({ baseUrl, apiKey })            // apiKey = the ADMIN key
+ * The app decides where its key comes from (its own env/secret store) and passes it in.
+ * A missing baseUrl or apiKey throws at construction with a clear message.
  */
 export type UUID = string;
 export interface Page<T> {
@@ -56,8 +55,10 @@ export interface QueryOverrides {
     top_k_reranked_chunks?: number;
     sibling_window?: number;
     rerank_instruction?: string;
-    max_hops?: number;
+    max_subqueries?: number;
+    max_reasoning_rounds?: number;
     decomposition_model?: string;
+    reasoning_inspect_model?: string;
     groundedness_verifier_model?: string;
     groundedness_threshold?: number;
     grounding_enabled?: boolean;
@@ -209,8 +210,10 @@ export interface Agent {
     top_k_reranked_chunks: number | null;
     sibling_window: number | null;
     rerank_instruction: string | null;
-    max_hops: number | null;
+    max_subqueries: number | null;
+    max_reasoning_rounds: number | null;
     decomposition_model: string | null;
+    reasoning_inspect_model: string | null;
     groundedness_verifier_model: string | null;
     groundedness_threshold: number | null;
     grounding_enabled: boolean | null;
@@ -247,11 +250,11 @@ export declare class KnowledgeCoreError extends Error {
     get code(): string | undefined;
 }
 export interface ClientOptions {
-    /** API base URL. Defaults to env BABAV_KC_BASE_URL when omitted. */
-    baseUrl?: string;
-    /** Tenant key (KnowledgeCoreClient) or admin key (AdminClient). Defaults to env
-     *  BABAV_KC_TENANT_KEY / BABAV_KC_ADMIN_KEY respectively when omitted. */
-    apiKey?: string;
+    /** API base URL — REQUIRED, supplied by the caller. */
+    baseUrl: string;
+    /** API key — REQUIRED, supplied by the caller (a TENANT key for KnowledgeCoreClient,
+     *  the ADMIN key for AdminClient). The SDK never reads it from the environment. */
+    apiKey: string;
     /** Optional default fetch timeout (ms). Streaming ignores this. */
     timeoutMs?: number;
     fetch?: typeof fetch;
@@ -268,7 +271,7 @@ declare class HttpBase {
     protected readonly apiKey: string;
     protected readonly timeoutMs?: number;
     protected readonly _fetch: typeof fetch;
-    constructor(opts?: ClientOptions, keyEnvVar?: string);
+    constructor(opts: ClientOptions);
     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>;
@@ -293,8 +296,8 @@ export interface StreamHandlers {
     onEvent?: (event: string, data: unknown) => void;
 }
 export declare class KnowledgeCoreClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
-    constructor(opts?: ClientOptions);
+    /** @param opts.apiKey a TENANT key, supplied by the caller. */
+    constructor(opts: ClientOptions);
     query(agentId: UUID, body: QueryRequest): Promise<QueryResponse>;
     /** Streaming query (SSE). Resolves when the stream ends. */
     queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
@@ -480,8 +483,8 @@ export declare class KnowledgeCoreClient extends HttpBase {
     };
 }
 export declare class AdminClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
-    constructor(opts?: ClientOptions);
+    /** @param opts.apiKey the ADMIN key, supplied by the caller. */
+    constructor(opts: ClientOptions);
     tenants: {
         create: (b: Partial<Tenant> & {
             name: string;
@@ -512,8 +515,10 @@ export declare class AdminClient extends HttpBase {
             top_k_reranked_chunks?: number;
             sibling_window?: number;
             rerank_instruction?: string;
-            max_hops?: number;
+            max_subqueries?: number;
+            max_reasoning_rounds?: number;
             decomposition_model?: string;
+            reasoning_inspect_model?: string;
             groundedness_verifier_model?: string;
             groundedness_threshold?: number;
             grounding_enabled?: boolean;

package/dist/index.js

@@ -12,13 +12,12 @@
  * 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.
  *
- * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
- *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
- *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
- * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
- * (the app is then responsible for supplying it). A missing value (no param AND no
- * env var) throws at construction with a clear message. In Deno, env access needs
- * `--allow-env` (without it, pass the values explicitly).
+ * Configuration — the CALLER supplies credentials at construction; the SDK never reads
+ * the environment or defaults/derives a key itself:
+ *   new KnowledgeCoreClient({ baseUrl, apiKey })   // apiKey = a TENANT key
+ *   new AdminClient({ baseUrl, apiKey })            // apiKey = the ADMIN key
+ * The app decides where its key comes from (its own env/secret store) and passes it in.
+ * A missing baseUrl or apiKey throws at construction with a clear message.
  */
 // ---------------------------------------------------------------------------
 // Errors
@@ -43,37 +42,19 @@ export class KnowledgeCoreError extends Error {
         return d?.detail?.error ?? d?.error;
     }
 }
-/** Read an env var under Node (process.env) or Deno (Deno.env); undefined if unset
- *  or inaccessible (e.g. Deno without --allow-env). */
-function readEnv(name) {
-    const g = globalThis;
-    const fromNode = g.process?.env?.[name];
-    if (fromNode)
-        return fromNode;
-    try {
-        const fromDeno = g.Deno?.env?.get?.(name);
-        if (fromDeno)
-            return fromDeno;
-    }
-    catch {
-        /* Deno env access denied (no --allow-env) — treat as unset */
-    }
-    return undefined;
-}
 class HttpBase {
     baseUrl;
     apiKey;
     timeoutMs;
     _fetch;
-    constructor(opts = {}, keyEnvVar = "BABAV_KC_TENANT_KEY") {
-        const baseUrl = opts.baseUrl ?? readEnv("BABAV_KC_BASE_URL");
-        const apiKey = opts.apiKey ?? readEnv(keyEnvVar);
-        if (!baseUrl)
-            throw new Error("KnowledgeCore: no base URL — pass { baseUrl } or set BABAV_KC_BASE_URL");
-        if (!apiKey)
-            throw new Error(`KnowledgeCore: no API key — pass { apiKey } or set ${keyEnvVar}`);
-        this.baseUrl = baseUrl.replace(/\/+$/, "");
-        this.apiKey = apiKey;
+    constructor(opts) {
+        // Credentials come from the CALLER at init — the SDK never sources a key itself.
+        if (!opts?.baseUrl)
+            throw new Error("KnowledgeCore: { baseUrl } is required");
+        if (!opts?.apiKey)
+            throw new Error("KnowledgeCore: { apiKey } is required — the caller must supply the key at init");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
         this.timeoutMs = opts.timeoutMs;
         this._fetch = opts.fetch ?? fetch;
     }
@@ -162,9 +143,9 @@ const MULTIPART_MAX_BYTES = 30 * 1024 * 1024;
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
 export class KnowledgeCoreClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
-    constructor(opts = {}) {
-        super(opts, "BABAV_KC_TENANT_KEY");
+    /** @param opts.apiKey a TENANT key, supplied by the caller. */
+    constructor(opts) {
+        super(opts);
     }
     // --- query (agent-anchored) ---
     query(agentId, body) {
@@ -329,9 +310,9 @@ export class KnowledgeCoreClient extends HttpBase {
 // Admin client (tenant + key + agent management) — use the ADMIN key
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
-    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
-    constructor(opts = {}) {
-        super(opts, "BABAV_KC_ADMIN_KEY");
+    /** @param opts.apiKey the ADMIN key, supplied by the caller. */
+    constructor(opts) {
+        super(opts);
     }
     tenants = {
         create: (b) => this.request("POST", "/v1/tenants", { json: b }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps).",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,7 +11,10 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -23,12 +26,15 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/"
   },
   "devDependencies": {
     "typescript": "^5.6.0"
   },
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "sideEffects": false,
   "private": false,
   "license": "UNLICENSED"

package/src/index.ts

@@ -12,13 +12,12 @@
  * 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.
  *
- * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
- *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
- *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
- * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
- * (the app is then responsible for supplying it). A missing value (no param AND no
- * env var) throws at construction with a clear message. In Deno, env access needs
- * `--allow-env` (without it, pass the values explicitly).
+ * Configuration — the CALLER supplies credentials at construction; the SDK never reads
+ * the environment or defaults/derives a key itself:
+ *   new KnowledgeCoreClient({ baseUrl, apiKey })   // apiKey = a TENANT key
+ *   new AdminClient({ baseUrl, apiKey })            // apiKey = the ADMIN key
+ * The app decides where its key comes from (its own env/secret store) and passes it in.
+ * A missing baseUrl or apiKey throws at construction with a clear message.
  */
 
 // ---------------------------------------------------------------------------
@@ -66,8 +65,10 @@ export interface QueryOverrides {
   top_k_reranked_chunks?: number;   // sections kept after rerank -> the LLM
   sibling_window?: number;          // adjacent sections fetched each side of a hit
   rerank_instruction?: string;
-  max_hops?: number;
+  max_subqueries?: number;          // parallel decompose-and-merge breadth per retrieval step
+  max_reasoning_rounds?: number;    // iterative agentic-loop ceiling (1 = single pass; early-stops)
   decomposition_model?: string;     // model for query decomposition
+  reasoning_inspect_model?: string; // model for the per-round sufficiency / next-query decision
   groundedness_verifier_model?: string;  // model for the groundedness LLM judge
   groundedness_threshold?: number;
   grounding_enabled?: boolean;   // groundedness score (default off)
@@ -222,8 +223,10 @@ export interface Agent {
   top_k_reranked_chunks: number | null;
   sibling_window: number | null;
   rerank_instruction: string | null;
-  max_hops: number | null;
+  max_subqueries: number | null;
+  max_reasoning_rounds: number | null;
   decomposition_model: string | null;
+  reasoning_inspect_model: string | null;
   groundedness_verifier_model: string | null;
   groundedness_threshold: number | null;
   grounding_enabled: boolean | null;
@@ -275,34 +278,16 @@ export class KnowledgeCoreError extends Error {
 // Base HTTP
 // ---------------------------------------------------------------------------
 export interface ClientOptions {
-  /** API base URL. Defaults to env BABAV_KC_BASE_URL when omitted. */
-  baseUrl?: string;
-  /** Tenant key (KnowledgeCoreClient) or admin key (AdminClient). Defaults to env
-   *  BABAV_KC_TENANT_KEY / BABAV_KC_ADMIN_KEY respectively when omitted. */
-  apiKey?: string;
+  /** API base URL — REQUIRED, supplied by the caller. */
+  baseUrl: string;
+  /** API key — REQUIRED, supplied by the caller (a TENANT key for KnowledgeCoreClient,
+   *  the ADMIN key for AdminClient). The SDK never reads it from the environment. */
+  apiKey: string;
   /** Optional default fetch timeout (ms). Streaming ignores this. */
   timeoutMs?: number;
   fetch?: typeof fetch; // override for tests
 }
 
-/** Read an env var under Node (process.env) or Deno (Deno.env); undefined if unset
- *  or inaccessible (e.g. Deno without --allow-env). */
-function readEnv(name: string): string | undefined {
-  const g = globalThis as {
-    process?: { env?: Record<string, string | undefined> };
-    Deno?: { env?: { get?: (n: string) => string | undefined } };
-  };
-  const fromNode = g.process?.env?.[name];
-  if (fromNode) return fromNode;
-  try {
-    const fromDeno = g.Deno?.env?.get?.(name);
-    if (fromDeno) return fromDeno;
-  } catch {
-    /* Deno env access denied (no --allow-env) — treat as unset */
-  }
-  return undefined;
-}
-
 interface RequestOpts {
   query?: Record<string, string | number | boolean | undefined>;
   json?: unknown;
@@ -317,13 +302,12 @@ class HttpBase {
   protected readonly timeoutMs?: number;
   protected readonly _fetch: typeof fetch;
 
-  constructor(opts: ClientOptions = {}, keyEnvVar = "BABAV_KC_TENANT_KEY") {
-    const baseUrl = opts.baseUrl ?? readEnv("BABAV_KC_BASE_URL");
-    const apiKey = opts.apiKey ?? readEnv(keyEnvVar);
-    if (!baseUrl) throw new Error("KnowledgeCore: no base URL — pass { baseUrl } or set BABAV_KC_BASE_URL");
-    if (!apiKey) throw new Error(`KnowledgeCore: no API key — pass { apiKey } or set ${keyEnvVar}`);
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
-    this.apiKey = apiKey;
+  constructor(opts: ClientOptions) {
+    // Credentials come from the CALLER at init — the SDK never sources a key itself.
+    if (!opts?.baseUrl) throw new Error("KnowledgeCore: { baseUrl } is required");
+    if (!opts?.apiKey) throw new Error("KnowledgeCore: { apiKey } is required — the caller must supply the key at init");
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
     this.timeoutMs = opts.timeoutMs;
     this._fetch = opts.fetch ?? fetch;
   }
@@ -431,9 +415,9 @@ export interface StreamHandlers {
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
 export class KnowledgeCoreClient extends HttpBase {
-  /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
-  constructor(opts: ClientOptions = {}) {
-    super(opts, "BABAV_KC_TENANT_KEY");
+  /** @param opts.apiKey a TENANT key, supplied by the caller. */
+  constructor(opts: ClientOptions) {
+    super(opts);
   }
 
   // --- query (agent-anchored) ---
@@ -623,9 +607,9 @@ export class KnowledgeCoreClient extends HttpBase {
 // Admin client (tenant + key + agent management) — use the ADMIN key
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
-  /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
-  constructor(opts: ClientOptions = {}) {
-    super(opts, "BABAV_KC_ADMIN_KEY");
+  /** @param opts.apiKey the ADMIN key, supplied by the caller. */
+  constructor(opts: ClientOptions) {
+    super(opts);
   }
 
   tenants = {
@@ -642,7 +626,7 @@ export class AdminClient extends HttpBase {
 
   // Agents are query agents, global for now.
   agents = {
-    create: (b: { name: string; identity_prompt?: string; response_prompt?: string; generation_model?: string; max_response_tokens?: number; top_k_retrieved_chunks?: number; top_k_reranked_chunks?: number; sibling_window?: number; rerank_instruction?: string; max_hops?: number; decomposition_model?: string; groundedness_verifier_model?: string; groundedness_threshold?: number; grounding_enabled?: boolean; citations_enabled?: boolean }) =>
+    create: (b: { name: string; identity_prompt?: string; response_prompt?: string; generation_model?: string; max_response_tokens?: number; top_k_retrieved_chunks?: number; top_k_reranked_chunks?: number; sibling_window?: number; rerank_instruction?: string; max_subqueries?: number; max_reasoning_rounds?: number; decomposition_model?: string; reasoning_inspect_model?: string; groundedness_verifier_model?: string; groundedness_threshold?: number; grounding_enabled?: boolean; citations_enabled?: boolean }) =>
       this.request<Agent>("POST", "/v1/agents", { json: b }),
     update: (id: UUID, b: Partial<Omit<Agent, "id">>) =>
       this.request<Agent>("PATCH", `/v1/agents/${id}`, { json: b }),