fix(types): make RetrievalResult.score Optional[float] to match API null return (#27)

* feat: add optional decision_trace field to RetrievalQueryResponse and update tests

* fix(types): make RetrievalResult.score Optional[float] to match API null return

The agentic retrieval route now returns null for score when no real
score is available (navigation-only chunks). Previously the SDK model
declared score as float which would fail Pydantic validation on null.

score: float → Optional[float] = None

Author: EricNGOntos

src/knowhere/types/retrieval.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Literal, Optional, TypedDict
+from typing import Any, Literal, Optional, TypedDict
 
 from pydantic import BaseModel, Field
 
@@ -31,7 +31,7 @@ class RetrievalResult(BaseModel):
 
     chunk_type: str
     content: str
-    score: float
+    score: Optional[float] = None
     asset_url: Optional[str] = None
     source: RetrievalSource
 
@@ -51,8 +51,11 @@ class RetrievalReferencedChunk(BaseModel):
 class RetrievalQueryResponse(BaseModel):
     """Response from ``POST /v1/retrieval/query``.
 
-    Agentic retrieval may also include ``evidence_text``, ``stop_reason``,
-    and ``failure_reason`` when the server returns workflow diagnostics.
+    Three PRIMARY output fields for downstream agent consumption:
+
+    - ``evidence_text``: hierarchical evidence tree for LLM context
+    - ``decision_trace``: per-step navigation decisions (includes stop/failure)
+    - ``referenced_chunks``: structured chunk citations for follow-up queries
     """
 
     namespace: str
@@ -64,3 +67,4 @@ class RetrievalQueryResponse(BaseModel):
     stop_reason: Optional[str] = None
     failure_reason: Optional[str] = None
     results: list[RetrievalResult]
+    decision_trace: Optional[list[dict[str, Any]]] = None

tests/test_retrieval.py

@@ -24,6 +24,10 @@ def _make_retrieval_response() -> Dict[str, Any]:
         "evidence_text": "Rendered retrieval evidence",
         "stop_reason": "answer_done",
         "failure_reason": "insufficient evidence",
+        "decision_trace": [
+            {"phase": "discovery", "action": "select_documents", "selected": ["doc_123"]},
+            {"phase": "terminal", "action": "complete", "stop_reason": "answer_done", "failure_reason": "insufficient evidence"},
+        ],
         "referenced_chunks": [
             {
                 "chunk_id": "chunk_001",
@@ -228,6 +232,10 @@ def test_agentic_response_fields(self, sync_client: Any) -> None:
         assert response.evidence_text == "Rendered retrieval evidence"
         assert response.stop_reason == "answer_done"
         assert response.failure_reason == "insufficient evidence"
+        assert response.decision_trace is not None
+        assert len(response.decision_trace) == 2
+        assert response.decision_trace[0]["phase"] == "discovery"
+        assert response.decision_trace[-1]["phase"] == "terminal"
 
     @respx.mock
     def test_legacy_response_without_agentic_fields(self, sync_client: Any) -> None:
@@ -242,3 +250,4 @@ def test_legacy_response_without_agentic_fields(self, sync_client: Any) -> None:
 
         assert response.answer_text is None
         assert response.referenced_chunks == []
+        assert response.decision_trace is None