knowhere-python-sdk 0.2.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

knowhere/__init__.py

@@ -35,8 +35,17 @@ 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.job import Job, JobError, JobProgress, JobResult
 from knowhere.types.params import ParsingParams, WebhookConfig
+from knowhere.types.retrieval import (
+    RetrievalChannel,
+    RetrievalFilterMode,
+    RetrievalSectionExclusion,
+    RetrievalSource,
+    RetrievalQueryResponse,
+    RetrievalResult,
+)
 from knowhere.types.result import (
     BaseChunk,
     Checksum,
@@ -87,6 +96,16 @@ __all__: list[str] = [
     "JobError",
     "JobProgress",
     "JobResult",
+    # Document types
+    "Document",
+    "DocumentListResponse",
+    # Retrieval types
+    "RetrievalChannel",
+    "RetrievalFilterMode",
+    "RetrievalSectionExclusion",
+    "RetrievalSource",
+    "RetrievalQueryResponse",
+    "RetrievalResult",
     # Result types
     "ParseResult",
     "Manifest",

knowhere/_client.py

@@ -19,7 +19,9 @@ from knowhere._types import (
     PollProgressCallback,
     UploadProgressCallback,
 )
+from knowhere.resources.documents import AsyncDocuments, Documents
 from knowhere.resources.jobs import AsyncJobs, Jobs
+from knowhere.resources.retrieval import AsyncRetrieval, Retrieval
 from knowhere.types.job import Job, JobResult
 from knowhere.types.params import ParsingParams, WebhookConfig
 from knowhere.types.result import ParseResult
@@ -42,6 +44,16 @@ class Knowhere(SyncAPIClient):
         """Access the jobs resource namespace."""
         return Jobs(self)
 
+    @cached_property
+    def retrieval(self) -> Retrieval:
+        """Access the retrieval resource namespace."""
+        return Retrieval(self)
+
+    @cached_property
+    def documents(self) -> Documents:
+        """Access the documents resource namespace."""
+        return Documents(self)
+
     # -- overloaded parse signatures --
 
     @overload
@@ -50,6 +62,8 @@ class Knowhere(SyncAPIClient):
         *,
         url: str,
         data_id: Optional[str] = ...,
+        namespace: Optional[str] = ...,
+        document_id: Optional[str] = ...,
         parsing_params: Optional[ParsingParams] = ...,
         webhook: Optional[WebhookConfig] = ...,
         poll_interval: float = ...,
@@ -66,6 +80,8 @@ class Knowhere(SyncAPIClient):
         file: Union[Path, BinaryIO, bytes],
         file_name: Optional[str] = ...,
         data_id: Optional[str] = ...,
+        namespace: Optional[str] = ...,
+        document_id: Optional[str] = ...,
         parsing_params: Optional[ParsingParams] = ...,
         webhook: Optional[WebhookConfig] = ...,
         poll_interval: float = ...,
@@ -82,6 +98,8 @@ class Knowhere(SyncAPIClient):
         file: Optional[Union[Path, BinaryIO, bytes]] = None,
         file_name: Optional[str] = None,
         data_id: Optional[str] = None,
+        namespace: Optional[str] = None,
+        document_id: Optional[str] = None,
         parsing_params: Optional[ParsingParams] = None,
         webhook: Optional[WebhookConfig] = None,
         poll_interval: float = DEFAULT_POLL_INTERVAL,
@@ -105,6 +123,8 @@ class Knowhere(SyncAPIClient):
                 source_type="url",
                 source_url=url,
                 data_id=data_id,
+                namespace=namespace,
+                document_id=document_id,
                 parsing_params=parsing_params,
                 webhook=webhook,
             )
@@ -116,6 +136,8 @@ class Knowhere(SyncAPIClient):
                 source_type="file",
                 file_name=resolved_name,
                 data_id=data_id,
+                namespace=namespace,
+                document_id=document_id,
                 parsing_params=parsing_params,
                 webhook=webhook,
             )
@@ -149,12 +171,24 @@ class AsyncKnowhere(AsyncAPIClient):
         """Access the async jobs resource namespace."""
         return AsyncJobs(self)
 
+    @cached_property
+    def retrieval(self) -> AsyncRetrieval:
+        """Access the async retrieval resource namespace."""
+        return AsyncRetrieval(self)
+
+    @cached_property
+    def documents(self) -> AsyncDocuments:
+        """Access the async documents resource namespace."""
+        return AsyncDocuments(self)
+
     @overload
     async def parse(
         self,
         *,
         url: str,
         data_id: Optional[str] = ...,
+        namespace: Optional[str] = ...,
+        document_id: Optional[str] = ...,
         parsing_params: Optional[ParsingParams] = ...,
         webhook: Optional[WebhookConfig] = ...,
         poll_interval: float = ...,
@@ -171,6 +205,8 @@ class AsyncKnowhere(AsyncAPIClient):
         file: Union[Path, BinaryIO, bytes],
         file_name: Optional[str] = ...,
         data_id: Optional[str] = ...,
+        namespace: Optional[str] = ...,
+        document_id: Optional[str] = ...,
         parsing_params: Optional[ParsingParams] = ...,
         webhook: Optional[WebhookConfig] = ...,
         poll_interval: float = ...,
@@ -187,6 +223,8 @@ class AsyncKnowhere(AsyncAPIClient):
         file: Optional[Union[Path, BinaryIO, bytes]] = None,
         file_name: Optional[str] = None,
         data_id: Optional[str] = None,
+        namespace: Optional[str] = None,
+        document_id: Optional[str] = None,
         parsing_params: Optional[ParsingParams] = None,
         webhook: Optional[WebhookConfig] = None,
         poll_interval: float = DEFAULT_POLL_INTERVAL,
@@ -206,6 +244,8 @@ class AsyncKnowhere(AsyncAPIClient):
                 source_type="url",
                 source_url=url,
                 data_id=data_id,
+                namespace=namespace,
+                document_id=document_id,
                 parsing_params=parsing_params,
                 webhook=webhook,
             )
@@ -217,6 +257,8 @@ class AsyncKnowhere(AsyncAPIClient):
                 source_type="file",
                 file_name=resolved_name,
                 data_id=data_id,
+                namespace=namespace,
+                document_id=document_id,
                 parsing_params=parsing_params,
                 webhook=webhook,
             )
@@ -232,4 +274,4 @@ class AsyncKnowhere(AsyncAPIClient):
 
         return await self.jobs.load(
             job_result, verify_checksum=verify_checksum
-        )
+        )

knowhere/_version.py

@@ -1 +1 @@
-__version__ = "0.2.1"  # x-release-please-version
+__version__ = "0.3.1"  # x-release-please-version

knowhere/resources/__init__.py

@@ -2,6 +2,15 @@
 
 from __future__ import annotations
 
+from knowhere.resources.documents import AsyncDocuments, Documents
 from knowhere.resources.jobs import AsyncJobs, Jobs
+from knowhere.resources.retrieval import AsyncRetrieval, Retrieval
 
-__all__: list[str] = ["Jobs", "AsyncJobs"]
+__all__: list[str] = [
+    "AsyncDocuments",
+    "AsyncJobs",
+    "AsyncRetrieval",
+    "Documents",
+    "Jobs",
+    "Retrieval",
+]

knowhere/resources/documents.py

@@ -0,0 +1,74 @@
+"""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/resources/jobs.py

@@ -34,6 +34,8 @@ class Jobs(SyncAPIResource):
         source_type: str,
         source_url: Optional[str] = None,
         file_name: Optional[str] = None,
+        namespace: Optional[str] = None,
+        document_id: Optional[str] = None,
         data_id: Optional[str] = None,
         parsing_params: Optional[ParsingParams] = None,
         webhook: Optional[WebhookConfig] = None,
@@ -44,6 +46,8 @@ class Jobs(SyncAPIResource):
             source_type: ``"url"`` or ``"file"``.
             source_url: URL to parse (required when ``source_type="url"``).
             file_name: Original filename (used when ``source_type="file"``).
+            namespace: Retrieval namespace. Defaults to the server ``default``.
+            document_id: Existing document ID when creating an update job.
             data_id: Optional idempotency / correlation identifier.
             parsing_params: Optional parsing configuration.
             webhook: Optional webhook configuration.
@@ -56,6 +60,10 @@ class Jobs(SyncAPIResource):
             body["source_url"] = source_url
         if file_name is not None:
             body["file_name"] = file_name
+        if namespace is not None:
+            body["namespace"] = namespace
+        if document_id is not None:
+            body["document_id"] = document_id
         if data_id is not None:
             body["data_id"] = data_id
         if parsing_params is not None:
@@ -137,8 +145,12 @@ class Jobs(SyncAPIResource):
             if not job_result.result_url:
                 raise InvalidStateError("JobResult does not have a result_url.")
             result_url: str = job_result.result_url
+            namespace: Optional[str] = job_result.namespace
+            document_id: Optional[str] = job_result.document_id
         else:
             result_url = job_result
+            namespace = None
+            document_id = None
 
         response: httpx.Response = self._client._client.get(
             result_url, timeout=self._client.upload_timeout
@@ -146,7 +158,10 @@ class Jobs(SyncAPIResource):
         response.raise_for_status()
         zip_bytes: bytes = response.content
 
-        return parseResultZip(zip_bytes, verify_checksum=verify_checksum)
+        parsed_result = parseResultZip(zip_bytes, verify_checksum=verify_checksum)
+        parsed_result.namespace = namespace
+        parsed_result.document_id = document_id
+        return parsed_result
 
 
 class AsyncJobs(AsyncAPIResource):
@@ -158,6 +173,8 @@ class AsyncJobs(AsyncAPIResource):
         source_type: str,
         source_url: Optional[str] = None,
         file_name: Optional[str] = None,
+        namespace: Optional[str] = None,
+        document_id: Optional[str] = None,
         data_id: Optional[str] = None,
         parsing_params: Optional[ParsingParams] = None,
         webhook: Optional[WebhookConfig] = None,
@@ -168,6 +185,10 @@ class AsyncJobs(AsyncAPIResource):
             body["source_url"] = source_url
         if file_name is not None:
             body["file_name"] = file_name
+        if namespace is not None:
+            body["namespace"] = namespace
+        if document_id is not None:
+            body["document_id"] = document_id
         if data_id is not None:
             body["data_id"] = data_id
         if parsing_params is not None:
@@ -237,8 +258,12 @@ class AsyncJobs(AsyncAPIResource):
             if not job_result.result_url:
                 raise InvalidStateError("JobResult does not have a result_url.")
             result_url: str = job_result.result_url
+            namespace: Optional[str] = job_result.namespace
+            document_id: Optional[str] = job_result.document_id
         else:
             result_url = job_result
+            namespace = None
+            document_id = None
 
         response: httpx.Response = await self._client._client.get(
             result_url, timeout=self._client.upload_timeout
@@ -246,4 +271,7 @@ class AsyncJobs(AsyncAPIResource):
         response.raise_for_status()
         zip_bytes: bytes = response.content
 
-        return parseResultZip(zip_bytes, verify_checksum=verify_checksum)
+        parsed_result = parseResultZip(zip_bytes, verify_checksum=verify_checksum)
+        parsed_result.namespace = namespace
+        parsed_result.document_id = document_id
+        return parsed_result

knowhere/resources/retrieval.py

@@ -0,0 +1,123 @@
+"""Retrieval resource for querying published documents."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from knowhere.resources._base import AsyncAPIResource, SyncAPIResource
+from knowhere.types.retrieval import (
+    RetrievalChannel,
+    RetrievalFilterMode,
+    RetrievalQueryResponse,
+    RetrievalSectionExclusion,
+)
+
+
+class Retrieval(SyncAPIResource):
+    """Synchronous interface for ``/v1/retrieval`` endpoints."""
+
+    def query(
+        self,
+        *,
+        query: str,
+        namespace: Optional[str] = None,
+        top_k: Optional[int] = None,
+        data_type: Optional[int] = None,
+        signal_paths: Optional[list[str]] = None,
+        filter_mode: Optional[RetrievalFilterMode] = None,
+        channels: Optional[list[RetrievalChannel]] = None,
+        channel_weights: Optional[dict[RetrievalChannel, float]] = None,
+        rerank: Optional[bool] = None,
+        threshold: Optional[float] = None,
+        internal_recall_k: Optional[int] = None,
+        exclude_document_ids: Optional[list[str]] = None,
+        exclude_sections: Optional[list[RetrievalSectionExclusion]] = None,
+    ) -> RetrievalQueryResponse:
+        """Query published documents in a namespace."""
+        body: Dict[str, Any] = {"query": query}
+        if namespace is not None:
+            body["namespace"] = namespace
+        if top_k is not None:
+            body["top_k"] = top_k
+        if data_type is not None:
+            body["data_type"] = data_type
+        if signal_paths is not None:
+            body["signal_paths"] = signal_paths
+        if filter_mode is not None:
+            body["filter_mode"] = filter_mode
+        if channels is not None:
+            body["channels"] = channels
+        if channel_weights is not None:
+            body["channel_weights"] = channel_weights
+        if rerank is not None:
+            body["rerank"] = rerank
+        if threshold is not None:
+            body["threshold"] = threshold
+        if internal_recall_k is not None:
+            body["internal_recall_k"] = internal_recall_k
+        if exclude_document_ids is not None:
+            body["exclude_document_ids"] = exclude_document_ids
+        if exclude_sections is not None:
+            body["exclude_sections"] = exclude_sections
+
+        return self._request(
+            "POST",
+            "v1/retrieval/query",
+            body=body,
+            cast_to=RetrievalQueryResponse,
+        )
+
+
+class AsyncRetrieval(AsyncAPIResource):
+    """Asynchronous interface for ``/v1/retrieval`` endpoints."""
+
+    async def query(
+        self,
+        *,
+        query: str,
+        namespace: Optional[str] = None,
+        top_k: Optional[int] = None,
+        data_type: Optional[int] = None,
+        signal_paths: Optional[list[str]] = None,
+        filter_mode: Optional[RetrievalFilterMode] = None,
+        channels: Optional[list[RetrievalChannel]] = None,
+        channel_weights: Optional[dict[RetrievalChannel, float]] = None,
+        rerank: Optional[bool] = None,
+        threshold: Optional[float] = None,
+        internal_recall_k: Optional[int] = None,
+        exclude_document_ids: Optional[list[str]] = None,
+        exclude_sections: Optional[list[RetrievalSectionExclusion]] = None,
+    ) -> RetrievalQueryResponse:
+        """Query published documents in a namespace."""
+        body: Dict[str, Any] = {"query": query}
+        if namespace is not None:
+            body["namespace"] = namespace
+        if top_k is not None:
+            body["top_k"] = top_k
+        if data_type is not None:
+            body["data_type"] = data_type
+        if signal_paths is not None:
+            body["signal_paths"] = signal_paths
+        if filter_mode is not None:
+            body["filter_mode"] = filter_mode
+        if channels is not None:
+            body["channels"] = channels
+        if channel_weights is not None:
+            body["channel_weights"] = channel_weights
+        if rerank is not None:
+            body["rerank"] = rerank
+        if threshold is not None:
+            body["threshold"] = threshold
+        if internal_recall_k is not None:
+            body["internal_recall_k"] = internal_recall_k
+        if exclude_document_ids is not None:
+            body["exclude_document_ids"] = exclude_document_ids
+        if exclude_sections is not None:
+            body["exclude_sections"] = exclude_sections
+
+        return await self._request(
+            "POST",
+            "v1/retrieval/query",
+            body=body,
+            cast_to=RetrievalQueryResponse,
+        )

knowhere/types/__init__.py

@@ -2,8 +2,17 @@
 
 from __future__ import annotations
 
+from knowhere.types.document import Document, DocumentListResponse
 from knowhere.types.job import Job, JobError, JobResult
 from knowhere.types.params import ParsingParams, WebhookConfig
+from knowhere.types.retrieval import (
+    RetrievalChannel,
+    RetrievalFilterMode,
+    RetrievalSectionExclusion,
+    RetrievalSource,
+    RetrievalQueryResponse,
+    RetrievalResult,
+)
 from knowhere.types.result import (
     BaseChunk,
     Checksum,
@@ -28,6 +37,16 @@ __all__: list[str] = [
     "Job",
     "JobError",
     "JobResult",
+    # document
+    "Document",
+    "DocumentListResponse",
+    # retrieval
+    "RetrievalChannel",
+    "RetrievalFilterMode",
+    "RetrievalSectionExclusion",
+    "RetrievalSource",
+    "RetrievalQueryResponse",
+    "RetrievalResult",
     # params
     "ParsingParams",
     "WebhookConfig",

knowhere/types/document.py

@@ -0,0 +1,28 @@
+"""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/types/job.py

@@ -40,6 +40,7 @@ class Job(BaseModel):
     job_id: str
     status: str
     source_type: str
+    namespace: Optional[str] = None
     data_id: Optional[str] = None
     created_at: Optional[datetime] = None
     upload_url: Optional[str] = None
@@ -53,6 +54,8 @@ class JobResult(BaseModel):
     job_id: str
     status: str
     source_type: str
+    namespace: Optional[str] = None
+    document_id: Optional[str] = None
     data_id: Optional[str] = None
     created_at: Optional[datetime] = None
     progress: Optional[Union[float, JobProgress]] = None

knowhere/types/result.py

@@ -272,6 +272,8 @@ class ParseResult:
     kb_csv: Optional[str]
     hierarchy_view_html: Optional[str]
     raw_zip: bytes
+    namespace: Optional[str]
+    document_id: Optional[str]
 
     def __init__(
         self,
@@ -285,6 +287,8 @@ class ParseResult:
         kb_csv: Optional[str],
         hierarchy_view_html: Optional[str],
         raw_zip: bytes,
+        namespace: Optional[str] = None,
+        document_id: Optional[str] = None,
     ) -> None:
         self.manifest = manifest
         self.chunks = chunks
@@ -295,6 +299,8 @@ class ParseResult:
         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 --
 

knowhere/types/retrieval.py

@@ -0,0 +1,45 @@
+"""Pydantic models for retrieval query responses."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional, TypedDict
+
+from pydantic import BaseModel
+
+
+RetrievalChannel = Literal["path", "content", "term"]
+RetrievalFilterMode = Literal["delete", "keep"]
+
+
+class RetrievalSectionExclusion(TypedDict):
+    """Section exclusion for follow-up retrieval queries."""
+
+    document_id: str
+    section_path: str
+
+
+class RetrievalSource(BaseModel):
+    """Caller-facing source reference attached to a retrieval result."""
+
+    document_id: Optional[str] = None
+    source_file_name: Optional[str] = None
+    section_path: Optional[str] = None
+
+
+class RetrievalResult(BaseModel):
+    """Canonical chunk result returned by ``POST /v1/retrieval/query``."""
+
+    chunk_type: str
+    content: str
+    score: float
+    asset_url: Optional[str] = None
+    source: RetrievalSource
+
+
+class RetrievalQueryResponse(BaseModel):
+    """Response from ``POST /v1/retrieval/query``."""
+
+    namespace: str
+    query: str
+    router_used: Optional[str] = None
+    results: list[RetrievalResult]

{knowhere_python_sdk-0.2.1.dist-info → knowhere_python_sdk-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowhere-python-sdk
-Version: 0.2.1
+Version: 0.3.1
 Summary: Official Python SDK for the Knowhere document parsing API
 Project-URL: Homepage, https://knowhereto.ai
 Project-URL: Documentation, https://docs.knowhereto.ai
@@ -64,6 +64,84 @@ for chunk in result.text_chunks:
     print(chunk.content[:80])
 ```
 
+## Retrieval and document lifecycle
+
+New documents are published into a retrieval namespace. The server returns a
+stable `document_id` after the job is published. `client.jobs.create(...)`
+does not return a usable `document_id`; persist `job_result.document_id` if you
+need to update or archive the same document later.
+
+```python
+job = client.jobs.create(
+    source_type="url",
+    source_url="https://example.com/manual.pdf",
+    namespace="support-center",
+)
+
+job_result = client.jobs.wait(job.job_id)
+document_id = job_result.document_id
+
+if document_id is None:
+    raise RuntimeError("Expected document_id after successful publication.")
+```
+
+After the job is done and published, query the canonical document content:
+
+```python
+response = client.retrieval.query(
+    namespace="support-center",
+    query="How do I reset Bluetooth pairing?",
+    top_k=5,
+    channels=["path", "term"],
+    filter_mode="keep",
+    signal_paths=["Bluetooth", "Pairing"],
+)
+
+print(response.router_used)
+
+for result in response.results:
+    print(result.content)
+    print(result.score)
+    print(result.source.source_file_name, result.source.section_path)
+```
+
+Use `document_id` to update or archive a document:
+
+```python
+update_job = client.jobs.create(
+    source_type="url",
+    source_url="https://example.com/manual-v2.pdf",
+    document_id=document_id,
+)
+
+document = client.documents.get(document_id)
+print(document.status)
+
+client.documents.archive(document_id)
+```
+
+You can also list documents in a namespace:
+
+```python
+documents = client.documents.list(namespace="support-center")
+for document in documents.documents:
+    print(document.document_id, document.status)
+```
+
+Retrieval supports exclusions when clients want follow-up results that avoid
+previously used documents or sections:
+
+```python
+response = client.retrieval.query(
+    namespace="support-center",
+    query="battery charging",
+    exclude_document_ids=["doc_old"],
+    exclude_sections=[
+        {"document_id": "doc_123", "section_path": "Appendix / Legal"}
+    ],
+)
+```
+
 While you can provide an `api_key` keyword argument, we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/) to add `KNOWHERE_API_KEY="sk_..."` to your `.env` file so that your API key is not stored in source control.
 
 ### Parse a local file
@@ -78,6 +156,8 @@ result = client.parse(
 
 print(result.manifest.source_file_name)  # "report.pdf"
 print(len(result.chunks))                # 152
+print(result.namespace)                  # "default" or your explicit namespace
+print(result.document_id)                # Published canonical document id
 ```
 
 ### Access different chunk types
@@ -137,6 +217,7 @@ from pathlib import Path
 job = client.jobs.create(
     source_type="file",
     file_name="report.pdf",
+    namespace="support-center",
     parsing_params={"model": "advanced", "ocr_enabled": True},
 )
 
@@ -146,6 +227,8 @@ client.jobs.upload(job, file=Path("report.pdf"))
 # Step 3: Poll until done (adaptive backoff)
 job_result = client.jobs.wait(job.job_id, poll_interval=10.0, poll_timeout=1800.0)
 
+print(job_result.document_id)  # Persist this to update/archive the document later.
+
 # Step 4: Download and parse results
 result = client.jobs.load(job_result)
 print(result.statistics)

knowhere_python_sdk-0.3.1.dist-info/RECORD

@@ -0,0 +1,29 @@
+knowhere/__init__.py,sha256=wicVid8SW7a3AqabHmHI6iIxpY5Tm732eMyQgBQ7zDM,3016
+knowhere/_base_client.py,sha256=ddeRR1lWLhes5ipvYX6-TMEecjjiEBGfQdPw_vnSNqA,17978
+knowhere/_client.py,sha256=WYb-Fhi3x3nQYNfQG9eCgOpLc_wVyAawfPZWdZhFESg,9586
+knowhere/_constants.py,sha256=ZNCFQC00NpUZIyc_XZ0uemjJE-E8uKAbv3BDa3po9cg,885
+knowhere/_exceptions.py,sha256=NflH7phh_bNFOJmQ758V4mZCAFQskpGXACMz2JIfFNU,11896
+knowhere/_logging.py,sha256=tNqEA1dLv-adTT6qRq5RBeO35FoWrnS3gwt7gKChLTA,1376
+knowhere/_response.py,sha256=EsrM794qxCykvl82UkszeqjJzm9_OSq7nsyzaSCnx0I,1415
+knowhere/_types.py,sha256=8-JFaRcxgBJbw2mV9BwnmCktFVph41a1mduwtXlYidI,1775
+knowhere/_version.py,sha256=ma0Xv9k49qOL337sii6xfWylMGz1MNXbCb4rszXekbo,50
+knowhere/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+knowhere/lib/__init__.py,sha256=e953V5ny3VmDtCw7y_4uPwdTkwwNpe_Y6o4AEgz3ujw,50
+knowhere/lib/polling.py,sha256=s0EPHozAvNhXLqr5uwU8YXkkwAdF0ji_nIN0QfR6avY,4500
+knowhere/lib/result_parser.py,sha256=dR3knoMq-AFMAe0M3l0YgOM-OrtSmofSLaKZO0tgYao,9882
+knowhere/lib/upload.py,sha256=eT-O9_wB2WkWUAsUd7VzaKY6DVfNeA6WMHRdwm0HM0o,7849
+knowhere/resources/__init__.py,sha256=ClsR-yn_0E4KOopD_Yq13wbPHHjl9s15XpydN-d2Rzo,393
+knowhere/resources/_base.py,sha256=tgKphNTsgMhktWp6_rhyVOZyee4CYlDmD5O1_jWVvYo,1829
+knowhere/resources/documents.py,sha256=u_gmrElvpMOABaHkEuTyaYvh4D_CG4pHZt23r8tivaY,2314
+knowhere/resources/jobs.py,sha256=xYhgYP3Vz7SgGEckmXOvZocNru_4nsS4BoqquojncNw,9727
+knowhere/resources/retrieval.py,sha256=t_jFY-7wYfYVSH6e3WYgn0IaoaPcABXaeZoqcs-pUIo,4543
+knowhere/types/__init__.py,sha256=-T1Rx90y1W3kSW63v6QbXDgTO9aE097vx98xvRaYejU,1452
+knowhere/types/document.py,sha256=LbFleglvm538vSDDho82j7fVxvgMXdIVm9wrWemLShY,711
+knowhere/types/job.py,sha256=VsLUFuELZo8rRemuekTbliTIwaD6CR_dAjgdSriPmw4,2472
+knowhere/types/params.py,sha256=7DyBd4xMxtLPch-A1130-gI0ajKOv2G5tbSMkE8n6-E,543
+knowhere/types/result.py,sha256=uSpvOadmKOF5-n_uBTkmWAho2eDsOAUZoK_W96X2jeU,13143
+knowhere/types/retrieval.py,sha256=EopqmAx2DeO9AmEbd50emdu2mTbTxrhGoJ6DwvvoUCI,1090
+knowhere/types/shared.py,sha256=K5ezX212othxgCviiE2WnwWFY2MS08pXKJ8Km1ZWmjc,104
+knowhere_python_sdk-0.3.1.dist-info/METADATA,sha256=VSSYe-vr9NLen7NEf-BZc4lT3OJF4bGtL3ivqYbItDk,8429
+knowhere_python_sdk-0.3.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+knowhere_python_sdk-0.3.1.dist-info/RECORD,,

knowhere_python_sdk-0.2.1.dist-info/RECORD

@@ -1,25 +0,0 @@
-knowhere/__init__.py,sha256=NFNOUllG-7TZ-NVx7_g1vUPv15zQp1lvAXjb0BQotB4,2513
-knowhere/_base_client.py,sha256=ddeRR1lWLhes5ipvYX6-TMEecjjiEBGfQdPw_vnSNqA,17978
-knowhere/_client.py,sha256=MGU1QsyjKrzTiitm891wgNCq6JLf3DR7y7zhkil_p2E,8027
-knowhere/_constants.py,sha256=ZNCFQC00NpUZIyc_XZ0uemjJE-E8uKAbv3BDa3po9cg,885
-knowhere/_exceptions.py,sha256=NflH7phh_bNFOJmQ758V4mZCAFQskpGXACMz2JIfFNU,11896
-knowhere/_logging.py,sha256=tNqEA1dLv-adTT6qRq5RBeO35FoWrnS3gwt7gKChLTA,1376
-knowhere/_response.py,sha256=EsrM794qxCykvl82UkszeqjJzm9_OSq7nsyzaSCnx0I,1415
-knowhere/_types.py,sha256=8-JFaRcxgBJbw2mV9BwnmCktFVph41a1mduwtXlYidI,1775
-knowhere/_version.py,sha256=5IhDnbb-SxjydsfhOSqft_BBCgSQNKdMjw7ElLASiGo,50
-knowhere/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-knowhere/lib/__init__.py,sha256=e953V5ny3VmDtCw7y_4uPwdTkwwNpe_Y6o4AEgz3ujw,50
-knowhere/lib/polling.py,sha256=s0EPHozAvNhXLqr5uwU8YXkkwAdF0ji_nIN0QfR6avY,4500
-knowhere/lib/result_parser.py,sha256=dR3knoMq-AFMAe0M3l0YgOM-OrtSmofSLaKZO0tgYao,9882
-knowhere/lib/upload.py,sha256=eT-O9_wB2WkWUAsUd7VzaKY6DVfNeA6WMHRdwm0HM0o,7849
-knowhere/resources/__init__.py,sha256=_x391t8qxwkGbOmbkzcp7rR10Q8uoDLQaAkZxCq_oM8,170
-knowhere/resources/_base.py,sha256=tgKphNTsgMhktWp6_rhyVOZyee4CYlDmD5O1_jWVvYo,1829
-knowhere/resources/jobs.py,sha256=45P4rZ9HMnTdgcso2AwQ6lDA9U80HGsgOU0jZLBIMFU,8460
-knowhere/types/__init__.py,sha256=2Qp2bIY7CyVieBdSfQnowyKG-ErMI3wF37-neBdwTBU,961
-knowhere/types/job.py,sha256=8shCqvgzKKkEPOpEHdk7CnDbPQiDzy3wEd5Jngw94ZM,2362
-knowhere/types/params.py,sha256=7DyBd4xMxtLPch-A1130-gI0ajKOv2G5tbSMkE8n6-E,543
-knowhere/types/result.py,sha256=UmoxaFmxt2bhrP-2O6jYL89C2WuwZh2xcyyHl46Q1_Y,12925
-knowhere/types/shared.py,sha256=K5ezX212othxgCviiE2WnwWFY2MS08pXKJ8Km1ZWmjc,104
-knowhere_python_sdk-0.2.1.dist-info/METADATA,sha256=xf35vXtOtg7ubZWh4QNrqcjTpERpJO8kYuPXKmcmz_w,6115
-knowhere_python_sdk-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-knowhere_python_sdk-0.2.1.dist-info/RECORD,,