knowhere-python-sdk 0.4.0__tar.gz → 0.5.0__tar.gz

knowhere_python_sdk-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.4.0...v0.5.0) (2026-05-15)
+
+
+### Features
+
+* sync SDK with current worker ZIP contract and agentic retrieval API ([ad8db2e](https://github.com/Ontos-AI/knowhere-python-sdk/commit/ad8db2e87c77978928d046c95565e9e60c1b1f4e))
+
 ## [0.4.0](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.3.2...v0.4.0) (2026-04-27)
 
 

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowhere-python-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: Official Python SDK for the Knowhere document parsing API
 Project-URL: Homepage, https://knowhereto.ai
 Project-URL: Documentation, https://docs.knowhereto.ai

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/docs/usage.md

@@ -1,5 +1,9 @@
 # Knowhere Python SDK — Usage Guide
 
+> **Recent changes:** Chunk metadata fields (`tokens`, `keywords`, `summary`,
+> `length`, etc.) are no longer flattened to the chunk surface. Access them
+> through `chunk.metadata` instead. See [Chunk Types](#chunk-types).
+
 Comprehensive reference for every feature, parameter, and pattern in the SDK.
 
 ## Table of Contents
@@ -219,8 +223,13 @@ result.table_chunks               # List[TableChunk]
 # Lookup by ID
 chunk = result.getChunk("chunk_42")
 
-# Hierarchy data (document structure tree, if available)
-result.hierarchy
+# Document navigation tree (from doc_nav.json, current worker output)
+result.doc_nav                # DocNav | None
+result.doc_nav.sections       # List[DocNavSection] — tree of titles/paths/levels
+result.doc_nav.resources      # DocNavResources — image/table resource summaries
+
+# Legacy hierarchy (from hierarchy.json, older worker output)
+result.hierarchy              # Any | None
 
 # Raw ZIP bytes (for archival)
 result.raw_zip
@@ -239,49 +248,48 @@ result.save("./output/report/")
 
 ## Chunk Types
 
-Every chunk shares a base set of fields (`chunk_id`, `type`, `content`, `path`). Each type adds its own fields.
+Every chunk shares a base set of fields (`chunk_id`, `type`, `content`, `path`,
+`metadata`). Worker metadata is kept in the `metadata` dict — it is **not**
+flattened to top-level chunk properties.
 
-### TextChunk
+### Base fields (all chunk types)
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `chunk_id` | `str` | Unique identifier |
-| `type` | `str` | Always `"text"` |
-| `content` | `str` | The text content |
-| `path` | `str \| None` | Document structure path (e.g. `"Section 1 > Subsection 2"`) |
-| `length` | `int` | Character count |
-| `tokens` | `List[str] \| None` | Tokenized words returned by the parser pipeline |
-| `keywords` | `List[str] \| None` | Extracted keywords (requires `summary_txt: True`) |
-| `summary` | `str \| None` | AI-generated summary (requires `summary_txt: True`) |
-| `relationships` | `List \| None` | Relationships to other chunks |
+| `type` | `str` | `"text"`, `"image"`, or `"table"` |
+| `content` | `str` | Text content or placeholder |
+| `path` | `str \| None` | Document structure path |
+| `metadata` | `dict` | Raw worker metadata (tokens, keywords, summary, length, page_nums, etc.) |
+
+### TextChunk
 
 ```python
 for chunk in result.text_chunks:
     print(f"[{chunk.chunk_id}] {chunk.content[:60]}...")
-    if chunk.keywords:
-        print(f"  Keywords: {', '.join(chunk.keywords)}")
-    if chunk.summary:
-        print(f"  Summary: {chunk.summary}")
+    # Metadata is in chunk.metadata, not flattened:
+    keywords = chunk.metadata.get("keywords", [])
+    summary = chunk.metadata.get("summary")
+    if keywords:
+        print(f"  Keywords: {', '.join(keywords)}")
+    if summary:
+        print(f"  Summary: {summary}")
 ```
 
 ### ImageChunk
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `chunk_id` | `str` | Unique identifier |
-| `type` | `str` | Always `"image"` |
-| `content` | `str` | Text content associated with the image |
 | `file_path` | `str \| None` | Path within the ZIP |
-| `original_name` | `str \| None` | Original filename |
-| `summary` | `str \| None` | AI-generated image description (requires `summary_image: True`) |
 | `data` | `bytes` | Raw image bytes (loaded from ZIP) |
 | `format` | `str \| None` | Image format inferred from extension (property) |
 
 ```python
 for img in result.image_chunks:
     print(f"{img.file_path} ({len(img.data)} bytes, {img.format})")
-    if img.summary:
-        print(f"  Description: {img.summary}")
+    summary = img.metadata.get("summary")
+    if summary:
+        print(f"  Description: {summary}")
     img.save("./output/images/")  # writes to disk
 ```
 
@@ -289,13 +297,7 @@ for img in result.image_chunks:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `chunk_id` | `str` | Unique identifier |
-| `type` | `str` | Always `"table"` |
-| `content` | `str` | Text representation of the table |
 | `file_path` | `str \| None` | Path within the ZIP |
-| `original_name` | `str \| None` | Original filename |
-| `table_type` | `str \| None` | Table classification |
-| `summary` | `str \| None` | AI-generated table summary (requires `summary_table: True`) |
 | `html` | `str` | Full HTML of the table (loaded from ZIP) |
 
 ```python
@@ -471,6 +473,19 @@ response = client.retrieval.query(
     top_k=5,
 )
 
+# Agentic mode (LLM navigation + answer synthesis)
+response = client.retrieval.query(
+    namespace="support-center",
+    query="How do I pair a Bluetooth headset?",
+    use_agentic=True,
+    top_k=5,
+)
+print(response.answer_text)          # LLM-generated natural-language answer
+print(response.router_used)          # "workflow_single_step", "small_kb_all", etc.
+for ref in response.referenced_chunks:
+    print(ref.get("chunk_id"), ref.get("asset_url"))
+
+# Legacy results are always available
 for result in response.results:
     print(result.content)
     print(result.score)
@@ -479,6 +494,10 @@ for result in response.results:
     print(result.source.section_path)
 ```
 
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `use_agentic` | `bool \| None` | `None` | Force agentic (`True`) or legacy (`False`) retrieval. `None` uses server default. |
+
 Retrieval results expose `content`, not the older parse-result `text` field.
 Media results may include `asset_url` when the server can sign the referenced
 artifact.

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "knowhere-python-sdk"
-version = "0.4.0"
+version = "0.5.0"
 description = "Official Python SDK for the Knowhere document parsing API"
 readme = "README.md"
 license = "MIT"

knowhere_python_sdk-0.5.0/src/knowhere/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"  # x-release-please-version

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/src/knowhere/lib/result_parser.py

@@ -13,13 +13,13 @@ from knowhere._exceptions import ChecksumError, KnowhereError
 from knowhere._logging import getLogger
 from knowhere.types.result import (
     Chunk,
+    DocNav,
     ImageChunk,
     Manifest,
     ParseResult,
     SlimChunk,
     TableChunk,
     TextChunk,
-    TextChunkTokens,
 )
 
 _logger = getLogger()
@@ -81,38 +81,6 @@ def _extractFilePath(raw: Dict[str, Any]) -> Optional[str]:
     return fallback
 
 
-def _normalizeTokenList(raw_tokens: List[Any]) -> List[str]:
-    """Return a string-only token list with empty values removed."""
-    normalized_tokens: List[str] = []
-    for raw_token in raw_tokens:
-        token_text: str = str(raw_token).strip()
-        if token_text:
-            normalized_tokens.append(token_text)
-    return normalized_tokens
-
-
-def _parseTextChunkTokens(
-    raw_tokens: Any,
-    *,
-    chunk_id: str,
-) -> Optional[TextChunkTokens]:
-    """Normalize text chunk tokens from the current backend payload."""
-    if raw_tokens is None:
-        return None
-    if isinstance(raw_tokens, bool):
-        raise KnowhereError(
-            f"Invalid tokens payload for text chunk '{chunk_id}': expected list[str], got bool."
-        )
-    if isinstance(raw_tokens, list):
-        return _normalizeTokenList(raw_tokens)
-
-    raise KnowhereError(
-        "Invalid tokens payload for text chunk "
-        f"'{chunk_id}': expected list[str], "
-        f"got {type(raw_tokens).__name__}."
-    )
-
-
 def _buildChunks(
     raw_chunks: List[Dict[str, Any]],
     zf: zipfile.ZipFile,
@@ -125,58 +93,39 @@ def _buildChunks(
 
         if chunk_type == "image":
             image_data: bytes = b""
-            # file_path may be at top level, inside metadata, or use path as fallback
             file_path: Optional[str] = _extractFilePath(raw)
             if file_path:
                 image_data = _readZipBytes(zf, file_path) or b""
-            metadata: Dict[str, Any] = raw.get("metadata", {})
             chunk: Chunk = ImageChunk(
                 chunk_id=raw.get("chunk_id", ""),
                 type="image",
                 content=raw.get("content", ""),
                 path=raw.get("path"),
-                page_nums=metadata.get("page_nums", raw.get("page_nums")),
-                length=metadata.get("length", raw.get("length", 0)),
                 file_path=file_path,
-                original_name=metadata.get("original_name", raw.get("original_name")),
-                summary=metadata.get("summary", raw.get("summary")),
                 data=image_data,
+                metadata=raw.get("metadata", {}),
             )
         elif chunk_type == "table":
             table_html: str = ""
             file_path = _extractFilePath(raw)
             if file_path:
                 table_html = _readZipText(zf, file_path) or ""
-            metadata = raw.get("metadata", {})
             chunk = TableChunk(
                 chunk_id=raw.get("chunk_id", ""),
                 type="table",
                 content=raw.get("content", ""),
                 path=raw.get("path"),
-                page_nums=metadata.get("page_nums", raw.get("page_nums")),
-                length=metadata.get("length", raw.get("length", 0)),
                 file_path=file_path,
-                original_name=metadata.get("original_name", raw.get("original_name")),
-                table_type=metadata.get("table_type", raw.get("table_type")),
-                summary=metadata.get("summary", raw.get("summary")),
                 html=table_html,
+                metadata=raw.get("metadata", {}),
             )
         else:
-            metadata = raw.get("metadata", {})
-            chunk_id: str = raw.get("chunk_id", "")
-            raw_tokens: Any = metadata.get("tokens", raw.get("tokens"))
             chunk = TextChunk(
-                chunk_id=chunk_id,
+                chunk_id=raw.get("chunk_id", ""),
                 type="text",
                 content=raw.get("content", ""),
                 path=raw.get("path"),
-                page_nums=metadata.get("page_nums", raw.get("page_nums")),
-                length=metadata.get("length", raw.get("length", 0)),
-                tokens=_parseTextChunkTokens(raw_tokens, chunk_id=chunk_id),
-                keywords=metadata.get("keywords", raw.get("keywords")),
-                summary=metadata.get("summary", raw.get("summary")),
-                connect_to=metadata.get("connect_to", raw.get("connect_to")),
-                relationships=metadata.get("relationships", raw.get("relationships")),
+                metadata=raw.get("metadata", {}),
             )
 
         chunks.append(chunk)
@@ -229,7 +178,15 @@ def parseResultZip(
     # -- Full markdown --
     full_markdown: str = _readZipText(zf, "full.md") or ""
 
-    # -- Hierarchy --
+    # -- DocNav (current worker output) --
+    doc_nav_text: Optional[str] = _readZipText(zf, "doc_nav.json")
+    doc_nav: Optional[DocNav] = (
+        DocNav.model_validate(json.loads(doc_nav_text))
+        if doc_nav_text
+        else None
+    )
+
+    # -- Hierarchy (legacy — current worker no longer emits this) --
     hierarchy_text: Optional[str] = _readZipText(zf, "hierarchy.json")
     hierarchy: Optional[Any] = (
         json.loads(hierarchy_text) if hierarchy_text else None
@@ -263,11 +220,13 @@ def parseResultZip(
     return ParseResult(
         manifest=manifest,
         chunks=chunks,
-        chunks_slim=chunks_slim,
         full_markdown=full_markdown,
+        raw_zip=zip_bytes,
+        doc_nav=doc_nav,
+        # Legacy — the current worker no longer emits these files
+        chunks_slim=chunks_slim,
         hierarchy=hierarchy,
         toc_hierarchies=toc_hierarchies,
         kb_csv=kb_csv,
         hierarchy_view_html=hierarchy_view_html,
-        raw_zip=zip_bytes,
     )

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/src/knowhere/resources/retrieval.py

@@ -22,6 +22,7 @@ class Retrieval(SyncAPIResource):
         query: str,
         namespace: Optional[str] = None,
         top_k: Optional[int] = None,
+        use_agentic: Optional[bool] = None,
         data_type: Optional[int] = None,
         signal_paths: Optional[list[str]] = None,
         filter_mode: Optional[RetrievalFilterMode] = None,
@@ -39,6 +40,8 @@ class Retrieval(SyncAPIResource):
             body["namespace"] = namespace
         if top_k is not None:
             body["top_k"] = top_k
+        if use_agentic is not None:
+            body["use_agentic"] = use_agentic
         if data_type is not None:
             body["data_type"] = data_type
         if signal_paths is not None:
@@ -77,6 +80,7 @@ class AsyncRetrieval(AsyncAPIResource):
         query: str,
         namespace: Optional[str] = None,
         top_k: Optional[int] = None,
+        use_agentic: Optional[bool] = None,
         data_type: Optional[int] = None,
         signal_paths: Optional[list[str]] = None,
         filter_mode: Optional[RetrievalFilterMode] = None,
@@ -94,6 +98,8 @@ class AsyncRetrieval(AsyncAPIResource):
             body["namespace"] = namespace
         if top_k is not None:
             body["top_k"] = top_k
+        if use_agentic is not None:
+            body["use_agentic"] = use_agentic
         if data_type is not None:
             body["data_type"] = data_type
         if signal_paths is not None:

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/src/knowhere/types/result.py

@@ -9,7 +9,6 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel, Field
-from typing_extensions import TypeAlias
 
 from knowhere._exceptions import ValidationError
 
@@ -138,6 +137,44 @@ class Manifest(BaseModel):
     checksum: Optional[Checksum] = None
     statistics: Optional[Statistics] = None
     files: Optional[FileIndex] = None
+    hierarchy: Optional[Any] = Field(default=None, alias="HIERARCHY")
+
+
+# ---------------------------------------------------------------------------
+# DocNav models
+# ---------------------------------------------------------------------------
+
+
+class DocNavResourceItem(BaseModel):
+    """A single image or table resource entry in ``doc_nav.json``."""
+
+    path: str
+    summary: Optional[str] = None
+
+
+class DocNavResources(BaseModel):
+    """Image and table resource summaries from ``doc_nav.json``."""
+
+    images: List[DocNavResourceItem] = Field(default_factory=list)
+    tables: List[DocNavResourceItem] = Field(default_factory=list)
+
+
+class DocNavSection(BaseModel):
+    """A document section entry in the ``doc_nav.json`` navigation tree."""
+
+    title: str
+    path: str
+    level: int
+    summary: Optional[str] = None
+    chunk_count: int = 0
+    children: List["DocNavSection"] = Field(default_factory=list)
+
+
+class DocNav(BaseModel):
+    """Top-level document navigation structure from ``doc_nav.json``."""
+
+    sections: List[DocNavSection] = Field(default_factory=list)
+    resources: Optional[DocNavResources] = None
 
 
 # ---------------------------------------------------------------------------
@@ -145,6 +182,27 @@ class Manifest(BaseModel):
 # ---------------------------------------------------------------------------
 
 
+class ChunkMetadata(BaseModel):
+    """Known worker metadata fields for a chunk.
+
+    All fields are optional.  Unknown fields added by future worker
+    versions are preserved thanks to ``model_config``.
+    """
+
+    model_config = {"extra": "allow"}
+
+    length: Optional[int] = None
+    page_nums: Optional[List[int]] = None
+    tokens: Optional[List[str]] = None
+    keywords: Optional[List[str]] = None
+    summary: Optional[str] = None
+    connect_to: Optional[List[Dict[str, Any]]] = None
+    file_path: Optional[str] = None
+    original_name: Optional[str] = None
+    table_type: Optional[str] = None
+    document_top_summary: Optional[str] = None
+
+
 class BaseChunk(BaseModel):
     """Fields shared by every chunk type."""
 
@@ -152,32 +210,20 @@ class BaseChunk(BaseModel):
     type: str
     content: str = ""
     path: Optional[str] = None
-    page_nums: Optional[List[int]] = None
-
-
-TextChunkTokens: TypeAlias = List[str]
+    metadata: ChunkMetadata = Field(default_factory=ChunkMetadata)
 
 
 class TextChunk(BaseChunk):
     """A text chunk extracted from the document."""
 
     type: str = "text"
-    length: int = 0
-    tokens: Optional[TextChunkTokens] = None
-    keywords: Optional[List[str]] = None
-    summary: Optional[str] = None
-    connect_to: Optional[List[Dict[str, Any]]] = None
-    relationships: Optional[List[Union[Dict[str, Any], str]]] = None
 
 
 class ImageChunk(BaseChunk):
     """An image chunk — carries raw bytes loaded from the ZIP."""
 
     type: str = "image"
-    length: int = 0
     file_path: Optional[str] = None
-    original_name: Optional[str] = None
-    summary: Optional[str] = None
     data: bytes = Field(default=b"", exclude=True)
 
     model_config = {"arbitrary_types_allowed": True}
@@ -193,13 +239,13 @@ class ImageChunk(BaseChunk):
     def save(self, directory: Union[str, Path]) -> Path:
         """Write the image bytes to *directory*, returning the output path.
 
-        The filename is derived from ``original_name`` or ``file_path``,
-        sanitised for cross-platform safety.
+        The filename is derived from ``file_path``, sanitised for
+        cross-platform safety.
         """
         dir_path: Path = Path(directory)
         dir_path.mkdir(parents=True, exist_ok=True)
 
-        raw_name: str = self.original_name or os.path.basename(
+        raw_name: str = os.path.basename(
             self.file_path or f"{self.chunk_id}.bin"
         )
         safe_name: str = _sanitizeFilename(raw_name)
@@ -214,11 +260,7 @@ class TableChunk(BaseChunk):
     """A table chunk — carries HTML loaded from the ZIP."""
 
     type: str = "table"
-    length: int = 0
     file_path: Optional[str] = None
-    original_name: Optional[str] = None
-    table_type: Optional[str] = None
-    summary: Optional[str] = None
     html: str = Field(default="", exclude=True)
 
     def save(self, directory: Union[str, Path]) -> Path:
@@ -226,7 +268,7 @@ class TableChunk(BaseChunk):
         dir_path: Path = Path(directory)
         dir_path.mkdir(parents=True, exist_ok=True)
 
-        raw_name: str = self.original_name or os.path.basename(
+        raw_name: str = os.path.basename(
             self.file_path or f"{self.chunk_id}.html"
         )
         safe_name: str = _sanitizeFilename(raw_name)
@@ -242,12 +284,11 @@ Chunk = Union[TextChunk, ImageChunk, TableChunk]
 
 
 class SlimChunk(BaseModel):
-    """Minimal chunk entry emitted in chunks_slim.json."""
+    """Minimal chunk entry emitted in chunks_slim.json (legacy)."""
 
     type: str
     path: Optional[str] = None
     content: str = ""
-    summary: Optional[str] = None
 
 
 # ---------------------------------------------------------------------------
@@ -259,48 +300,59 @@ class ParseResult:
     """Eagerly-loaded result of a document parsing job.
 
     Contains the manifest, all chunks (with image bytes and table HTML
-    already loaded), the full markdown, hierarchy data, and the raw ZIP
-    bytes for archival purposes.
+    already loaded), the full markdown, the document navigation tree,
+    and the raw ZIP bytes for archival purposes.
+
+    Legacy fields (``chunks_slim``, ``hierarchy``, ``toc_hierarchies``,
+    ``kb_csv``, ``hierarchy_view_html``) are kept for backward
+    compatibility with older result ZIPs.  The current worker does not
+    emit ``chunks_slim.json`` or ``hierarchy.json``.
     """
 
     manifest: Manifest
     chunks: List[Chunk]
-    chunks_slim: Optional[List[SlimChunk]]
     full_markdown: str
+    raw_zip: bytes
+    namespace: Optional[str]
+    document_id: Optional[str]
+    # Current worker output
+    doc_nav: Optional[DocNav]
+    # Legacy — the current worker no longer emits these files
+    chunks_slim: Optional[List[SlimChunk]]
     hierarchy: Optional[Any]
     toc_hierarchies: Optional[Any]
     kb_csv: Optional[str]
     hierarchy_view_html: Optional[str]
-    raw_zip: bytes
-    namespace: Optional[str]
-    document_id: Optional[str]
 
     def __init__(
         self,
         *,
         manifest: Manifest,
         chunks: List[Chunk],
-        chunks_slim: Optional[List[SlimChunk]],
         full_markdown: str,
-        hierarchy: Optional[Any],
-        toc_hierarchies: Optional[Any],
-        kb_csv: Optional[str],
-        hierarchy_view_html: Optional[str],
         raw_zip: bytes,
+        doc_nav: Optional[DocNav] = None,
         namespace: Optional[str] = None,
         document_id: Optional[str] = None,
+        # Legacy — the current worker no longer emits these files
+        chunks_slim: Optional[List[SlimChunk]] = None,
+        hierarchy: Optional[Any] = None,
+        toc_hierarchies: Optional[Any] = None,
+        kb_csv: Optional[str] = None,
+        hierarchy_view_html: Optional[str] = None,
     ) -> None:
         self.manifest = manifest
         self.chunks = chunks
-        self.chunks_slim = chunks_slim
         self.full_markdown = full_markdown
+        self.raw_zip = raw_zip
+        self.doc_nav = doc_nav
+        self.namespace = namespace
+        self.document_id = document_id
+        self.chunks_slim = chunks_slim
         self.hierarchy = hierarchy
         self.toc_hierarchies = toc_hierarchies
         self.kb_csv = kb_csv
         self.hierarchy_view_html = hierarchy_view_html
-        self.raw_zip = raw_zip
-        self.namespace = namespace
-        self.document_id = document_id
 
     # -- convenience properties --
 
@@ -344,11 +396,17 @@ class ParseResult:
         """Save the full result to *directory*.
 
         Creates the directory if needed and writes:
+        * ``manifest.json`` — result manifest
+        * ``chunks.json`` — all chunks
+        * ``doc_nav.json`` — document navigation tree (if present)
         * ``full.md`` — the full markdown
         * ``images/`` — all image chunks
         * ``tables/`` — all table chunks
         * ``result.zip`` — the raw ZIP archive
 
+        Legacy files (``chunks_slim.json``, ``hierarchy.json``, etc.) are
+        also written when present for backward compatibility.
+
         Returns the resolved directory path.
         """
         dir_path: Path = Path(directory)
@@ -357,7 +415,7 @@ class ParseResult:
         # Manifest / chunks
         manifest_path: Path = dir_path / "manifest.json"
         manifest_path.write_text(
-            self.manifest.model_dump_json(indent=2),
+            self.manifest.model_dump_json(indent=2, by_alias=True),
             encoding="utf-8",
         )
 
@@ -367,6 +425,13 @@ class ParseResult:
             encoding="utf-8",
         )
 
+        if self.doc_nav is not None:
+            doc_nav_path: Path = dir_path / "doc_nav.json"
+            doc_nav_path.write_text(
+                self.doc_nav.model_dump_json(indent=2),
+                encoding="utf-8",
+            )
+
         if self.chunks_slim is not None:
             chunks_slim_path: Path = dir_path / "chunks_slim.json"
             chunks_slim_path.write_text(

{knowhere_python_sdk-0.4.0 → knowhere_python_sdk-0.5.0}/src/knowhere/types/retrieval.py

@@ -2,9 +2,9 @@
 
 from __future__ import annotations
 
-from typing import Literal, Optional, TypedDict
+from typing import Any, Dict, List, Literal, Optional, TypedDict
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 RetrievalChannel = Literal["path", "content", "term"]
@@ -37,9 +37,16 @@ class RetrievalResult(BaseModel):
 
 
 class RetrievalQueryResponse(BaseModel):
-    """Response from ``POST /v1/retrieval/query``."""
+    """Response from ``POST /v1/retrieval/query``.
+
+    Agentic fields (``answer_text``, ``referenced_chunks``) are only
+    populated when ``use_agentic=True``.  In legacy retrieval mode they
+    default to ``None`` and ``[]`` respectively.
+    """
 
     namespace: str
     query: str
     router_used: Optional[str] = None
+    answer_text: Optional[str] = None
+    referenced_chunks: List[Dict[str, Any]] = Field(default_factory=list)
     results: list[RetrievalResult]