knowhere-python-sdk 0.1.0__tar.gz → 0.2.1__tar.gz

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

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

knowhere_python_sdk-0.2.1/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## [0.2.1](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.2.0...v0.2.1) (2026-04-09)
+
+
+### Bug Fixes
+
+* narrow status error constructors ([c8fc035](https://github.com/Ontos-AI/knowhere-python-sdk/commit/c8fc035dade768c5364e50de890bde0fb280586e))
+* remove stale mypy ignore ([150336a](https://github.com/Ontos-AI/knowhere-python-sdk/commit/150336a5dc0497b287437dffa6e1506f4bcf8fbf))
+* sync optimized parse result payload ([a7903ad](https://github.com/Ontos-AI/knowhere-python-sdk/commit/a7903ad53fb5ab142c5835134c9a942eb5cdfe21))
+* sync parse result payload with current API schema ([430b067](https://github.com/Ontos-AI/knowhere-python-sdk/commit/430b067b37ce0b2eb8bd3c81cfca56b1df657376))
+
+## [0.2.0](https://github.com/Ontos-AI/knowhere-python-sdk/compare/v0.1.0...v0.2.0) (2026-03-18)
+
+
+### Features
+
+* ehance retry logic and exceptions handling ([a7d078f](https://github.com/Ontos-AI/knowhere-python-sdk/commit/a7d078f4d7ddfb6c9d07e12b809f5ee06a484c98))
+* implement retry logic for file uploads and introduce `ValidationError` for client input validation. ([1fddae6](https://github.com/Ontos-AI/knowhere-python-sdk/commit/1fddae6275cb36e8382128abe4616de93183eae8))
+
+
+### Bug Fixes
+
+* accept token lists in parse results ([192dac9](https://github.com/Ontos-AI/knowhere-python-sdk/commit/192dac922826b5e7372e311467624e96a004f446))
+* accept token lists in parse results ([4dc1407](https://github.com/Ontos-AI/knowhere-python-sdk/commit/4dc1407da9246984006368471c3bfb8cccc89b70))
+
+
+### Chores
+
+* remove plan doc ([9e4595e](https://github.com/Ontos-AI/knowhere-python-sdk/commit/9e4595e7da4015d2e5ea6b86c9ea64f76d70714c))
+* remove plan doc ([4228bfb](https://github.com/Ontos-AI/knowhere-python-sdk/commit/4228bfb0d2c90b0745404bd10ed16bf2dc4a72e0))
+* update readme ([aa426f3](https://github.com/Ontos-AI/knowhere-python-sdk/commit/aa426f33b52b95138280014cd9efa32c54e9672c))
+* update readme ([9f900a0](https://github.com/Ontos-AI/knowhere-python-sdk/commit/9f900a06cf42d1b7de522d34d4672ba977f23cc6))
+
+
+### Documentation
+
+* add usage ([bbbe6c3](https://github.com/Ontos-AI/knowhere-python-sdk/commit/bbbe6c3daf8538ae09ff3a93fa4a3c8a37d9cf55))
+* add usage ([6832dfe](https://github.com/Ontos-AI/knowhere-python-sdk/commit/6832dfe2afc2e46f32247a9c406fd5f42a480740))
+
+
+### Refactors
+
+* require list tokens in parse results ([663491c](https://github.com/Ontos-AI/knowhere-python-sdk/commit/663491cc6e74bead085587cf0fa0d8fe49ec292c))
+
+## 0.1.0 (2026-02-11)
+
+
+### Features
+
+* knowhere python SDK ([6363b60](https://github.com/Ontos-AI/knowhere-python-sdk/commit/6363b603372e9bb431e0386daf0f6fb0b5fc999b))

{knowhere_python_sdk-0.1.0 → knowhere_python_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowhere-python-sdk
-Version: 0.1.0
+Version: 0.2.1
 Summary: Official Python SDK for the Knowhere document parsing API
 Project-URL: Homepage, https://knowhereto.ai
 Project-URL: Documentation, https://docs.knowhereto.ai
@@ -32,38 +32,41 @@ Description-Content-Type: text/markdown
 
 # Knowhere Python SDK
 
+[![PyPI version](https://img.shields.io/pypi/v/knowhere-python-sdk.svg)](https://pypi.org/project/knowhere-python-sdk/)
+
 Official Python SDK for the [Knowhere](https://knowhereto.ai) document parsing API.
 
 ## Installation
 
-```bash
+```sh
 pip install knowhere-python-sdk
 ```
 
 Or with [uv](https://docs.astral.sh/uv/):
 
-```bash
+```sh
 uv add knowhere-python-sdk
 ```
 
-## Quick Start
+## Usage
 
 ```python
 import knowhere
 
 client = knowhere.Knowhere(api_key="sk_...")
 
-# Parse a document from URL
 result = client.parse(url="https://example.com/report.pdf")
 
-print(result.statistics.total_chunks)  # 152
-print(result.full_markdown[:200])      # First 200 chars of full markdown
+print(result.statistics.total_chunks)
+print(result.full_markdown[:200])
 
 for chunk in result.text_chunks:
     print(chunk.content[:80])
 ```
 
-### Parse a Local File
+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
 
 ```python
 from pathlib import Path
@@ -77,7 +80,7 @@ print(result.manifest.source_file_name)  # "report.pdf"
 print(len(result.chunks))                # 152
 ```
 
-### Access Different Chunk Types
+### Access different chunk types
 
 ```python
 result = client.parse(url="https://example.com/report.pdf")
@@ -99,14 +102,14 @@ for chunk in result.table_chunks:
     print(chunk.html[:100])
 ```
 
-### Save All Results to Disk
+### Save all results to disk
 
 ```python
 result = client.parse(file=Path("report.pdf"))
 result.save("./output/report/")
 ```
 
-## Async Usage
+## Async usage
 
 ```python
 import asyncio
@@ -123,7 +126,7 @@ async def main():
 asyncio.run(main())
 ```
 
-## Step-by-Step Control
+## Step-by-step control
 
 For granular control over the parsing workflow, use the `jobs` resource directly:
 
@@ -148,6 +151,22 @@ result = client.jobs.load(job_result)
 print(result.statistics)
 ```
 
+## Handling errors
+
+All errors inherit from `knowhere.KnowhereError`.
+
+
+```python
+import knowhere
+
+try:
+    result = client.parse(url="https://example.com/report.pdf")
+except knowhere.AuthenticationError:
+    print("Invalid API key")
+except knowhere.APIStatusError as e:
+    print(f"{e.status_code}: {e.message}")
+```
+
 ## Configuration
 
 The SDK reads configuration from constructor arguments, environment variables, or defaults (in that priority order):
@@ -172,50 +191,30 @@ client = knowhere.Knowhere(
 )
 ```
 
-### Context Manager
+### Retries
 
-```python
-# Sync — ensures httpx.Client is properly closed
-with knowhere.Knowhere(api_key="sk_...") as client:
-    result = client.parse(url="https://example.com/report.pdf")
+Connection errors, 429 Rate Limit, and >=500 Internal errors are automatically retried with exponential backoff.
 
-# Async — ensures httpx.AsyncClient is properly closed
-async with knowhere.AsyncKnowhere(api_key="sk_...") as client:
-    result = await client.parse(url="https://example.com/report.pdf")
+```python
+client = knowhere.Knowhere(
+    api_key="sk_...",
+    max_retries=3,  # default is 5
+)
 ```
 
-## Error Handling
+### Determining the installed version
 
 ```python
-from knowhere import (
-    Knowhere,
-    AuthenticationError,
-    NotFoundError,
-    RateLimitError,
-    BadRequestError,
-    APIStatusError,
-    PollingTimeoutError,
-)
-
-try:
-    result = client.parse(url="https://example.com/report.pdf")
-except BadRequestError as e:
-    print(e.status_code)   # 400
-    print(e.code)          # "INVALID_ARGUMENT"
-    print(e.message)       # "Unsupported file format"
-    print(e.request_id)    # "req_abc123"
-except NotFoundError as e:
-    print(e.message)       # "Job not found"
-except RateLimitError as e:
-    print(e.retry_after)   # seconds to wait
-except AuthenticationError:
-    print("Invalid API key")
-except PollingTimeoutError:
-    print("Job did not complete within timeout")
-except APIStatusError as e:
-    print(f"API error {e.status_code}: {e.message}")
+import knowhere
+print(knowhere.__version__)
 ```
 
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/).
+
+We publish stable releases to [PyPI](https://pypi.org/project/knowhere-python-sdk/). To install the latest unreleased changes directly from the repository: https://github.com/Ontos-AI/knowhere-python-sdk
+
 ## Requirements
 
 - Python 3.9+
@@ -223,92 +222,6 @@ except APIStatusError as e:
 - [pydantic](https://docs.pydantic.dev/) `>=2.0.0,<3.0`
 - [typing-extensions](https://pypi.org/project/typing-extensions/) `>=4.7.0`
 
-## Building from Source
-
-### Prerequisites
-
-- Python 3.9 or later
-- [uv](https://docs.astral.sh/uv/) (recommended) or pip
-
-### Build
-
-```bash
-git clone https://github.com/Ontos-AI/knowhere-python-sdk.git
-cd knowhere-python-sdk
-
-# Install uv if you don't have it
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# Build sdist + wheel
-uv build
-
-# Install the built wheel
-pip install dist/knowhere_python_sdk-*.whl
-```
-
-## Development
-
-### Setup
-
-```bash
-git clone https://github.com/Ontos-AI/knowhere-python-sdk.git
-cd knowhere-python-sdk
-
-# Create venv and install all dependencies (including dev)
-uv sync --all-extras
-```
-
-### Running Tests
-
-```bash
-# Run all unit tests
-uv run pytest tests/ -v
-
-# Run with coverage
-uv run coverage run -m pytest tests/ -v
-uv run coverage report -m
-```
-
-### Linting and Type Checking
-
-```bash
-# Lint
-uv run ruff check src/
-
-# Type check
-uv run mypy src/knowhere/
-```
-
-### Project Structure
-
-```
-knowhere-python-sdk/
-├── src/knowhere/
-│   ├── __init__.py              # Public API surface
-│   ├── _client.py               # Knowhere + AsyncKnowhere clients
-│   ├── _base_client.py          # HTTP logic, retry, error parsing
-│   ├── _exceptions.py           # Exception hierarchy
-│   ├── _constants.py            # Default URLs, timeouts, env var names
-│   ├── _types.py                # Sentinel types, callback type aliases
-│   ├── _logging.py              # Logger setup, header redaction
-│   ├── _response.py             # APIResponse wrapper
-│   ├── _version.py              # __version__
-│   ├── py.typed                 # PEP 561 marker
-│   ├── types/
-│   │   ├── job.py               # Job, JobResult, JobError
-│   │   ├── result.py            # ParseResult, Manifest, Chunk types
-│   │   └── params.py            # ParsingParams, WebhookConfig
-│   ├── resources/
-│   │   └── jobs.py              # Jobs + AsyncJobs resource
-│   └── lib/
-│       ├── polling.py           # Adaptive polling loop
-│       ├── upload.py            # Streaming file upload
-│       └── result_parser.py     # ZIP parsing, checksum verification
-├── tests/                       # Unit tests (respx-mocked HTTP)
-├── examples/                    # Usage examples
-└── pyproject.toml
-```
-
 ## License
 
 MIT

knowhere_python_sdk-0.2.1/README.md

@@ -0,0 +1,195 @@
+# Knowhere Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/knowhere-python-sdk.svg)](https://pypi.org/project/knowhere-python-sdk/)
+
+Official Python SDK for the [Knowhere](https://knowhereto.ai) document parsing API.
+
+## Installation
+
+```sh
+pip install knowhere-python-sdk
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv add knowhere-python-sdk
+```
+
+## Usage
+
+```python
+import knowhere
+
+client = knowhere.Knowhere(api_key="sk_...")
+
+result = client.parse(url="https://example.com/report.pdf")
+
+print(result.statistics.total_chunks)
+print(result.full_markdown[:200])
+
+for chunk in result.text_chunks:
+    print(chunk.content[:80])
+```
+
+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
+
+```python
+from pathlib import Path
+
+result = client.parse(
+    file=Path("report.pdf"),
+    parsing_params={"model": "advanced", "ocr_enabled": True},
+)
+
+print(result.manifest.source_file_name)  # "report.pdf"
+print(len(result.chunks))                # 152
+```
+
+### Access different chunk types
+
+```python
+result = client.parse(url="https://example.com/report.pdf")
+
+# Text chunks
+for chunk in result.text_chunks:
+    print(chunk.keywords)
+    print(chunk.summary)
+
+# Image chunks (raw bytes loaded from ZIP)
+for chunk in result.image_chunks:
+    print(chunk.file_path)
+    print(len(chunk.data))       # bytes
+    chunk.save("./output/")      # writes image to disk
+
+# Table chunks (HTML loaded from ZIP)
+for chunk in result.table_chunks:
+    print(chunk.file_path)
+    print(chunk.html[:100])
+```
+
+### Save all results to disk
+
+```python
+result = client.parse(file=Path("report.pdf"))
+result.save("./output/report/")
+```
+
+## Async usage
+
+```python
+import asyncio
+import knowhere
+
+async def main():
+    async with knowhere.AsyncKnowhere(api_key="sk_...") as client:
+        result = await client.parse(url="https://example.com/report.pdf")
+        print(result.statistics.total_chunks)
+
+        for chunk in result.text_chunks:
+            print(chunk.summary)
+
+asyncio.run(main())
+```
+
+## Step-by-step control
+
+For granular control over the parsing workflow, use the `jobs` resource directly:
+
+```python
+from pathlib import Path
+
+# Step 1: Create a parsing job
+job = client.jobs.create(
+    source_type="file",
+    file_name="report.pdf",
+    parsing_params={"model": "advanced", "ocr_enabled": True},
+)
+
+# 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)
+
+# Step 4: Download and parse results
+result = client.jobs.load(job_result)
+print(result.statistics)
+```
+
+## Handling errors
+
+All errors inherit from `knowhere.KnowhereError`.
+
+
+```python
+import knowhere
+
+try:
+    result = client.parse(url="https://example.com/report.pdf")
+except knowhere.AuthenticationError:
+    print("Invalid API key")
+except knowhere.APIStatusError as e:
+    print(f"{e.status_code}: {e.message}")
+```
+
+## Configuration
+
+The SDK reads configuration from constructor arguments, environment variables, or defaults (in that priority order):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KNOWHERE_API_KEY` | API key (required) | — |
+| `KNOWHERE_BASE_URL` | API base URL | `https://api.knowhereto.ai` |
+| `KNOWHERE_LOG_LEVEL` | Log level | `WARNING` |
+
+```python
+# Uses environment variables automatically
+client = knowhere.Knowhere()
+
+# Or configure explicitly
+client = knowhere.Knowhere(
+    api_key="sk_...",
+    base_url="https://api.knowhereto.ai",
+    timeout=30.0,           # HTTP request timeout (default: 60s)
+    upload_timeout=300.0,   # File upload timeout (default: 600s)
+    max_retries=3,          # Max retry attempts (default: 5)
+)
+```
+
+### Retries
+
+Connection errors, 429 Rate Limit, and >=500 Internal errors are automatically retried with exponential backoff.
+
+```python
+client = knowhere.Knowhere(
+    api_key="sk_...",
+    max_retries=3,  # default is 5
+)
+```
+
+### Determining the installed version
+
+```python
+import knowhere
+print(knowhere.__version__)
+```
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/).
+
+We publish stable releases to [PyPI](https://pypi.org/project/knowhere-python-sdk/). To install the latest unreleased changes directly from the repository: https://github.com/Ontos-AI/knowhere-python-sdk
+
+## Requirements
+
+- Python 3.9+
+- [httpx](https://www.python-httpx.org/) `>=0.25.0,<1.0`
+- [pydantic](https://docs.pydantic.dev/) `>=2.0.0,<3.0`
+- [typing-extensions](https://pypi.org/project/typing-extensions/) `>=4.7.0`
+
+## License
+
+MIT