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

knowhere_python_sdk-0.3.2/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,45 @@
+name: Bug report
+description: Report a reproducible problem in the Python SDK.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened, and what did you expect instead?
+    validations:
+      required: true
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SDK version
+      placeholder: 0.3.1
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: 3.11.9
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: macOS 15.4 / Ubuntu 24.04
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Minimal code or steps to reproduce the issue.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs or tracebacks
+      render: text

knowhere_python_sdk-0.3.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Knowhere documentation
+    url: https://docs.knowhereto.ai
+    about: Check the public docs before opening a support issue.
+  - name: Security report
+    url: mailto:team@knowhereto.ai?subject=Security%20report%20for%20knowhere-python-sdk
+    about: Report vulnerabilities privately by email.

knowhere_python_sdk-0.3.2/.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose an improvement for the Python SDK.
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What developer problem are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the API or behavior you want to add or improve.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Describe any workarounds or alternative designs you considered.

knowhere_python_sdk-0.3.2/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+- describe the change
+- describe any public API impact
+
+## Verification
+
+- list the commands you ran
+- list any manual checks you performed
+
+## Checklist
+
+- [ ] Tests were added or updated when behavior changed
+- [ ] Public docs or examples were updated when needed
+- [ ] The pull request description explains any breaking or user-visible change

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

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

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

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.3.2](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.3.1...v0.3.2) (2026-04-23)
+
+
+### Chores
+
+* harden python sdk OSS surface ([e7d9779](https://github.com/Ontos-AI/knowhere-python-sdk/commit/e7d9779502327d2bd9e4f27e666244d34f8fafb7))
+* harden Python SDK OSS surface ([a9396cd](https://github.com/Ontos-AI/knowhere-python-sdk/commit/a9396cda70eabcba66172884e38045caefc85a01))
+
+## [0.3.1](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.3.0...v0.3.1) (2026-04-22)
+
+
+### Documentation
+
+* clarify ParseResult document scope ([861084e](https://github.com/Ontos-AI/knowhere-python-sdk/commit/861084e34144987994fa618ac0db262ce681b5a8))
+* clarify ParseResult document scope ([bb14ad4](https://github.com/Ontos-AI/knowhere-python-sdk/commit/bb14ad4077c41cbe74a5dd155995d6f9937962b8))
+
 ## [0.3.0](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.2.1...v0.3.0) (2026-04-21)
 
 

knowhere_python_sdk-0.3.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+We want the Knowhere Python SDK community to be respectful, constructive, and
+welcoming.
+
+## Expected Behavior
+
+- Be respectful in discussions and code review.
+- Assume good intent and give actionable feedback.
+- Focus on technical substance instead of personal attacks.
+- Help keep the project useful for a broad developer audience.
+
+## Unacceptable Behavior
+
+- Harassment, discrimination, or hateful conduct
+- Threats, intimidation, or doxxing
+- Spam, trolling, or intentionally disruptive behavior
+- Sharing private information without permission
+
+## Enforcement
+
+Maintainers may edit or remove content, close discussions, or restrict access
+when behavior harms the project or its contributors.
+
+To report a problem, email `team@knowhereto.ai` with:
+
+- the repository name
+- a link or screenshot if available
+- a short description of what happened

knowhere_python_sdk-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thanks for contributing to the Knowhere Python SDK.
+
+## Development Setup
+
+Requirements:
+
+- Python 3.9+
+- `uv`
+
+Clone the repository and install the full development environment:
+
+```bash
+uv sync --all-extras
+```
+
+## Local Checks
+
+Run these commands before opening a pull request:
+
+```bash
+uv run ruff check src/
+uv run mypy src/knowhere
+uv run pytest -q
+```
+
+If you change public behavior, also update the relevant documentation in:
+
+- `README.md`
+- `docs/usage.md`
+- `examples/`
+
+## Pull Requests
+
+Please keep pull requests focused and easy to review.
+
+Recommended checklist:
+
+1. Add or update tests for behavior changes.
+2. Keep public types and examples in sync with the implementation.
+3. Document any breaking or user-visible changes in the pull request description.
+
+Maintainers handle versioning and release automation through GitHub Actions.

knowhere_python_sdk-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knowhere Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: knowhere-python-sdk
-Version: 0.3.0
+Version: 0.3.2
 Summary: Official Python SDK for the Knowhere document parsing API
 Project-URL: Homepage, https://knowhereto.ai
 Project-URL: Documentation, https://docs.knowhereto.ai
 Project-URL: Repository, https://github.com/Ontos-AI/knowhere-python-sdk
 Author-email: Knowhere Team <team@knowhereto.ai>
 License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -67,8 +68,9 @@ for chunk in result.text_chunks:
 ## Retrieval and document lifecycle
 
 New documents are published into a retrieval namespace. The server returns a
-stable `document_id` when you create a job; persist that value if you need to
-update or archive the same document later.
+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(
@@ -77,7 +79,11 @@ job = client.jobs.create(
     namespace="support-center",
 )
 
-print(job.document_id)  # "doc_..."
+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:
@@ -87,8 +93,13 @@ 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)
@@ -101,13 +112,13 @@ Use `document_id` to update or archive a document:
 update_job = client.jobs.create(
     source_type="url",
     source_url="https://example.com/manual-v2.pdf",
-    document_id=job.document_id,
+    document_id=document_id,
 )
 
-document = client.documents.get(job.document_id)
+document = client.documents.get(document_id)
 print(document.status)
 
-client.documents.archive(job.document_id)
+client.documents.archive(document_id)
 ```
 
 You can also list documents in a namespace:
@@ -146,6 +157,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
@@ -209,14 +222,14 @@ job = client.jobs.create(
     parsing_params={"model": "advanced", "ocr_enabled": True},
 )
 
-print(job.document_id)  # Persist this to update/archive the document later.
-
 # Step 2: Upload file to presigned URL
 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)
@@ -293,6 +306,12 @@ We publish stable releases to [PyPI](https://pypi.org/project/knowhere-python-sd
 - [pydantic](https://docs.pydantic.dev/) `>=2.0.0,<3.0`
 - [typing-extensions](https://pypi.org/project/typing-extensions/) `>=4.7.0`
 
+## Community
+
+- Contributing guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Security policy: [SECURITY.md](./SECURITY.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
 ## License
 
 MIT

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

@@ -35,8 +35,9 @@ for chunk in result.text_chunks:
 ## Retrieval and document lifecycle
 
 New documents are published into a retrieval namespace. The server returns a
-stable `document_id` when you create a job; persist that value if you need to
-update or archive the same document later.
+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(
@@ -45,7 +46,11 @@ job = client.jobs.create(
     namespace="support-center",
 )
 
-print(job.document_id)  # "doc_..."
+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:
@@ -55,8 +60,13 @@ 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)
@@ -69,13 +79,13 @@ Use `document_id` to update or archive a document:
 update_job = client.jobs.create(
     source_type="url",
     source_url="https://example.com/manual-v2.pdf",
-    document_id=job.document_id,
+    document_id=document_id,
 )
 
-document = client.documents.get(job.document_id)
+document = client.documents.get(document_id)
 print(document.status)
 
-client.documents.archive(job.document_id)
+client.documents.archive(document_id)
 ```
 
 You can also list documents in a namespace:
@@ -114,6 +124,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
@@ -177,14 +189,14 @@ job = client.jobs.create(
     parsing_params={"model": "advanced", "ocr_enabled": True},
 )
 
-print(job.document_id)  # Persist this to update/archive the document later.
-
 # Step 2: Upload file to presigned URL
 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)
@@ -261,6 +273,12 @@ We publish stable releases to [PyPI](https://pypi.org/project/knowhere-python-sd
 - [pydantic](https://docs.pydantic.dev/) `>=2.0.0,<3.0`
 - [typing-extensions](https://pypi.org/project/typing-extensions/) `>=4.7.0`
 
+## Community
+
+- Contributing guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Security policy: [SECURITY.md](./SECURITY.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
 ## License
 
 MIT

knowhere_python_sdk-0.3.2/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest published release line is supported for security fixes.
+
+| Version | Supported |
+| --- | --- |
+| Latest release | Yes |
+| Older releases | No |
+
+## Reporting a Vulnerability
+
+Please do not open public GitHub issues for suspected vulnerabilities.
+
+Instead, email `team@knowhereto.ai` with:
+
+- the repository name
+- a clear description of the issue
+- reproduction steps or a proof of concept
+- impact assessment if known
+
+We will acknowledge the report, validate it, and coordinate remediation before
+public disclosure.

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

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

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

@@ -39,6 +39,9 @@ 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,
@@ -97,6 +100,9 @@ __all__: list[str] = [
     "Document",
     "DocumentListResponse",
     # Retrieval types
+    "RetrievalChannel",
+    "RetrievalFilterMode",
+    "RetrievalSectionExclusion",
     "RetrievalSource",
     "RetrievalQueryResponse",
     "RetrievalResult",

knowhere_python_sdk-0.3.2/src/knowhere/_version.py

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

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/src/knowhere/resources/jobs.py

@@ -145,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
@@ -154,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):
@@ -251,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
@@ -260,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_python_sdk-0.3.2/src/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_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/src/knowhere/types/__init__.py

@@ -6,6 +6,9 @@ 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,
@@ -38,6 +41,9 @@ __all__: list[str] = [
     "Document",
     "DocumentListResponse",
     # retrieval
+    "RetrievalChannel",
+    "RetrievalFilterMode",
+    "RetrievalSectionExclusion",
     "RetrievalSource",
     "RetrievalQueryResponse",
     "RetrievalResult",

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/src/knowhere/types/job.py

@@ -41,7 +41,6 @@ class Job(BaseModel):
     status: str
     source_type: str
     namespace: Optional[str] = None
-    document_id: Optional[str] = None
     data_id: Optional[str] = None
     created_at: Optional[datetime] = None
     upload_url: Optional[str] = None

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/src/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_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/src/knowhere/types/retrieval.py

@@ -2,11 +2,22 @@
 
 from __future__ import annotations
 
-from typing import Optional
+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."""
 
@@ -30,4 +41,5 @@ class RetrievalQueryResponse(BaseModel):
 
     namespace: str
     query: str
+    router_used: Optional[str] = None
     results: list[RetrievalResult]

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/tests/conftest.py

@@ -72,7 +72,6 @@ def mock_job_response() -> Dict[str, Any]:
         "status": "waiting-file",
         "source_type": "file",
         "namespace": "default",
-        "document_id": "doc_test123",
         "data_id": None,
         "created_at": "2025-01-01T00:00:00Z",
         "upload_url": "https://storage.example.com/upload?token=abc",

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/tests/test_jobs.py

@@ -36,7 +36,6 @@ class TestJobsCreate:
             "status": "pending",
             "source_type": "url",
             "namespace": "support-center",
-            "document_id": "doc_123",
         }
 
         route = respx.post(JOBS_URL).mock(
@@ -53,7 +52,7 @@ class TestJobsCreate:
         assert job.source_type == "url"
         assert job.status == "pending"
         assert job.namespace == "support-center"
-        assert job.document_id == "doc_123"
+        assert not hasattr(job, "document_id")
 
     @respx.mock
     def test_create_with_file_source(
@@ -87,7 +86,6 @@ class TestJobsCreate:
             "status": "pending",
             "source_type": "url",
             "namespace": "support-center",
-            "document_id": "doc_123",
         }
 
         route = respx.post(JOBS_URL).mock(
@@ -284,6 +282,8 @@ class TestJobsLoad:
             job_id="job_load",
             status="done",
             source_type="url",
+            namespace="support-center",
+            document_id="doc_123",
             result_url=result_url,
         )
 
@@ -293,3 +293,5 @@ class TestJobsLoad:
 
         assert route.called
         assert parse_result.manifest is not None
+        assert parse_result.namespace == "support-center"
+        assert parse_result.document_id == "doc_123"

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/tests/test_logging.py

@@ -18,7 +18,7 @@ class TestRedactSensitiveHeaders:
 
     def test_redacts_authorization_bearer(self) -> None:
         headers: Dict[str, str] = {
-            "Authorization": "Bearer sk_live_abc123xyz",
+            "Authorization": "Bearer sk_example_redacted_token",
             "Content-Type": "application/json",
         }
         redacted: Dict[str, str] = redactSensitiveHeaders(headers)

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/tests/test_models.py

@@ -55,7 +55,7 @@ class TestJobModel:
         }
         job: Job = Job(**data)
         assert job.namespace == "support-center"
-        assert job.document_id == "doc_123"
+        assert "document_id" not in job.model_dump()
 
     def test_from_dict_with_upload(self) -> None:
         data: Dict[str, Any] = {
@@ -717,6 +717,11 @@ class TestParseResult:
         assert stats.total_chunks == 3
         assert stats.text_chunks == 1
 
+    def test_document_scope_defaults_to_none(self) -> None:
+        result: ParseResult = _build_parse_result()
+        assert result.namespace is None
+        assert result.document_id is None
+
     def test_raw_zip_accessible(self) -> None:
         result: ParseResult = _build_parse_result()
         assert result.raw_zip == b"fake zip bytes"

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/tests/test_parse.py

@@ -42,6 +42,8 @@ def _make_done_response(job_id: str, result_url: str) -> Dict[str, Any]:
         "job_id": job_id,
         "status": "done",
         "source_type": "url",
+        "namespace": "support-center",
+        "document_id": "doc_123",
         "result_url": result_url,
     }
 
@@ -96,6 +98,8 @@ class TestParseWithUrl:
 
         assert parse_result.manifest is not None
         assert parse_result.manifest.job_id == "job_test123"
+        assert parse_result.namespace == "support-center"
+        assert parse_result.document_id == "doc_123"
 
 
 # ---------------------------------------------------------------------------

{knowhere_python_sdk-0.3.0 → knowhere_python_sdk-0.3.2}/tests/test_retrieval.py

@@ -19,6 +19,7 @@ def _make_retrieval_response() -> Dict[str, Any]:
     return {
         "namespace": "support-center",
         "query": "refund policy",
+        "router_used": "discovery+agent",
         "results": [
             {
                 "chunk_type": "text",
@@ -47,6 +48,14 @@ class TestRetrievalQuery:
             query="refund policy",
             namespace="support-center",
             top_k=5,
+            data_type=6,
+            signal_paths=["Billing", "Refunds"],
+            filter_mode="keep",
+            channels=["path", "term"],
+            channel_weights={"path": 2.0, "term": 0.5},
+            rerank=True,
+            threshold=0.2,
+            internal_recall_k=25,
             exclude_document_ids=["doc_old"],
             exclude_sections=[
                 {
@@ -62,6 +71,14 @@ class TestRetrievalQuery:
             "query": "refund policy",
             "namespace": "support-center",
             "top_k": 5,
+            "data_type": 6,
+            "signal_paths": ["Billing", "Refunds"],
+            "filter_mode": "keep",
+            "channels": ["path", "term"],
+            "channel_weights": {"path": 2.0, "term": 0.5},
+            "rerank": True,
+            "threshold": 0.2,
+            "internal_recall_k": 25,
             "exclude_document_ids": ["doc_old"],
             "exclude_sections": [
                 {
@@ -71,6 +88,7 @@ class TestRetrievalQuery:
             ],
         }
         assert response.namespace == "support-center"
+        assert response.router_used == "discovery+agent"
         assert response.results[0].content == "Annual plans may be refunded within 30 days."
         assert response.results[0].source.document_id == "doc_123"
         assert response.results[0].source.source_file_name == "refund-policy.md"
@@ -107,4 +125,5 @@ class TestRetrievalQuery:
         )
 
         assert route.called
+        assert response.router_used == "discovery+agent"
         assert response.results[0].source.document_id == "doc_123"

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

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

knowhere_python_sdk-0.3.0/src/knowhere/_version.py

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

knowhere_python_sdk-0.3.0/src/knowhere/resources/retrieval.py

@@ -1,70 +0,0 @@
-"""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 RetrievalQueryResponse
-
-
-class Retrieval(SyncAPIResource):
-    """Synchronous interface for ``/v1/retrieval`` endpoints."""
-
-    def query(
-        self,
-        *,
-        query: str,
-        namespace: Optional[str] = None,
-        top_k: Optional[int] = None,
-        exclude_document_ids: Optional[list[str]] = None,
-        exclude_sections: Optional[list[dict[str, str]]] = 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 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,
-        exclude_document_ids: Optional[list[str]] = None,
-        exclude_sections: Optional[list[dict[str, str]]] = 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 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,
-        )