docs(retrieval): mark evidence_text as deprecated and always empty

README.md

@@ -76,8 +76,8 @@ response = client.retrieval.query(
 
 print(response.router_used)
 print(response.answer_text)
-print(response.evidence)  # composed parts to consume
-print(response.evidence_text)
+print(response.evidence)  # grouped [E n] parts to consume
+print(response.evidence_text)  # deprecated; always empty. Use evidence.
 print(response.stop_reason)
 print(response.failure_reason)
 

docs/usage.md

@@ -541,8 +541,8 @@ response = client.retrieval.query(
 )
 print(response.answer_text)          # LLM-generated natural-language answer
 print(response.router_used)          # "workflow_single_step", "small_kb_all", etc.
-print(response.evidence)             # composed parts to consume
-print(response.evidence_text)        # text projection of those parts
+print(response.evidence)             # grouped [E n] parts to consume
+print(response.evidence_text)        # deprecated; always empty. Use evidence.
 print(response.stop_reason)          # agentic termination reason, when returned
 print(response.failure_reason)       # no-answer reason, when returned
 for ref in response.referenced_chunks:

src/knowhere/types/retrieval.py

@@ -79,8 +79,8 @@ class RetrievalQueryResponse(BaseModel):
 
     Downstream agents consume:
 
-    - ``evidence``: composed parts (text/HTML and inline images)
-    - ``evidence_text``: text projection of those parts
+    - ``evidence``: grouped ``[E n]`` parts (text/HTML and inline images)
+    - ``evidence_text``: deprecated; always empty. Use ``evidence``.
     - ``results``: raw path chunks for debug
     - ``decision_trace``: per-step navigation decisions (includes stop/failure)
     - ``referenced_chunks``: structured chunk citations for follow-up queries

tests/test_retrieval.py

@@ -32,7 +32,7 @@ def _make_retrieval_response() -> Dict[str, Any]:
                 "data": "abc",
             },
         ],
-        "evidence_text": "Rendered retrieval evidence",
+        "evidence_text": "",
         "stop_reason": "answer_done",
         "failure_reason": "insufficient evidence",
         "decision_trace": [
@@ -157,7 +157,7 @@ def test_query_sends_request_and_returns_results(self, sync_client: Any) -> None
         assert response.results[0].source.section_path == "Policies / Billing / Refunds"
         assert response.answer_text == ("Annual plans may be refunded within 30 days of purchase.")
         assert len(response.referenced_chunks) == 1
-        assert response.evidence_text == "Rendered retrieval evidence"
+        assert response.evidence_text == ""
         assert response.evidence[0].type == "text"
         assert response.evidence[0].text == "Annual plans may be refunded within 30 days."
         assert response.evidence[1].type == "image"
@@ -344,7 +344,7 @@ def test_agentic_response_fields(self, sync_client: Any) -> None:
         assert response.referenced_chunks[0].file_path is None
         assert response.referenced_chunks[0].job_id == "job_123"
         assert response.referenced_chunks[0].asset_url == ("https://example.com/assets/chunk_001")
-        assert response.evidence_text == "Rendered retrieval evidence"
+        assert response.evidence_text == ""
         assert response.evidence[1].media_type == "image/png"
         assert not hasattr(response.results[0], "composed")
         assert response.stop_reason == "answer_done"