turboocr 0.1.0__tar.gz

turboocr-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.so
+.DS_Store
+.coverage
+htmlcov/
+site/

turboocr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiptimizer
+
+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.

turboocr-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: turboocr
+Version: 0.1.0
+Summary: Python SDK for TurboOCR — fast GPU OCR server (HTTP + gRPC)
+Project-URL: Homepage, https://turboocr.com
+Project-URL: Repository, https://github.com/aiptimizer/turboocr-python
+Project-URL: Issues, https://github.com/aiptimizer/turboocr-python/issues
+Project-URL: Server, https://github.com/aiptimizer/TurboOCR
+Author: turbo-ocr contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: layout,markdown,ocr,paddleocr,pdf,tensorrt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pypdf>=5.0
+Requires-Dist: reportlab>=4.2
+Requires-Dist: rich>=14
+Requires-Dist: typer>=0.15
+Provides-Extra: all
+Requires-Dist: grpcio>=1.66; extra == 'all'
+Requires-Dist: protobuf>=5.27; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.66; extra == 'dev'
+Requires-Dist: grpcio>=1.66; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: protobuf>=5.27; extra == 'dev'
+Requires-Dist: pypdfium2>=4.30; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mike>=2.1; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.66; extra == 'grpc'
+Requires-Dist: protobuf>=5.27; extra == 'grpc'
+Description-Content-Type: text/markdown
+
+# turboocr
+
+Typed Python client for the [TurboOCR](https://github.com/aiptimizer/TurboOCR) server.
+Sync + async, HTTP + gRPC, layout-aware Markdown rendering, searchable-PDF generation.
+
+[![PyPI](https://img.shields.io/pypi/v/turboocr.svg)](https://pypi.org/project/turboocr/)
+[![Python](https://img.shields.io/pypi/pyversions/turboocr.svg)](https://pypi.org/project/turboocr/)
+[![Typed](https://img.shields.io/badge/typed-PEP_561-blue.svg)](https://peps.python.org/pep-0561/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+- [Install](#install) · [Quickstart](#quickstart) · [What you get](#what-you-get)
+- [Examples](examples/) · [API reference](docs/) · [CLI](#cli) · [Errors](#errors)
+
+## Install
+
+```bash
+pip install turboocr             # HTTP client + CLI + searchable-PDF
+pip install 'turboocr[grpc]'     # add the gRPC transport
+pip install 'turboocr[all]'      # everything optional (currently == [grpc])
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+Start a [TurboOCR](https://github.com/aiptimizer/TurboOCR) server (the C++/CUDA
+OCR engine — this repo is just the Python client):
+
+```bash
+docker run --gpus all -p 8000:8000 -p 50051:50051 \
+  -v trt-cache:/home/ocr/.cache/turbo-ocr \
+  -e OCR_LANG=latin \
+  ghcr.io/aiptimizer/turboocr:v2.2.3
+```
+
+`OCR_LANG=latin` (default) covers English, French, German, Spanish, …. Swap for
+`chinese`, `greek`, `eslav`, `arabic`, `korean`, or `thai` — all are baked in.
+See the [TurboOCR repo](https://github.com/aiptimizer/TurboOCR) for build-from-source,
+benchmarks, and the full set of server env vars.
+
+Then recognise an image and turn a PDF into Markdown:
+
+```python
+from turboocr import Client, render_to_markdown
+
+with Client(base_url="http://localhost:8000") as client:
+    # Image OCR
+    img = client.recognize_image("page.png", layout=True, include_blocks=True)
+    print(f"{len(img.results)} text items, {len(img.blocks)} blocks")
+    print(img.text)
+
+    # PDF → Markdown
+    pdf = client.recognize_pdf("paper.pdf", dpi=150, include_blocks=True)
+    print(render_to_markdown(pdf).markdown)
+
+    # Searchable PDF (invisible text overlay)
+    overlay = client.make_searchable_pdf("scan.pdf", dpi=200)
+    open("scan.searchable.pdf", "wb").write(overlay)
+```
+
+That's the 80% case. Full runnable examples for async, gRPC, batch, retries,
+custom `httpx.Client`, hooks, Markdown styling, folder pipelines, and more live
+in [`examples/`](examples/) — every script runs end-to-end against the bundled
+ACME invoice fixture.
+
+## What you get
+
+- **Sync + async, HTTP + gRPC.** Four clients (`Client`, `AsyncClient`,
+  `GrpcClient`, `AsyncGrpcClient`) with identical method surfaces.
+- **Typed, immutable responses (pydantic v2).** IDE autocomplete, and if a newer
+  server adds a field your SDK doesn't know about, parsing still succeeds — the
+  extra lands on `.model_extra` instead of crashing.
+- **Layout-aware Markdown.** `render_to_markdown(...)` walks the reading order
+  and maps each layout class (`doc_title`, `display_formula`, `table`, …) to a
+  Markdown construct. Pluggable via `MarkdownStyle`.
+- **Searchable PDFs.** `make_searchable_pdf(...)` overlays an invisible text
+  layer aligned to the page geometry. Auto-discovers a Unicode font for
+  non-Latin scripts, or pass `font_path=`.
+- **Production-friendly.** Configurable retry policy (HTTP status + gRPC status
+  + `Retry-After`), per-request timeouts, custom `httpx.Client`, `on_request` /
+  `on_response` event hooks, uuid7 `X-Request-ID` per call.
+- **Precise exception hierarchy.** Maps the server's `error_code` to typed
+  exceptions — see [Errors](#errors).
+- **`turbo-ocr` CLI** included in the default install.
+
+Today's server does plain OCR + layout classification. Table-structure and
+LaTeX-formula source are **not** yet emitted; the SDK exposes `page.tables` /
+`page.formulas` as a forward-compatible surface that populates automatically
+when those server features ship.
+
+## Configuration
+
+```python
+from turboocr import Client, RetryPolicy
+
+client = Client(
+    base_url="http://localhost:8000",   # or TURBO_OCR_BASE_URL env
+    api_key="sk-...",                   # or TURBO_OCR_API_KEY env
+    auth_scheme="bearer",               # "bearer" | "x-api-key"
+    timeout=30.0,
+    default_headers={"X-Tenant": "acme"},
+    retry=RetryPolicy(attempts=5, backoff=0.5),
+)
+```
+
+Pass `http_client=httpx.Client(...)` for custom TLS, connection limits, or
+proxies — see [`examples/08_custom_httpx_client.py`](examples/08_custom_httpx_client.py).
+
+Retry defaults: HTTP `{429, 502, 503, 504}`, gRPC
+`{UNAVAILABLE, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED}`, 3 attempts, exponential
+backoff + jitter, `Retry-After` honoured. Tune via `RetryPolicy(...)` — see
+[`examples/07_retry_and_timeout.py`](examples/07_retry_and_timeout.py).
+
+## Errors
+
+```
+TurboOcrError
+├── APIConnectionError       # transport-level
+│   ├── Timeout
+│   ├── NetworkError
+│   └── ProtocolError
+├── InvalidParameter         # 4xx: bad params / headers / dims
+├── EmptyBody                # 4xx: empty body / batch / PDF
+├── LayoutDisabled           # asked for layout when server has it off
+├── ImageDecodeError         # bad bytes / bad base64
+├── DimensionsTooLarge       # image / PDF over server limits
+├── PoolExhausted            # "Server at capacity"
+├── PdfRenderError           # PDF rasterization failed
+└── ServerError              # 5xx, no specific code
+```
+
+Server-side exceptions carry `.code`, `.status_code`, and `.payload`. Transport
+exceptions inherit from `APIConnectionError`.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `NetworkError: Connection refused` | server not running | start the docker container (above) |
+| `DimensionsTooLarge` | image > `MAX_IMAGE_DIM` (default 16384) | downscale, or raise the server limit |
+| `LayoutDisabled` | server started with `DISABLE_LAYOUT=1` | restart without that env var |
+| `UnicodeFontRequired` | non-Latin text, no Unicode font found | pass `font_path=` or set `TURBO_OCR_FONT` |
+| `PoolExhausted` | server queue full | retry with backoff, or scale `PIPELINE_POOL_SIZE` |
+| `Timeout` | per-request timeout hit | pass `timeout=N`, or raise `RetryPolicy.attempts` |
+
+## CLI
+
+```bash
+turbo-ocr ocr page.png --output markdown
+turbo-ocr pdf doc.pdf --dpi 150 --output json
+turbo-ocr searchable-pdf doc.pdf -o out.pdf --font-path /path/to/font.ttf
+turbo-ocr health --ready
+```
+
+`--output` accepts `json | blocks | text | markdown`. Reads `TURBO_OCR_BASE_URL`,
+`TURBO_OCR_API_KEY`, `TURBO_OCR_FONT` from the environment. Run
+`turbo-ocr --help` for the full surface.
+
+## Logging
+
+```python
+import logging
+logging.getLogger("turboocr").setLevel(logging.DEBUG)
+```
+
+Emits `method path -> status (Xms) [req=<short-id>]` per HTTP request. Retry
+warnings go to `turboocr.retry` / `turboocr.grpc.retry`. Searchable-PDF font
+resolution logs to `turboocr.searchable_pdf`. Every HTTP request sends a uuid7
+`X-Request-ID` header (gRPC uses `x-request-id` metadata).
+
+## Learn more
+
+- [`examples/`](examples/) — 13 runnable scripts (each runs against the bundled
+  ACME invoice fixture, no server config needed beyond `TURBO_OCR_BASE_URL`)
+- [`docs/`](docs/) — full docs source (MkDocs + mkdocstrings, deployed at
+  https://aiptimizer.github.io/turboocr-python/). Preview locally with
+  `uv run --extra docs mkdocs serve -f docs/mkdocs.yml`
+- Server compatibility: `SERVER_API_VERSION_MIN` /
+  `SERVER_API_VERSION_MAX_EXCLUSIVE` document the supported server range;
+  `extra="allow"` on response models means additive server changes don't break
+  parsing
+
+## Testing
+
+```bash
+pytest -q                                                # offline (respx)
+TURBO_OCR_BASE_URL=http://localhost:8000 pytest tests/integration -v
+python examples/03_searchable_pdf.py                         # smoke test
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

turboocr-0.1.0/README.md

@@ -0,0 +1,191 @@
+# turboocr
+
+Typed Python client for the [TurboOCR](https://github.com/aiptimizer/TurboOCR) server.
+Sync + async, HTTP + gRPC, layout-aware Markdown rendering, searchable-PDF generation.
+
+[![PyPI](https://img.shields.io/pypi/v/turboocr.svg)](https://pypi.org/project/turboocr/)
+[![Python](https://img.shields.io/pypi/pyversions/turboocr.svg)](https://pypi.org/project/turboocr/)
+[![Typed](https://img.shields.io/badge/typed-PEP_561-blue.svg)](https://peps.python.org/pep-0561/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+- [Install](#install) · [Quickstart](#quickstart) · [What you get](#what-you-get)
+- [Examples](examples/) · [API reference](docs/) · [CLI](#cli) · [Errors](#errors)
+
+## Install
+
+```bash
+pip install turboocr             # HTTP client + CLI + searchable-PDF
+pip install 'turboocr[grpc]'     # add the gRPC transport
+pip install 'turboocr[all]'      # everything optional (currently == [grpc])
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+Start a [TurboOCR](https://github.com/aiptimizer/TurboOCR) server (the C++/CUDA
+OCR engine — this repo is just the Python client):
+
+```bash
+docker run --gpus all -p 8000:8000 -p 50051:50051 \
+  -v trt-cache:/home/ocr/.cache/turbo-ocr \
+  -e OCR_LANG=latin \
+  ghcr.io/aiptimizer/turboocr:v2.2.3
+```
+
+`OCR_LANG=latin` (default) covers English, French, German, Spanish, …. Swap for
+`chinese`, `greek`, `eslav`, `arabic`, `korean`, or `thai` — all are baked in.
+See the [TurboOCR repo](https://github.com/aiptimizer/TurboOCR) for build-from-source,
+benchmarks, and the full set of server env vars.
+
+Then recognise an image and turn a PDF into Markdown:
+
+```python
+from turboocr import Client, render_to_markdown
+
+with Client(base_url="http://localhost:8000") as client:
+    # Image OCR
+    img = client.recognize_image("page.png", layout=True, include_blocks=True)
+    print(f"{len(img.results)} text items, {len(img.blocks)} blocks")
+    print(img.text)
+
+    # PDF → Markdown
+    pdf = client.recognize_pdf("paper.pdf", dpi=150, include_blocks=True)
+    print(render_to_markdown(pdf).markdown)
+
+    # Searchable PDF (invisible text overlay)
+    overlay = client.make_searchable_pdf("scan.pdf", dpi=200)
+    open("scan.searchable.pdf", "wb").write(overlay)
+```
+
+That's the 80% case. Full runnable examples for async, gRPC, batch, retries,
+custom `httpx.Client`, hooks, Markdown styling, folder pipelines, and more live
+in [`examples/`](examples/) — every script runs end-to-end against the bundled
+ACME invoice fixture.
+
+## What you get
+
+- **Sync + async, HTTP + gRPC.** Four clients (`Client`, `AsyncClient`,
+  `GrpcClient`, `AsyncGrpcClient`) with identical method surfaces.
+- **Typed, immutable responses (pydantic v2).** IDE autocomplete, and if a newer
+  server adds a field your SDK doesn't know about, parsing still succeeds — the
+  extra lands on `.model_extra` instead of crashing.
+- **Layout-aware Markdown.** `render_to_markdown(...)` walks the reading order
+  and maps each layout class (`doc_title`, `display_formula`, `table`, …) to a
+  Markdown construct. Pluggable via `MarkdownStyle`.
+- **Searchable PDFs.** `make_searchable_pdf(...)` overlays an invisible text
+  layer aligned to the page geometry. Auto-discovers a Unicode font for
+  non-Latin scripts, or pass `font_path=`.
+- **Production-friendly.** Configurable retry policy (HTTP status + gRPC status
+  + `Retry-After`), per-request timeouts, custom `httpx.Client`, `on_request` /
+  `on_response` event hooks, uuid7 `X-Request-ID` per call.
+- **Precise exception hierarchy.** Maps the server's `error_code` to typed
+  exceptions — see [Errors](#errors).
+- **`turbo-ocr` CLI** included in the default install.
+
+Today's server does plain OCR + layout classification. Table-structure and
+LaTeX-formula source are **not** yet emitted; the SDK exposes `page.tables` /
+`page.formulas` as a forward-compatible surface that populates automatically
+when those server features ship.
+
+## Configuration
+
+```python
+from turboocr import Client, RetryPolicy
+
+client = Client(
+    base_url="http://localhost:8000",   # or TURBO_OCR_BASE_URL env
+    api_key="sk-...",                   # or TURBO_OCR_API_KEY env
+    auth_scheme="bearer",               # "bearer" | "x-api-key"
+    timeout=30.0,
+    default_headers={"X-Tenant": "acme"},
+    retry=RetryPolicy(attempts=5, backoff=0.5),
+)
+```
+
+Pass `http_client=httpx.Client(...)` for custom TLS, connection limits, or
+proxies — see [`examples/08_custom_httpx_client.py`](examples/08_custom_httpx_client.py).
+
+Retry defaults: HTTP `{429, 502, 503, 504}`, gRPC
+`{UNAVAILABLE, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED}`, 3 attempts, exponential
+backoff + jitter, `Retry-After` honoured. Tune via `RetryPolicy(...)` — see
+[`examples/07_retry_and_timeout.py`](examples/07_retry_and_timeout.py).
+
+## Errors
+
+```
+TurboOcrError
+├── APIConnectionError       # transport-level
+│   ├── Timeout
+│   ├── NetworkError
+│   └── ProtocolError
+├── InvalidParameter         # 4xx: bad params / headers / dims
+├── EmptyBody                # 4xx: empty body / batch / PDF
+├── LayoutDisabled           # asked for layout when server has it off
+├── ImageDecodeError         # bad bytes / bad base64
+├── DimensionsTooLarge       # image / PDF over server limits
+├── PoolExhausted            # "Server at capacity"
+├── PdfRenderError           # PDF rasterization failed
+└── ServerError              # 5xx, no specific code
+```
+
+Server-side exceptions carry `.code`, `.status_code`, and `.payload`. Transport
+exceptions inherit from `APIConnectionError`.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `NetworkError: Connection refused` | server not running | start the docker container (above) |
+| `DimensionsTooLarge` | image > `MAX_IMAGE_DIM` (default 16384) | downscale, or raise the server limit |
+| `LayoutDisabled` | server started with `DISABLE_LAYOUT=1` | restart without that env var |
+| `UnicodeFontRequired` | non-Latin text, no Unicode font found | pass `font_path=` or set `TURBO_OCR_FONT` |
+| `PoolExhausted` | server queue full | retry with backoff, or scale `PIPELINE_POOL_SIZE` |
+| `Timeout` | per-request timeout hit | pass `timeout=N`, or raise `RetryPolicy.attempts` |
+
+## CLI
+
+```bash
+turbo-ocr ocr page.png --output markdown
+turbo-ocr pdf doc.pdf --dpi 150 --output json
+turbo-ocr searchable-pdf doc.pdf -o out.pdf --font-path /path/to/font.ttf
+turbo-ocr health --ready
+```
+
+`--output` accepts `json | blocks | text | markdown`. Reads `TURBO_OCR_BASE_URL`,
+`TURBO_OCR_API_KEY`, `TURBO_OCR_FONT` from the environment. Run
+`turbo-ocr --help` for the full surface.
+
+## Logging
+
+```python
+import logging
+logging.getLogger("turboocr").setLevel(logging.DEBUG)
+```
+
+Emits `method path -> status (Xms) [req=<short-id>]` per HTTP request. Retry
+warnings go to `turboocr.retry` / `turboocr.grpc.retry`. Searchable-PDF font
+resolution logs to `turboocr.searchable_pdf`. Every HTTP request sends a uuid7
+`X-Request-ID` header (gRPC uses `x-request-id` metadata).
+
+## Learn more
+
+- [`examples/`](examples/) — 13 runnable scripts (each runs against the bundled
+  ACME invoice fixture, no server config needed beyond `TURBO_OCR_BASE_URL`)
+- [`docs/`](docs/) — full docs source (MkDocs + mkdocstrings, deployed at
+  https://aiptimizer.github.io/turboocr-python/). Preview locally with
+  `uv run --extra docs mkdocs serve -f docs/mkdocs.yml`
+- Server compatibility: `SERVER_API_VERSION_MIN` /
+  `SERVER_API_VERSION_MAX_EXCLUSIVE` document the supported server range;
+  `extra="allow"` on response models means additive server changes don't break
+  parsing
+
+## Testing
+
+```bash
+pytest -q                                                # offline (respx)
+TURBO_OCR_BASE_URL=http://localhost:8000 pytest tests/integration -v
+python examples/03_searchable_pdf.py                         # smoke test
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

turboocr-0.1.0/docs/api/cli.md

@@ -0,0 +1,68 @@
+# CLI — `turbo-ocr`
+
+The `turbo-ocr` command ships with the default install — no extras needed.
+
+```bash
+turbo-ocr ocr page.png --output markdown
+turbo-ocr pdf doc.pdf --dpi 150 --output json
+turbo-ocr searchable-pdf doc.pdf -o out.pdf --font-path /path/to/font.ttf
+turbo-ocr blocks doc.pdf
+turbo-ocr health --ready
+```
+
+## Commands
+
+### `turbo-ocr ocr <image>`
+
+Single-image OCR.
+
+| Option | Notes |
+|---|---|
+| `--output` | `json` (default) · `blocks` · `text` · `markdown` |
+| `--base-url` | env: `TURBO_OCR_BASE_URL` (default `http://localhost:8000`) |
+| `--api-key` | env: `TURBO_OCR_API_KEY` |
+| `--layout / --no-layout` | request layout (default on) |
+| `--reading-order` | request reading-order grouping |
+| `--include-blocks` | request reading-order-grouped paragraphs |
+
+### `turbo-ocr pdf <pdf>`
+
+PDF OCR.
+
+| Option | Notes |
+|---|---|
+| `--output` | `json` · `blocks` · `text` · `markdown` |
+| `--dpi` | rasterization DPI (default `150`) |
+| `--mode` | `ocr` · `text` · `auto` · `auto_verified` · `geometric` |
+| `--base-url`, `--api-key`, `--layout`, `--reading-order`, `--include-blocks` | as above |
+
+### `turbo-ocr searchable-pdf <pdf>`
+
+Generate a searchable PDF with an invisible text overlay.
+
+| Option | Notes |
+|---|---|
+| `-o`, `--out` | output PDF path (required) |
+| `--dpi` | rasterization DPI (default `200`) |
+| `--mode` | `ocr` · `text` · `auto` · `auto_verified` · `geometric` (default `ocr`) |
+| `--font-path` | TTF for non-Latin scripts; env: `TURBO_OCR_FONT` |
+| `--base-url`, `--api-key` | as above |
+
+### `turbo-ocr blocks <pdf>`
+
+Dump reading-order-grouped blocks as JSON (shortcut for
+`pdf --include-blocks --output blocks`).
+
+### `turbo-ocr health [--ready]`
+
+Probe `/healthz`; with `--ready`, also requires the pipeline to be ready.
+
+## Environment
+
+| Variable | Used by |
+|---|---|
+| `TURBO_OCR_BASE_URL` | every command — default `http://localhost:8000` |
+| `TURBO_OCR_API_KEY` | every command — sent as bearer or `X-API-Key` |
+| `TURBO_OCR_FONT` | `searchable-pdf` — TTF path for non-Latin scripts |
+
+Run `turbo-ocr <command> --help` for the live, authoritative option list.

turboocr-0.1.0/docs/api/clients.md

@@ -0,0 +1,17 @@
+# HTTP clients
+
+`Client` and `AsyncClient` share an identical method surface — anything you
+can do with one, you can `await` with the other.
+
+Construct either directly with `base_url`, from env vars with
+`Client.from_env()`, or pass a pre-built `httpx.Client` via `http_client=`.
+The introspection properties (`.base_url`, `.auth_scheme`, `.default_headers`,
+`.timeout`, `.retry`) read back the resolved config.
+
+## `Client`
+
+::: turboocr.Client
+
+## `AsyncClient`
+
+::: turboocr.AsyncClient

turboocr-0.1.0/docs/api/errors.md

@@ -0,0 +1,61 @@
+# Errors
+
+## Hierarchy
+
+```
+TurboOcrError
+├── APIConnectionError       # transport-level
+│   ├── Timeout
+│   ├── NetworkError
+│   └── ProtocolError
+├── InvalidParameter         # 4xx: bad params / headers / dims
+├── EmptyBody                # 4xx: empty body / batch / PDF
+├── LayoutDisabled           # asked for layout when server has it off
+├── ImageDecodeError         # bad bytes / bad base64
+├── DimensionsTooLarge       # image / PDF over server limits
+├── PoolExhausted            # "Server at capacity"
+├── PdfRenderError           # PDF rasterization failed
+└── ServerError              # 5xx, no specific code
+```
+
+Server-side exceptions carry `.code`, `.status_code`, and `.payload`. Transport
+exceptions inherit from `APIConnectionError`.
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `NetworkError: Connection refused` | server not running | start the docker container |
+| `DimensionsTooLarge` | image > `MAX_IMAGE_DIM` (default 16384) | downscale or raise the server limit |
+| `LayoutDisabled` | server started with `DISABLE_LAYOUT=1` | restart without that env var |
+| `UnicodeFontRequired` | non-Latin text, no Unicode font found | pass `font_path=` or set `TURBO_OCR_FONT` |
+| `PoolExhausted` | server queue full | retry with backoff, or scale `PIPELINE_POOL_SIZE` |
+| `Timeout` | per-request timeout hit | pass `timeout=N` or raise `RetryPolicy.attempts` |
+
+## Reference
+
+::: turboocr.TurboOcrError
+
+::: turboocr.APIConnectionError
+
+::: turboocr.NetworkError
+
+::: turboocr.Timeout
+
+::: turboocr.ProtocolError
+
+::: turboocr.InvalidParameter
+
+::: turboocr.EmptyBody
+
+::: turboocr.LayoutDisabled
+
+::: turboocr.ImageDecodeError
+
+::: turboocr.DimensionsTooLarge
+
+::: turboocr.PoolExhausted
+
+::: turboocr.PdfRenderError
+
+::: turboocr.ServerError

turboocr-0.1.0/docs/api/grpc.md

@@ -0,0 +1,22 @@
+# gRPC clients
+
+`GrpcClient` and `AsyncGrpcClient` mirror the HTTP clients over gRPC.
+Requires `pip install 'turboocr[grpc]'`.
+
+!!! warning "Two parity caveats"
+
+    - The gRPC proto's bool fields lack field presence (proto3 without
+      `optional`), so `None` is sent as `False`. Today the server defaults all
+      bool options to `False`, so behavior matches the HTTP client — if the
+      server ever flips a default, gRPC users would have to opt in explicitly.
+    - `GrpcClient.recognize_pdf(reading_order=True)` raises
+      `InvalidParameter` — the proto lacks the `reading_order` field. Use the
+      HTTP client for PDFs that need reading order.
+
+## `GrpcClient`
+
+::: turboocr.GrpcClient
+
+## `AsyncGrpcClient`
+
+::: turboocr.AsyncGrpcClient

turboocr-0.1.0/docs/api/layout.md

@@ -0,0 +1,43 @@
+# Layout, blocks, geometry
+
+## `Block`
+
+Reading-order-grouped paragraph with bounding box, layout class, and content.
+Emitted on the response when `include_blocks=True`.
+
+::: turboocr.Block
+
+## `TextItem`
+
+A single recognised word/line with confidence and bounding box.
+
+::: turboocr.TextItem
+
+## `BoundingBox`
+
+::: turboocr.BoundingBox
+
+## `LayoutBox`
+
+::: turboocr.LayoutBox
+
+## `LayoutLabel`
+
+::: turboocr.LayoutLabel
+
+## `Table`
+
+::: turboocr.Table
+
+## `Formula`
+
+::: turboocr.Formula
+
+!!! info "Tables and formulas — partial support today"
+
+    As of server v2.2.3, the server detects table and formula **regions** (you
+    get a `bounding_box` and row-major OCR'd `text`) but does **not** emit
+    cell structure or LaTeX source. `Table.html`, `Table.cells`, and
+    `Formula.latex` are always `None`. The SDK is forward-compatible: when the
+    server ships table-structure-recognition and LaTeX OCR, those fields will
+    populate without any SDK code changes.