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

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

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

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

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.4.0](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.3.2...v0.4.0) (2026-04-27)
+
+
+### Features
+
+* add document chunks resource methods ([73094d4](https://github.com/Ontos-AI/knowhere-python-sdk/commit/73094d4f95ef693785fa3965f6f2a223dfd2a350))
+
 ## [0.3.2](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.3.1...v0.3.2) (2026-04-23)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowhere-python-sdk
-Version: 0.3.2
+Version: 0.4.0
 Summary: Official Python SDK for the Knowhere document parsing API
 Project-URL: Homepage, https://knowhereto.ai
 Project-URL: Documentation, https://docs.knowhereto.ai
@@ -118,6 +118,21 @@ update_job = client.jobs.create(
 document = client.documents.get(document_id)
 print(document.status)
 
+chunks = client.documents.list_chunks(
+    document_id,
+    page=1,
+    page_size=50,
+    chunk_type="text",
+)
+print(chunks.pagination.total)
+if chunks.chunks:
+    chunk = client.documents.get_chunk(
+        document_id,
+        chunks.chunks[0].id,
+        include_asset_urls=True,
+    )
+    print(chunk.chunk.content)
+
 client.documents.archive(document_id)
 ```
 

{knowhere_python_sdk-0.3.2 → knowhere_python_sdk-0.4.0}/README.md

@@ -85,6 +85,21 @@ update_job = client.jobs.create(
 document = client.documents.get(document_id)
 print(document.status)
 
+chunks = client.documents.list_chunks(
+    document_id,
+    page=1,
+    page_size=50,
+    chunk_type="text",
+)
+print(chunks.pagination.total)
+if chunks.chunks:
+    chunk = client.documents.get_chunk(
+        document_id,
+        chunks.chunks[0].id,
+        include_asset_urls=True,
+    )
+    print(chunk.chunk.content)
+
 client.documents.archive(document_id)
 ```
 

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

@@ -521,6 +521,22 @@ for document in document_list.documents:
 document = client.documents.get("doc_123")
 print(document.current_job_result_id)
 
+chunks = client.documents.list_chunks(
+    "doc_123",
+    page=1,
+    page_size=50,
+    chunk_type="text",
+)
+for chunk in chunks.chunks:
+    print(chunk.id, chunk.content)
+
+image_chunk = client.documents.get_chunk(
+    "doc_123",
+    "dchk_123",
+    include_asset_urls=True,
+)
+print(image_chunk.chunk.asset_url)
+
 archived = client.documents.archive("doc_123")
 print(archived.status)  # "archived"
 ```

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

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

{knowhere_python_sdk-0.3.2 → knowhere_python_sdk-0.4.0}/src/knowhere/__init__.py

@@ -35,7 +35,15 @@ from knowhere._exceptions import (
 )
 from knowhere._types import PollProgressCallback, UploadProgressCallback
 from knowhere._version import __version__
-from knowhere.types.document import Document, DocumentListResponse
+from knowhere.types.document import (
+    Document,
+    DocumentChunk,
+    DocumentChunkListResponse,
+    DocumentChunkPagination,
+    DocumentChunkResponse,
+    DocumentChunkType,
+    DocumentListResponse,
+)
 from knowhere.types.job import Job, JobError, JobProgress, JobResult
 from knowhere.types.params import ParsingParams, WebhookConfig
 from knowhere.types.retrieval import (
@@ -98,6 +106,11 @@ __all__: list[str] = [
     "JobResult",
     # Document types
     "Document",
+    "DocumentChunk",
+    "DocumentChunkListResponse",
+    "DocumentChunkPagination",
+    "DocumentChunkResponse",
+    "DocumentChunkType",
     "DocumentListResponse",
     # Retrieval types
     "RetrievalChannel",

knowhere_python_sdk-0.4.0/src/knowhere/_version.py

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

knowhere_python_sdk-0.4.0/src/knowhere/resources/documents.py

@@ -0,0 +1,191 @@
+"""Documents resource for canonical document lifecycle operations."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from knowhere.resources._base import AsyncAPIResource, SyncAPIResource
+from knowhere.types.document import (
+    Document,
+    DocumentChunkListResponse,
+    DocumentChunkResponse,
+    DocumentChunkType,
+    DocumentListResponse,
+)
+
+
+class Documents(SyncAPIResource):
+    """Synchronous interface for ``/v1/documents`` endpoints."""
+
+    def list(self, *, namespace: Optional[str] = None) -> DocumentListResponse:
+        """List canonical documents in a namespace."""
+        params: Dict[str, Any] = {}
+        if namespace is not None:
+            params["namespace"] = namespace
+
+        return self._request(
+            "GET",
+            "v1/documents",
+            params=params or None,
+            cast_to=DocumentListResponse,
+        )
+
+    def get(self, document_id: str) -> Document:
+        """Get one canonical document by ID."""
+        return self._request(
+            "GET",
+            f"v1/documents/{document_id}",
+            cast_to=Document,
+        )
+
+    def list_chunks(
+        self,
+        document_id: str,
+        *,
+        page: int = 1,
+        page_size: int = 50,
+        chunk_type: Optional[DocumentChunkType] = None,
+        include_asset_urls: bool = False,
+    ) -> DocumentChunkListResponse:
+        """List current-revision chunks for one canonical document."""
+        params: Dict[str, Any] = _build_chunk_list_params(
+            page=page,
+            page_size=page_size,
+            chunk_type=chunk_type,
+            include_asset_urls=include_asset_urls,
+        )
+
+        return self._request(
+            "GET",
+            f"v1/documents/{document_id}/chunks",
+            params=params or None,
+            cast_to=DocumentChunkListResponse,
+        )
+
+    def get_chunk(
+        self,
+        document_id: str,
+        document_chunk_id: str,
+        *,
+        include_asset_urls: bool = False,
+    ) -> DocumentChunkResponse:
+        """Get one current-revision chunk for one canonical document."""
+        params: Dict[str, Any] = _build_chunk_get_params(
+            include_asset_urls=include_asset_urls,
+        )
+
+        return self._request(
+            "GET",
+            f"v1/documents/{document_id}/chunks/{document_chunk_id}",
+            params=params or None,
+            cast_to=DocumentChunkResponse,
+        )
+
+    def archive(self, document_id: str) -> Document:
+        """Archive one canonical document by ID."""
+        return self._request(
+            "POST",
+            f"v1/documents/{document_id}/archive",
+            cast_to=Document,
+        )
+
+
+class AsyncDocuments(AsyncAPIResource):
+    """Asynchronous interface for ``/v1/documents`` endpoints."""
+
+    async def list(self, *, namespace: Optional[str] = None) -> DocumentListResponse:
+        """List canonical documents in a namespace."""
+        params: Dict[str, Any] = {}
+        if namespace is not None:
+            params["namespace"] = namespace
+
+        return await self._request(
+            "GET",
+            "v1/documents",
+            params=params or None,
+            cast_to=DocumentListResponse,
+        )
+
+    async def get(self, document_id: str) -> Document:
+        """Get one canonical document by ID."""
+        return await self._request(
+            "GET",
+            f"v1/documents/{document_id}",
+            cast_to=Document,
+        )
+
+    async def list_chunks(
+        self,
+        document_id: str,
+        *,
+        page: int = 1,
+        page_size: int = 50,
+        chunk_type: Optional[DocumentChunkType] = None,
+        include_asset_urls: bool = False,
+    ) -> DocumentChunkListResponse:
+        """List current-revision chunks for one canonical document."""
+        params: Dict[str, Any] = _build_chunk_list_params(
+            page=page,
+            page_size=page_size,
+            chunk_type=chunk_type,
+            include_asset_urls=include_asset_urls,
+        )
+
+        return await self._request(
+            "GET",
+            f"v1/documents/{document_id}/chunks",
+            params=params or None,
+            cast_to=DocumentChunkListResponse,
+        )
+
+    async def get_chunk(
+        self,
+        document_id: str,
+        document_chunk_id: str,
+        *,
+        include_asset_urls: bool = False,
+    ) -> DocumentChunkResponse:
+        """Get one current-revision chunk for one canonical document."""
+        params: Dict[str, Any] = _build_chunk_get_params(
+            include_asset_urls=include_asset_urls,
+        )
+
+        return await self._request(
+            "GET",
+            f"v1/documents/{document_id}/chunks/{document_chunk_id}",
+            params=params or None,
+            cast_to=DocumentChunkResponse,
+        )
+
+    async def archive(self, document_id: str) -> Document:
+        """Archive one canonical document by ID."""
+        return await self._request(
+            "POST",
+            f"v1/documents/{document_id}/archive",
+            cast_to=Document,
+        )
+
+
+def _build_chunk_list_params(
+    *,
+    page: int,
+    page_size: int,
+    chunk_type: Optional[DocumentChunkType],
+    include_asset_urls: bool,
+) -> Dict[str, Any]:
+    params: Dict[str, Any] = {}
+    if page != 1:
+        params["page"] = page
+    if page_size != 50:
+        params["page_size"] = page_size
+    if chunk_type is not None:
+        params["chunk_type"] = chunk_type
+    if include_asset_urls:
+        params["include_asset_urls"] = True
+    return params
+
+
+def _build_chunk_get_params(*, include_asset_urls: bool) -> Dict[str, Any]:
+    if not include_asset_urls:
+        return {}
+    return {"include_asset_urls": True}

{knowhere_python_sdk-0.3.2 → knowhere_python_sdk-0.4.0}/src/knowhere/types/__init__.py

@@ -2,7 +2,15 @@
 
 from __future__ import annotations
 
-from knowhere.types.document import Document, DocumentListResponse
+from knowhere.types.document import (
+    Document,
+    DocumentChunk,
+    DocumentChunkListResponse,
+    DocumentChunkPagination,
+    DocumentChunkResponse,
+    DocumentChunkType,
+    DocumentListResponse,
+)
 from knowhere.types.job import Job, JobError, JobResult
 from knowhere.types.params import ParsingParams, WebhookConfig
 from knowhere.types.retrieval import (
@@ -39,6 +47,11 @@ __all__: list[str] = [
     "JobResult",
     # document
     "Document",
+    "DocumentChunk",
+    "DocumentChunkListResponse",
+    "DocumentChunkPagination",
+    "DocumentChunkResponse",
+    "DocumentChunkType",
     "DocumentListResponse",
     # retrieval
     "RetrievalChannel",

knowhere_python_sdk-0.4.0/src/knowhere/types/document.py

@@ -0,0 +1,78 @@
+"""Pydantic models for canonical document lifecycle responses."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Literal, Optional
+
+from pydantic import BaseModel
+
+
+class Document(BaseModel):
+    """Canonical document state returned by ``/v1/documents`` endpoints."""
+
+    document_id: str
+    namespace: str
+    status: str
+    current_job_result_id: Optional[str] = None
+    source_file_name: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    archived_at: Optional[datetime] = None
+
+
+class DocumentListResponse(BaseModel):
+    """Response from ``GET /v1/documents``."""
+
+    namespace: str
+    documents: list[Document]
+
+
+DocumentChunkType = Literal["text", "image", "table"]
+
+
+class DocumentChunkPagination(BaseModel):
+    """Pagination metadata returned by document chunk list endpoints."""
+
+    page: int
+    page_size: int
+    total: int
+    total_pages: int
+
+
+class DocumentChunk(BaseModel):
+    """One current-revision document chunk."""
+
+    id: str
+    chunk_id: str
+    chunk_type: DocumentChunkType
+    content: Optional[str] = None
+    section_id: Optional[str] = None
+    section_path: Optional[str] = None
+    source_chunk_path: Optional[str] = None
+    file_path: Optional[str] = None
+    sort_order: int
+    metadata: Dict[str, Any]
+    asset_url: Optional[str] = None
+    created_at: Optional[datetime] = None
+
+
+class DocumentChunkListResponse(BaseModel):
+    """Response from ``GET /v1/documents/{document_id}/chunks``."""
+
+    document_id: str
+    namespace: str
+    job_result_id: Optional[str] = None
+    job_id: Optional[str] = None
+    chunks: list[DocumentChunk]
+    pagination: DocumentChunkPagination
+
+
+class DocumentChunkResponse(BaseModel):
+    """Response from ``GET /v1/documents/{document_id}/chunks/{chunk_id}``."""
+
+    document_id: str
+    namespace: str
+    job_result_id: Optional[str] = None
+    job_id: Optional[str] = None
+    chunk: DocumentChunk

knowhere_python_sdk-0.4.0/tests/test_documents.py

@@ -0,0 +1,219 @@
+"""Tests for the documents resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import httpx
+import pytest
+import respx
+
+from tests.conftest import BASE_URL
+
+
+DOCUMENTS_URL: str = f"{BASE_URL}/v1/documents"
+
+
+def _make_document(status: str = "active") -> Dict[str, Any]:
+    return {
+        "document_id": "doc_123",
+        "namespace": "support-center",
+        "status": status,
+        "current_job_result_id": "result_123",
+        "source_file_name": "refund-policy.md",
+        "created_at": "2026-04-21T08:00:00Z",
+        "updated_at": "2026-04-21T08:30:00Z",
+        "archived_at": "2026-04-21T09:00:00Z" if status == "archived" else None,
+    }
+
+
+def _make_document_chunk(chunk_type: str = "text") -> Dict[str, Any]:
+    return {
+        "id": "dchk_123",
+        "chunk_id": "parser-chunk-1",
+        "chunk_type": chunk_type,
+        "content": "Chunk content",
+        "section_id": "sec_123",
+        "section_path": "Chapter 1",
+        "source_chunk_path": "Chapter 1/Intro",
+        "file_path": "images/figure-1.png" if chunk_type == "image" else None,
+        "sort_order": 0,
+        "metadata": {"summary": "Intro", "page_nums": [1]},
+        "asset_url": "https://assets.example/figure-1.png" if chunk_type == "image" else None,
+        "created_at": "2026-04-27T04:00:00Z",
+    }
+
+
+class TestDocumentsResource:
+    """Verify document lifecycle calls."""
+
+    @respx.mock
+    def test_list_documents_sends_namespace_query(self, sync_client: Any) -> None:
+        route = respx.get(DOCUMENTS_URL).mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "namespace": "support-center",
+                    "documents": [_make_document()],
+                },
+            )
+        )
+
+        response = sync_client.documents.list(namespace="support-center")
+
+        assert route.called
+        assert route.calls[0].request.url.params["namespace"] == "support-center"
+        assert response.namespace == "support-center"
+        assert response.documents[0].document_id == "doc_123"
+
+    @respx.mock
+    def test_list_documents_omits_namespace_when_defaulted(self, sync_client: Any) -> None:
+        route = respx.get(DOCUMENTS_URL).mock(
+            return_value=httpx.Response(
+                200,
+                json={"namespace": "default", "documents": []},
+            )
+        )
+
+        response = sync_client.documents.list()
+
+        assert route.called
+        assert dict(route.calls[0].request.url.params) == {}
+        assert response.namespace == "default"
+        assert response.documents == []
+
+    @respx.mock
+    def test_get_document_returns_document_state(self, sync_client: Any) -> None:
+        route = respx.get(f"{DOCUMENTS_URL}/doc_123").mock(
+            return_value=httpx.Response(200, json=_make_document())
+        )
+
+        document = sync_client.documents.get("doc_123")
+
+        assert route.called
+        assert document.document_id == "doc_123"
+        assert document.status == "active"
+
+    @respx.mock
+    def test_list_chunks_sends_optional_query_params(self, sync_client: Any) -> None:
+        route = respx.get(f"{DOCUMENTS_URL}/doc_123/chunks").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "document_id": "doc_123",
+                    "namespace": "support-center",
+                    "job_result_id": "result_123",
+                    "job_id": "job_123",
+                    "chunks": [_make_document_chunk(chunk_type="table")],
+                    "pagination": {
+                        "page": 2,
+                        "page_size": 10,
+                        "total": 11,
+                        "total_pages": 2,
+                    },
+                },
+            )
+        )
+
+        response = sync_client.documents.list_chunks(
+            "doc_123",
+            page=2,
+            page_size=10,
+            chunk_type="table",
+            include_asset_urls=True,
+        )
+
+        assert route.called
+        assert route.calls[0].request.url.params["page"] == "2"
+        assert route.calls[0].request.url.params["page_size"] == "10"
+        assert route.calls[0].request.url.params["chunk_type"] == "table"
+        assert route.calls[0].request.url.params["include_asset_urls"] == "true"
+        assert response.document_id == "doc_123"
+        assert response.chunks[0].id == "dchk_123"
+        assert response.pagination.total_pages == 2
+
+    @respx.mock
+    def test_list_chunks_omits_default_query_params(self, sync_client: Any) -> None:
+        route = respx.get(f"{DOCUMENTS_URL}/doc_123/chunks").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "document_id": "doc_123",
+                    "namespace": "support-center",
+                    "job_result_id": None,
+                    "job_id": None,
+                    "chunks": [],
+                    "pagination": {
+                        "page": 1,
+                        "page_size": 50,
+                        "total": 0,
+                        "total_pages": 0,
+                    },
+                },
+            )
+        )
+
+        response = sync_client.documents.list_chunks("doc_123")
+
+        assert route.called
+        assert dict(route.calls[0].request.url.params) == {}
+        assert response.chunks == []
+        assert response.pagination.total == 0
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_async_get_chunk_requests_asset_urls_only_when_needed(
+        self,
+        async_client: Any,
+    ) -> None:
+        route = respx.get(f"{DOCUMENTS_URL}/doc_123/chunks/dchk_123").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "document_id": "doc_123",
+                    "namespace": "support-center",
+                    "job_result_id": "result_123",
+                    "job_id": "job_123",
+                    "chunk": _make_document_chunk(chunk_type="image"),
+                },
+            )
+        )
+
+        response = await async_client.documents.get_chunk(
+            "doc_123",
+            "dchk_123",
+            include_asset_urls=True,
+        )
+
+        assert route.called
+        assert route.calls[0].request.url.params["include_asset_urls"] == "true"
+        assert response.chunk.id == "dchk_123"
+        assert response.chunk.asset_url == "https://assets.example/figure-1.png"
+
+    @respx.mock
+    def test_archive_document_returns_archived_state(self, sync_client: Any) -> None:
+        route = respx.post(f"{DOCUMENTS_URL}/doc_123/archive").mock(
+            return_value=httpx.Response(200, json=_make_document(status="archived"))
+        )
+
+        document = sync_client.documents.archive("doc_123")
+
+        assert route.called
+        assert document.document_id == "doc_123"
+        assert document.status == "archived"
+        assert document.archived_at is not None
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_async_archive_document_returns_archived_state(
+        self,
+        async_client: Any,
+    ) -> None:
+        route = respx.post(f"{DOCUMENTS_URL}/doc_123/archive").mock(
+            return_value=httpx.Response(200, json=_make_document(status="archived"))
+        )
+
+        document = await async_client.documents.archive("doc_123")
+
+        assert route.called
+        assert document.status == "archived"

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

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

knowhere_python_sdk-0.3.2/src/knowhere/_version.py

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

knowhere_python_sdk-0.3.2/src/knowhere/resources/documents.py

@@ -1,74 +0,0 @@
-"""Documents resource for canonical document lifecycle operations."""
-
-from __future__ import annotations
-
-from typing import Any, Dict, Optional
-
-from knowhere.resources._base import AsyncAPIResource, SyncAPIResource
-from knowhere.types.document import Document, DocumentListResponse
-
-
-class Documents(SyncAPIResource):
-    """Synchronous interface for ``/v1/documents`` endpoints."""
-
-    def list(self, *, namespace: Optional[str] = None) -> DocumentListResponse:
-        """List canonical documents in a namespace."""
-        params: Dict[str, Any] = {}
-        if namespace is not None:
-            params["namespace"] = namespace
-
-        return self._request(
-            "GET",
-            "v1/documents",
-            params=params or None,
-            cast_to=DocumentListResponse,
-        )
-
-    def get(self, document_id: str) -> Document:
-        """Get one canonical document by ID."""
-        return self._request(
-            "GET",
-            f"v1/documents/{document_id}",
-            cast_to=Document,
-        )
-
-    def archive(self, document_id: str) -> Document:
-        """Archive one canonical document by ID."""
-        return self._request(
-            "POST",
-            f"v1/documents/{document_id}/archive",
-            cast_to=Document,
-        )
-
-
-class AsyncDocuments(AsyncAPIResource):
-    """Asynchronous interface for ``/v1/documents`` endpoints."""
-
-    async def list(self, *, namespace: Optional[str] = None) -> DocumentListResponse:
-        """List canonical documents in a namespace."""
-        params: Dict[str, Any] = {}
-        if namespace is not None:
-            params["namespace"] = namespace
-
-        return await self._request(
-            "GET",
-            "v1/documents",
-            params=params or None,
-            cast_to=DocumentListResponse,
-        )
-
-    async def get(self, document_id: str) -> Document:
-        """Get one canonical document by ID."""
-        return await self._request(
-            "GET",
-            f"v1/documents/{document_id}",
-            cast_to=Document,
-        )
-
-    async def archive(self, document_id: str) -> Document:
-        """Archive one canonical document by ID."""
-        return await self._request(
-            "POST",
-            f"v1/documents/{document_id}/archive",
-            cast_to=Document,
-        )

knowhere_python_sdk-0.3.2/src/knowhere/types/document.py

@@ -1,28 +0,0 @@
-"""Pydantic models for canonical document lifecycle responses."""
-
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Optional
-
-from pydantic import BaseModel
-
-
-class Document(BaseModel):
-    """Canonical document state returned by ``/v1/documents`` endpoints."""
-
-    document_id: str
-    namespace: str
-    status: str
-    current_job_result_id: Optional[str] = None
-    source_file_name: Optional[str] = None
-    created_at: Optional[datetime] = None
-    updated_at: Optional[datetime] = None
-    archived_at: Optional[datetime] = None
-
-
-class DocumentListResponse(BaseModel):
-    """Response from ``GET /v1/documents``."""
-
-    namespace: str
-    documents: list[Document]

knowhere_python_sdk-0.3.2/tests/test_documents.py

@@ -1,106 +0,0 @@
-"""Tests for the documents resource."""
-
-from __future__ import annotations
-
-from typing import Any, Dict
-
-import httpx
-import pytest
-import respx
-
-from tests.conftest import BASE_URL
-
-
-DOCUMENTS_URL: str = f"{BASE_URL}/v1/documents"
-
-
-def _make_document(status: str = "active") -> Dict[str, Any]:
-    return {
-        "document_id": "doc_123",
-        "namespace": "support-center",
-        "status": status,
-        "current_job_result_id": "result_123",
-        "source_file_name": "refund-policy.md",
-        "created_at": "2026-04-21T08:00:00Z",
-        "updated_at": "2026-04-21T08:30:00Z",
-        "archived_at": "2026-04-21T09:00:00Z" if status == "archived" else None,
-    }
-
-
-class TestDocumentsResource:
-    """Verify document lifecycle calls."""
-
-    @respx.mock
-    def test_list_documents_sends_namespace_query(self, sync_client: Any) -> None:
-        route = respx.get(DOCUMENTS_URL).mock(
-            return_value=httpx.Response(
-                200,
-                json={
-                    "namespace": "support-center",
-                    "documents": [_make_document()],
-                },
-            )
-        )
-
-        response = sync_client.documents.list(namespace="support-center")
-
-        assert route.called
-        assert route.calls[0].request.url.params["namespace"] == "support-center"
-        assert response.namespace == "support-center"
-        assert response.documents[0].document_id == "doc_123"
-
-    @respx.mock
-    def test_list_documents_omits_namespace_when_defaulted(self, sync_client: Any) -> None:
-        route = respx.get(DOCUMENTS_URL).mock(
-            return_value=httpx.Response(
-                200,
-                json={"namespace": "default", "documents": []},
-            )
-        )
-
-        response = sync_client.documents.list()
-
-        assert route.called
-        assert dict(route.calls[0].request.url.params) == {}
-        assert response.namespace == "default"
-        assert response.documents == []
-
-    @respx.mock
-    def test_get_document_returns_document_state(self, sync_client: Any) -> None:
-        route = respx.get(f"{DOCUMENTS_URL}/doc_123").mock(
-            return_value=httpx.Response(200, json=_make_document())
-        )
-
-        document = sync_client.documents.get("doc_123")
-
-        assert route.called
-        assert document.document_id == "doc_123"
-        assert document.status == "active"
-
-    @respx.mock
-    def test_archive_document_returns_archived_state(self, sync_client: Any) -> None:
-        route = respx.post(f"{DOCUMENTS_URL}/doc_123/archive").mock(
-            return_value=httpx.Response(200, json=_make_document(status="archived"))
-        )
-
-        document = sync_client.documents.archive("doc_123")
-
-        assert route.called
-        assert document.document_id == "doc_123"
-        assert document.status == "archived"
-        assert document.archived_at is not None
-
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_async_archive_document_returns_archived_state(
-        self,
-        async_client: Any,
-    ) -> None:
-        route = respx.post(f"{DOCUMENTS_URL}/doc_123/archive").mock(
-            return_value=httpx.Response(200, json=_make_document(status="archived"))
-        )
-
-        document = await async_client.documents.archive("doc_123")
-
-        assert route.called
-        assert document.status == "archived"