Metadata-Version: 2.5
Name: titanocr
Version: 0.1.3
Summary: General-purpose OCR + document-structure engine: any PDF/image to text + structure with pixel-level provenance
Project-URL: Homepage, https://github.com/Phantom-IN/titanocr
Project-URL: Repository, https://github.com/Phantom-IN/titanocr
Project-URL: Issues, https://github.com/Phantom-IN/titanocr/issues
Author: TitanOCR
License-Expression: MIT
License-File: LICENSE
Keywords: document-ai,layout-analysis,ocr,pdf,table-extraction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing
Requires-Python: >=3.13
Requires-Dist: fastapi>=0.141
Requires-Dist: httpx>=0.28
Requires-Dist: numpy>=2.5
Requires-Dist: omegaconf==2.4.0.dev15
Requires-Dist: onnxruntime>=1.28
Requires-Dist: opencv-python-headless>=5
Requires-Dist: pdf-inspector>=1.14
Requires-Dist: pillow-heif>=1.5
Requires-Dist: pillow>=12
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: pydantic>=2.13
Requires-Dist: pypdfium2>=5.12
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: pyyaml>=6.0
Requires-Dist: rapid-layout==1.2.1
Requires-Dist: rapid-table==3.0.2
Requires-Dist: rapidocr>=3.9
Requires-Dist: uvicorn>=0.52
Description-Content-Type: text/markdown

# titanocr

**Deterministic, CPU-only OCR and document structure, with pixel-level provenance on every value.**

TitanOCR turns any PDF or image — born-digital, scanned or phone-photographed — into a
**Document IR**: pages, blocks, lines and table cells, where every piece of text carries its
bounding box, a confidence score and its origin (`digital`, `ocr` or `vlm`). Nothing is a bare
string, and nothing below threshold is presented as certain: low-confidence content is flagged
for review instead of guessed.

> **Early preview (0.1.x).** This package gives you the Document IR, the Markdown projection and
> the named-field lookup as a Python library. The OCR engine itself runs as a service today (see
> [Running the OCR engine](#running-the-ocr-engine)); running it in-process from `pip install`
> is planned. There is **no published accuracy claim** yet — the evaluation harness exists and
> the human-labelled benchmark is being built. The API may change before 1.0.

## Install

```bash
pip install titanocr
```

Requires Python 3.13+. One dependency is pinned to a pre-release (`omegaconf==2.4.0.dev15`, the
only build compatible with the OCR stack), which `pip` accepts as-is. With **uv**, allow it:

```bash
uv pip install titanocr --prerelease=allow
# or, in a uv project:
uv add titanocr --prerelease=allow
```

## What you can do with the package

### Load and validate a Document IR

The engine's output (`GET /v1/documents/{id}/ir`) is a JSON document validated by pydantic
models. Loading it gives you typed access and rejects anything that breaks the contract.

```python
from pathlib import Path

from titanocr.ir import DocumentIR

ir = DocumentIR.model_validate_json(Path("ir.json").read_text())
print(ir.ir_version, ir.page_count)
```

### Walk the text with its provenance

Blocks come in reading order; every line and table cell knows where it came from.

```python
for page in ir.pages:
    for block in sorted(page.blocks, key=lambda b: b.reading_order):
        for line in block.lines or ():
            # bbox: (x0, y0, x1, y1) in page pixels, origin top-left
            print(page.page_no, line.origin.value, line.confidence, line.bbox, line.text)
        if block.table:
            for cell in block.table.cells:
                print(cell.row, cell.col, cell.text)
```

Each page also carries its own confidence signals (`page.confidence.mean_rec`,
`p10_rec`, `text_coverage`, …) and the preprocessing it went through (`page.prep`), so a bbox
can be mapped back to the original upload.

### Render Markdown

A deterministic projection for display, diffing or feeding an LLM. Markdown is a *view* of the
IR — build extraction on the IR, not on the Markdown.

```python
from titanocr.render_md import ir_to_markdown

print(ir_to_markdown(ir))
```

### Look up named fields

A deterministic key → value lookup over a finished document (labelled pairs, table cells,
inline `Label: value` text). Every hit carries the rule that found it and its provenance; a miss
says why instead of guessing.

```python
from titanocr.fields import available_labels, extract_fields

print(available_labels(ir))                 # every label this document offers

result = extract_fields(ir, ["Invoice No", "Due Date"])
for hit in result.fields:
    print(hit.name, "->", hit.value, hit.strategy, hit.reason)

payload = result.as_json()                  # JSON-ready, with provenance per field
```

### Command-line tools

```bash
python -m titanocr.ir.validate ir.json      # exit 0 if valid, prints each violation if not
python -m titanocr.ir.schema schema.json    # export the IR as JSON Schema (for non-Python consumers)
```

## Running the OCR engine

The engine — PDF text-layer extraction, image preparation, PP-OCRv5 detection and recognition
on ONNX Runtime, layout, table reconstruction and triage — runs as an HTTP service with its
models pinned and checksummed. Run it from the repository:

```bash
git clone https://github.com/Phantom-IN/titanocr && cd titanocr
make setup && make models    # install, then fetch + verify the ONNX models
make dev                     # http://localhost:8000/demo
```

or as a container (`make docker-build`, then `docker compose up`). Upload a file, poll until it
is done, then fetch the IR:

```bash
curl -F file=@invoice.pdf http://localhost:8000/v1/documents          # → {"doc_id": ...}
curl http://localhost:8000/v1/documents/<doc_id>                       # status + per-page review_required
curl http://localhost:8000/v1/documents/<doc_id>/ir -o ir.json         # the Document IR
```

## Design in one paragraph

Transcription (which characters are where) is done by OCR on CPU — deterministic, cheap, and
checkable against a bounding box. Understanding what the text means is left to you, on text.
Born-digital pages are exact by construction; scanned pages get accuracy-first OCR; anything
below threshold is flagged `review_required`. A vision model is never the default path: it is
an opt-in escalation for the cropped regions the engine could not read, and it is off unless an
operator configures it. Re-running the same document with the same models produces the same
bytes.

## Links

- Source, design docs and roadmap: https://github.com/Phantom-IN/titanocr
- Document IR specification: https://github.com/Phantom-IN/titanocr/blob/main/docs/02-document-ir.md
- Issues: https://github.com/Phantom-IN/titanocr/issues

Licensed under MIT.
