Merge pull request #85 from Ontos-AI/fix/wangbinqi/retrieval-response-contract

fix: sync retrieval response SDK contract

Author: suguanYang

.changeset/sync-retrieval-response.md

@@ -0,0 +1,5 @@
+---
+"@ontos-ai/knowhere-sdk": patch
+---
+
+Sync retrieval response types with the current API contract, including evidence text, stop/failure reasons, and typed referenced chunks.

README.md

@@ -198,6 +198,9 @@ const response = await client.retrieval.query({
 
 console.log(response.answerText);         // LLM-generated answer
 console.log(response.referencedChunks);   // cited evidence chunks
+console.log(response.evidenceText);       // rendered evidence context, when returned
+console.log(response.stopReason);         // agentic termination reason, when returned
+console.log(response.failureReason);      // no-answer reason, when returned
 
 for (const result of response.results) {
   console.log(result.content);
@@ -218,6 +221,20 @@ result.source.sourceFileName;
 result.source.sectionPath;
 ```
 
+Agentic references expose the current retrieval citation fields:
+
+```typescript
+const reference = response.referencedChunks[0];
+
+reference.chunkId;
+reference.documentId;
+reference.chunkType;
+reference.sectionPath;
+reference.filePath;
+reference.jobId;
+reference.assetUrl;
+```
+
 Use `documentId` to update or archive a document:
 
 ```typescript

src/index.ts

@@ -30,6 +30,7 @@ export type {
   RetrievalQueryParams,
   RetrievalSource,
   RetrievalResult,
+  RetrievalReferencedChunk,
   RetrievalQueryResponse,
   // Parameter types
   ParsingParams,

src/resources/__tests__/retrieval.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { Retrieval } from '../retrieval.js';
 import type { HttpClient } from '../../lib/http-client.js';
+import type { RetrievalQueryResponse, RetrievalReferencedChunk } from '../../types/retrieval.js';
 
 describe('Retrieval Resource', () => {
   let retrieval: Retrieval;
@@ -20,6 +21,8 @@ describe('Retrieval Resource', () => {
       namespace: 'support-center',
       query: 'refund policy',
       routerUsed: 'discovery+agent',
+      answerText: null,
+      referencedChunks: [],
       results: [
         {
           content: 'Annual plans may be refunded within 30 days.',
@@ -95,6 +98,9 @@ describe('Retrieval Resource', () => {
     mockHttpClient.post.mockResolvedValue({
       namespace: 'default',
       query: 'refund policy',
+      routerUsed: 'small_corpus_all',
+      answerText: null,
+      referencedChunks: [],
       results: [],
     });
 
@@ -111,7 +117,17 @@ describe('Retrieval Resource', () => {
       query: 'test',
       routerUsed: 'workflow_single_step',
       answerText: 'Generated answer',
-      referencedChunks: [{ chunkId: 'chunk-1', assetUrl: 'https://example.com' }],
+      referencedChunks: [
+        {
+          chunkId: 'chunk-1',
+          documentId: 'doc-1',
+          chunkType: 'image',
+          sectionPath: 'Images',
+          filePath: 'images/chunk-1.png',
+          jobId: 'job-1',
+          assetUrl: 'https://example.com',
+        },
+      ],
       results: [],
     });
 
@@ -129,30 +145,50 @@ describe('Retrieval Resource', () => {
       query: 'test',
       routerUsed: 'workflow_single_step',
       answerText: 'LLM-generated answer',
+      evidenceText: 'Rendered retrieval evidence',
+      stopReason: 'answer_done',
+      failureReason: 'insufficient evidence',
       referencedChunks: [
-        { chunkId: 'chunk-1', documentId: 'doc-1', assetUrl: 'https://example.com/1' },
+        {
+          chunkId: 'chunk-1',
+          documentId: 'doc-1',
+          chunkType: 'text',
+          sectionPath: 'Root',
+          filePath: null,
+          jobId: 'job-1',
+          assetUrl: 'https://example.com/1',
+        },
       ],
       results: [],
     });
 
     const response = await retrieval.query({ query: 'test', useAgentic: true });
+    const typedResponse: RetrievalQueryResponse = response;
+    const referencedChunk: RetrievalReferencedChunk | undefined = response.referencedChunks[0];
 
-    expect(response.answerText).toBe('LLM-generated answer');
+    expect(typedResponse.answerText).toBe('LLM-generated answer');
+    expect(response.evidenceText).toBe('Rendered retrieval evidence');
+    expect(response.stopReason).toBe('answer_done');
+    expect(response.failureReason).toBe('insufficient evidence');
     expect(response.referencedChunks).toHaveLength(1);
-    expect(response.referencedChunks?.[0]?.chunkId).toBe('chunk-1');
+    expect(referencedChunk?.chunkId).toBe('chunk-1');
+    expect(referencedChunk?.filePath).toBeNull();
   });
 
   it('should handle legacy response without agentic fields', async () => {
     mockHttpClient.post.mockResolvedValue({
       namespace: 'default',
       query: 'refund policy',
+      routerUsed: 'small_corpus_all',
+      answerText: null,
+      referencedChunks: [],
       results: [],
     });
 
     const response = await retrieval.query({ query: 'refund policy' });
 
-    expect(response.answerText).toBeUndefined();
-    expect(response.referencedChunks).toBeUndefined();
+    expect(response.answerText).toBeNull();
+    expect(response.referencedChunks).toEqual([]);
     expect(response.results).toEqual([]);
   });
 

src/types/retrieval.ts

@@ -63,11 +63,11 @@ export interface RetrievalQueryParams {
  */
 export interface RetrievalSource {
   /** Stable document identifier */
-  documentId?: string;
+  documentId?: string | null;
   /** Original source file name */
-  sourceFileName?: string;
+  sourceFileName?: string | null;
   /** Human-readable section path */
-  sectionPath?: string;
+  sectionPath?: string | null;
 }
 
 /**
@@ -86,6 +86,26 @@ export interface RetrievalResult {
   source: RetrievalSource;
 }
 
+/**
+ * Cited evidence chunk returned by agentic retrieval.
+ */
+export interface RetrievalReferencedChunk {
+  /** Parser-provided chunk identifier */
+  chunkId: string;
+  /** Stable document identifier */
+  documentId: string;
+  /** Chunk type, for example text, image, or table */
+  chunkType: string;
+  /** Human-readable section path */
+  sectionPath: string;
+  /** Generated artifact file path for media chunks */
+  filePath?: string | null;
+  /** Published job identifier for the referenced chunk */
+  jobId?: string | null;
+  /** Presigned asset URL for media chunks when available */
+  assetUrl?: string | null;
+}
+
 /**
  * Response from POST /v1/retrieval/query.
  */
@@ -95,11 +115,17 @@ export interface RetrievalQueryResponse {
   /** Echoed query text */
   query: string;
   /** Retrieval router path used by the API for this query */
-  routerUsed?: string;
-  /** LLM-generated natural-language answer (agentic mode only) */
-  answerText?: string | null;
-  /** Cited evidence chunks with asset URLs (agentic mode only) */
-  referencedChunks?: Array<Record<string, unknown>> | null;
+  routerUsed: string;
+  /** LLM-generated natural-language answer, or null when no answer was produced */
+  answerText: string | null;
+  /** Cited evidence chunks with asset URLs when available */
+  referencedChunks: RetrievalReferencedChunk[];
+  /** Rendered evidence context used by agentic answer synthesis */
+  evidenceText?: string;
+  /** Agentic termination reason when provided by the API */
+  stopReason?: string;
+  /** Semantic failure reason when no answer could be produced */
+  failureReason?: string;
   /** Ranked retrieval results */
   results: RetrievalResult[];
 }