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

knowhere_python_sdk-0.4.0/.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.4.0/.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.4.0/.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.4.0/.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.4.0/.release-please-manifest.json

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

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

@@ -1,5 +1,20 @@
 # 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)
+
+
+### 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)
 
 

knowhere_python_sdk-0.4.0/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.4.0/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.4.0/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.1 → knowhere_python_sdk-0.4.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: knowhere-python-sdk
-Version: 0.3.1
+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
 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
@@ -117,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)
 ```
 
@@ -305,6 +321,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.1 → 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)
 ```
 
@@ -273,6 +288,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.4.0/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.1 → 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.1 → knowhere_python_sdk-0.4.0}/pyproject.toml

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

{knowhere_python_sdk-0.3.1 → 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.1 → 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",