@babav/knowledge-core-client 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -75,18 +75,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;
@@ -246,6 +261,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;

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.9.0",
+  "version": "0.11.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

@@ -88,18 +88,32 @@ 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.
+  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 {
@@ -381,6 +395,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;
@@ -627,6 +647,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;