@babav/knowledge-core-client 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -51,9 +51,14 @@ export interface RetrievalContent {
 }
 export interface QueryOverrides {
     generation_model?: string;
+    max_response_tokens?: number;
     top_k?: number;
+    candidate_multiplier?: 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;
@@ -87,23 +92,31 @@ export interface Citation {
     custom_metadata: Record<string, unknown>;
     source_url: string | null;
 }
-export interface GroundednessSentence {
+export interface GroundednessClaim {
     /** Char span into the RAW answer (concatenated tokens / `final.answer`). */
     text_span: [number, number];
-    /** The exact sentence text — highlight by matching this in the rendered output
-     *  (robust to markdown rendering + inserted citation markers) rather than offsets. */
+    /** The exact claim text (a verbatim substring of the answer) — highlight by matching
+     *  this in the rendered output rather than by offsets (robust to markdown + citation
+     *  markers). Claims with `passed === false` are the unsupported spans to flag. */
     text: string;
+    /** Verdict from the LLM verifier: 1.0 = supported, 0.5 = partially supported,
+     *  0.0 = unsupported/contradicted (by the retrieved sources). */
     score: number;
     passed: boolean | null;
+    /** The verifier's brief justification for the verdict (why supported/partial/unsupported). */
+    reason?: string | null;
 }
+/** @deprecated Alias — groundedness entries are now per-claim. Use GroundednessClaim. */
+export type GroundednessSentence = GroundednessClaim;
 export interface Groundedness {
-    /** Headline faithfulness of the whole answer vs. the full context. */
+    /** Headline faithfulness of the whole answer = mean of the per-claim scores. */
     overall: {
         score: number | null;
         passed: boolean | null;
     };
-    /** Per-sentence faithfulness — flag low-`score` sentences as weakly grounded. */
-    sentences: GroundednessSentence[];
+    /** Per-CLAIM faithfulness from an independent Claude (Haiku) verifier that checks each
+     *  extracted claim against the retrieved sources. `model` reports the verifier. */
+    sentences: GroundednessClaim[];
     model: string;
     threshold: number | null;
 }
@@ -191,9 +204,14 @@ export interface Agent {
     identity_prompt: string | null;
     response_prompt: string | null;
     generation_model: string | null;
+    max_response_tokens: number | null;
     top_k: number | null;
+    candidate_multiplier: number | null;
+    sibling_window: number | null;
     rerank_instruction: string | null;
     max_hops: number | null;
+    decomposition_model: string | null;
+    groundedness_verifier_model: string | null;
     groundedness_threshold: number | null;
     grounding_enabled: boolean | null;
     citations_enabled: boolean | null;
@@ -488,9 +506,14 @@ export declare class AdminClient extends HttpBase {
             identity_prompt?: string;
             response_prompt?: string;
             generation_model?: string;
+            max_response_tokens?: number;
             top_k?: number;
+            candidate_multiplier?: 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -61,9 +61,14 @@ export interface RetrievalContent {
 
 export interface QueryOverrides {
   generation_model?: string;
+  max_response_tokens?: number;     // max answer tokens
   top_k?: number;
+  candidate_multiplier?: number;    // candidate pool = top_k * this (before rerank)
+  sibling_window?: number;          // adjacent sections fetched each side of a hit
   rerank_instruction?: string;
   max_hops?: number;
+  decomposition_model?: string;     // model for query decomposition
+  groundedness_verifier_model?: string;  // model for the groundedness LLM judge
   groundedness_threshold?: number;
   grounding_enabled?: boolean;   // groundedness score (default off)
   citations_enabled?: boolean;   // source attribution (default on)
@@ -102,20 +107,28 @@ export interface Citation {
   source_url: string | null;
 }
 
-export interface GroundednessSentence {
+export interface GroundednessClaim {
   /** Char span into the RAW answer (concatenated tokens / `final.answer`). */
   text_span: [number, number];
-  /** The exact sentence text — highlight by matching this in the rendered output
-   *  (robust to markdown rendering + inserted citation markers) rather than offsets. */
+  /** The exact claim text (a verbatim substring of the answer) — highlight by matching
+   *  this in the rendered output rather than by offsets (robust to markdown + citation
+   *  markers). Claims with `passed === false` are the unsupported spans to flag. */
   text: string;
+  /** Verdict from the LLM verifier: 1.0 = supported, 0.5 = partially supported,
+   *  0.0 = unsupported/contradicted (by the retrieved sources). */
   score: number;
   passed: boolean | null;
+  /** The verifier's brief justification for the verdict (why supported/partial/unsupported). */
+  reason?: string | null;
 }
+/** @deprecated Alias — groundedness entries are now per-claim. Use GroundednessClaim. */
+export type GroundednessSentence = GroundednessClaim;
 export interface Groundedness {
-  /** Headline faithfulness of the whole answer vs. the full context. */
+  /** Headline faithfulness of the whole answer = mean of the per-claim scores. */
   overall: { score: number | null; passed: boolean | null };
-  /** Per-sentence faithfulness — flag low-`score` sentences as weakly grounded. */
-  sentences: GroundednessSentence[];
+  /** Per-CLAIM faithfulness from an independent Claude (Haiku) verifier that checks each
+   *  extracted claim against the retrieved sources. `model` reports the verifier. */
+  sentences: GroundednessClaim[];
   model: string;
   threshold: number | null;
 }
@@ -204,9 +217,14 @@ export interface Agent {
   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;
+  max_response_tokens: number | null;
   top_k: number | null;
+  candidate_multiplier: number | null;
+  sibling_window: number | null;
   rerank_instruction: string | null;
   max_hops: number | null;
+  decomposition_model: string | null;
+  groundedness_verifier_model: string | null;
   groundedness_threshold: number | null;
   grounding_enabled: boolean | null;
   citations_enabled: boolean | null;
@@ -624,7 +642,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; top_k?: number; rerank_instruction?: string; max_hops?: number; 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?: number; candidate_multiplier?: 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 }) =>
       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 }),