@babav/knowledge-core-client 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -56,6 +56,7 @@ export interface QueryOverrides {
     max_hops?: number;
     groundedness_threshold?: number;
     grounding_enabled?: boolean;
+    citations_enabled?: boolean;
 }
 export interface QueryRequest {
     corpus_ids: UUID[];
@@ -75,21 +76,33 @@ export interface QueryResponse {
     standalone_query: string | null;
 }
 export interface Citation {
-    quote: string;
+    /** Char span IN THE ANSWER this citation supports (for highlighting). */
     text_span: [number, number] | null;
+    /** The exact SOURCE passage the model used (native Anthropic citation). */
+    cited_text: string | null;
     context_index: number;
     document_id: string;
     filename: string | null;
     visibility: Visibility | string;
     custom_metadata: Record<string, unknown>;
     source_url: string | null;
-    supported: boolean;
 }
-export interface Groundedness {
+export interface GroundednessSentence {
+    /** Char span IN THE ANSWER of this sentence. */
+    text_span: [number, number];
     score: number;
+    passed: boolean | null;
+}
+export interface Groundedness {
+    /** Headline faithfulness of the whole answer vs. the full context. */
+    overall: {
+        score: number | null;
+        passed: boolean | null;
+    };
+    /** Per-sentence faithfulness — flag low-`score` sentences as weakly grounded. */
+    sentences: GroundednessSentence[];
     model: string;
     threshold: number | null;
-    passed: boolean | null;
 }
 export interface Corpus {
     id: UUID;
@@ -180,6 +193,7 @@ export interface Agent {
     max_hops: number | null;
     groundedness_threshold: number | null;
     grounding_enabled: boolean | null;
+    citations_enabled: boolean | null;
 }
 export interface Tenant {
     id: UUID;
@@ -249,6 +263,12 @@ export interface StreamHandlers {
         retrieval_contents: RetrievalContent[];
     }) => void;
     onToken?: (text: string) => void;
+    /** A citation, emitted inline as the answer streams (Claude/native path). Also
+     *  present aggregated in the `final` event. */
+    onCitation?: (c: Citation) => void;
+    /** Per-sentence + overall groundedness, emitted once after the answer streams
+     *  (native path). Also present in `final`. May be `{}` if scoring was unavailable. */
+    onGroundedness?: (g: Groundedness | Record<string, never>) => void;
     onFinal?: (d: QueryResponse) => void;
     onError?: (d: unknown) => void;
     onDone?: () => void;
@@ -474,6 +494,7 @@ export declare class AdminClient extends HttpBase {
             max_hops?: number;
             groundedness_threshold?: number;
             grounding_enabled?: boolean;
+            citations_enabled?: boolean;
         }) => Promise<Agent>;
         update: (id: UUID, b: Partial<Omit<Agent, "id">>) => Promise<Agent>;
         delete: (id: UUID) => Promise<void>;

package/dist/index.js

@@ -374,6 +374,12 @@ function dispatchSse(frame, h) {
         case "token":
             h.onToken?.(data.text);
             break;
+        case "citation":
+            h.onCitation?.(data);
+            break;
+        case "groundedness":
+            h.onGroundedness?.(data);
+            break;
         case "final":
             h.onFinal?.(data);
             break;

package/package.json

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

@@ -65,7 +65,8 @@ export interface QueryOverrides {
   rerank_instruction?: string;
   max_hops?: number;
   groundedness_threshold?: number;
-  grounding_enabled?: boolean;
+  grounding_enabled?: boolean;   // HHEM groundedness score (default off)
+  citations_enabled?: boolean;   // source attribution (default on)
 }
 
 export interface QueryRequest {
@@ -88,8 +89,10 @@ export interface QueryResponse {
 }
 
 export interface Citation {
-  quote: string;
+  /** Char span IN THE ANSWER this citation supports (for highlighting). */
   text_span: [number, number] | null;
+  /** The exact SOURCE passage the model used (native Anthropic citation). */
+  cited_text: string | null;
   context_index: number;
   document_id: string;
   // Source identity carried inline — no per-citation API round-trip to render it.
@@ -97,13 +100,21 @@ export interface Citation {
   visibility: Visibility | string;
   custom_metadata: Record<string, unknown>;
   source_url: string | null;
-  supported: boolean;
 }
-export interface Groundedness {
+
+export interface GroundednessSentence {
+  /** Char span IN THE ANSWER of this sentence. */
+  text_span: [number, number];
   score: number;
+  passed: boolean | null;
+}
+export interface Groundedness {
+  /** Headline faithfulness of the whole answer vs. the full context. */
+  overall: { score: number | null; passed: boolean | null };
+  /** Per-sentence faithfulness — flag low-`score` sentences as weakly grounded. */
+  sentences: GroundednessSentence[];
   model: string;
   threshold: number | null;
-  passed: boolean | null;
 }
 
 export interface Corpus {
@@ -195,6 +206,7 @@ export interface Agent {
   max_hops: number | null;
   groundedness_threshold: number | null;
   grounding_enabled: boolean | null;
+  citations_enabled: boolean | null;
 }
 export interface Tenant {
   id: UUID;
@@ -385,6 +397,12 @@ const MULTIPART_MAX_BYTES = 30 * 1024 * 1024;
 export interface StreamHandlers {
   onSources?: (d: { retrieval_contents: RetrievalContent[] }) => void;
   onToken?: (text: string) => void;
+  /** A citation, emitted inline as the answer streams (Claude/native path). Also
+   *  present aggregated in the `final` event. */
+  onCitation?: (c: Citation) => void;
+  /** Per-sentence + overall groundedness, emitted once after the answer streams
+   *  (native path). Also present in `final`. May be `{}` if scoring was unavailable. */
+  onGroundedness?: (g: Groundedness | Record<string, never>) => void;
   onFinal?: (d: QueryResponse) => void;
   onError?: (d: unknown) => void;
   onDone?: () => void;
@@ -607,7 +625,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 }) =>
+    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 }) =>
       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 }),
@@ -631,6 +649,8 @@ function dispatchSse(frame: string, h: StreamHandlers): void {
   switch (event) {
     case "retrieval_contents": h.onSources?.(data as never); break;
     case "token": h.onToken?.((data as { text: string }).text); break;
+    case "citation": h.onCitation?.(data as Citation); break;
+    case "groundedness": h.onGroundedness?.(data as never); break;
     case "final": h.onFinal?.(data as QueryResponse); break;
     case "error": h.onError?.(data); break;
     case "done": h.onDone?.(); break;