Metadata-Version: 2.4
Name: german-ocr
Version: 0.5.0
Summary: High-performance German document OCR - Cloud API with Turbo, Pro and Ultra models
Author-email: Keyvan Hardani <hello@keyvan.ai>
Maintainer-email: Keyvan Hardani <hello@keyvan.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Keyvanhardani/german-ocr
Project-URL: Documentation, https://github.com/Keyvanhardani/german-ocr#readme
Project-URL: Repository, https://github.com/Keyvanhardani/german-ocr
Project-URL: Issues, https://github.com/Keyvanhardani/german-ocr/issues
Project-URL: Changelog, https://github.com/Keyvanhardani/german-ocr/releases
Keywords: ocr,german,document,invoice,text-extraction,dsgvo,cloud-api,document-ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: requests>=2.28.0
Provides-Extra: hf
Requires-Dist: torch>=2.0.0; extra == "hf"
Requires-Dist: transformers>=4.40.0; extra == "hf"
Requires-Dist: qwen-vl-utils>=0.0.10; extra == "hf"
Provides-Extra: all
Requires-Dist: german-ocr[hf]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="docs/logo-german-ocr.png" alt="German-OCR Logo" width="450"/>
</p>

<p align="center">
  <strong>High-performance German document OCR - Local & Cloud</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/german-ocr/"><img src="https://badge.fury.io/py/german-ocr.svg" alt="PyPI version"></a>
  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+"></a>
  <a href="https://app.german-ocr.de"><img src="https://img.shields.io/badge/Cloud-API-green" alt="Cloud API"></a>
</p>

---

## Features

| Feature | Local | Cloud |
|---------|-------|-------|
| **German Documents** | Invoices, contracts, forms | All document types |
| **Output Formats** | Markdown, JSON, text | JSON, Markdown, text, n8n |
| **PDF Support** | Images only | Up to 50 pages |
| **Privacy** | 100% local | DSGVO-konform (Frankfurt) |
| **Speed** | ~5s/page | ~2-3s/page |

## Installation

```bash
pip install german-ocr
```

## Quick Start

### Option 1: Cloud API (Recommended)

No GPU required. Get your API credentials at [app.german-ocr.de](https://app.german-ocr.de)

```python
from german_ocr import CloudClient

# API Key + Secret (Secret is only shown once at creation!)
client = CloudClient(
    api_key="gocr_xxxxxxxx",
    api_secret="your_64_char_secret_here"
)

# Simple extraction
result = client.analyze("invoice.pdf")
print(result.text)

# Structured JSON output
result = client.analyze(
    "invoice.pdf",
    prompt="Extrahiere Rechnungsnummer und Gesamtbetrag",
    output_format="json"
)
print(result.text)
```

### Option 2: Local (Ollama)

Requires [Ollama](https://ollama.ai) installed.

```bash
# Install model
ollama pull Keyvan/german-ocr-turbo
```

```python
from german_ocr import GermanOCR

ocr = GermanOCR()
text = ocr.extract("invoice.png")
print(text)
```

## Cloud Models

| Model | Parameter | Best For |
|-------|-----------|----------|
| **German-OCR Turbo** | `local` | DSGVO-konform, lokale Verarbeitung in DE |
| **German-OCR Pro** | `cloud_fast` | Balance aus Speed & Qualitat |
| **German-OCR Ultra** | `cloud` | Maximale Prazision, Strukturerkennung |

### Model Selection

```python
from german_ocr import CloudClient

client = CloudClient(
    api_key="gocr_xxxxxxxx",
    api_secret="your_64_char_secret_here"
)

# German-OCR Turbo - Lokal, DSGVO-konform
result = client.analyze("dokument.pdf", model="local")

# German-OCR Pro - Schnelle Cloud (Standard)
result = client.analyze("dokument.pdf", model="cloud_fast")

# German-OCR Ultra - Maximale Prazision
result = client.analyze("dokument.pdf", model="cloud")
```

## CLI Usage

### Cloud

```bash
# Set API credentials (Secret shown only once at creation!)
export GERMAN_OCR_API_KEY="gocr_xxxxxxxx"
export GERMAN_OCR_API_SECRET="your_64_char_secret_here"

# Extract text (uses German-OCR Pro by default)
german-ocr --cloud invoice.pdf

# Use German-OCR Turbo (DSGVO)
german-ocr --cloud --model local invoice.pdf

# JSON output with German-OCR Ultra
german-ocr --cloud --model cloud --output-format json invoice.pdf

# With custom prompt
german-ocr --cloud --prompt "Extrahiere alle Betraege" invoice.pdf
```

### Local

```bash
# Single image
german-ocr invoice.png

# Batch processing
german-ocr --batch ./invoices/

# JSON output
german-ocr --format json invoice.png
```

## Cloud API

### Output Formats

| Format | Description |
|--------|-------------|
| `text` | Plain text (default) |
| `json` | Structured JSON |
| `markdown` | Formatted Markdown |
| `n8n` | n8n-compatible format |

### Progress Tracking

```python
from german_ocr import CloudClient

client = CloudClient(
    api_key="gocr_xxxxxxxx",
    api_secret="your_64_char_secret"
)

def on_progress(status):
    print(f"Page {status.current_page}/{status.total_pages}")

result = client.analyze(
    "large_document.pdf",
    on_progress=on_progress
)
```

### Async Processing

```python
# Submit job with German-OCR Pro
job = client.submit("document.pdf", model="cloud_fast", output_format="json")
print(f"Job ID: {job.job_id}")

# Check status
status = client.get_job(job.job_id)
print(f"Status: {status.status}")

# Wait for result
result = client.wait_for_result(job.job_id)

# Cancel job
client.cancel_job(job.job_id)
```

### Account Info

```python
# Check balance
balance = client.get_balance()
print(f"Balance: {balance}")

# Usage statistics
usage = client.get_usage()
print(f"Usage: {usage}")
```

## Local Models

| Model | Size | Speed | Best For |
|-------|------|-------|----------|
| [german-ocr-turbo](https://ollama.com/Keyvan/german-ocr-turbo) | 1.9 GB | ~5s | Recommended |
| [german-ocr](https://ollama.com/Keyvan/german-ocr) | 3.2 GB | ~7s | Standard |

## Pricing

See current pricing at [app.german-ocr.de](https://app.german-ocr.de)

## License

Apache 2.0 - See [LICENSE](LICENSE) for details.

## Author

**Keyvan Hardani** - [keyvan.ai](https://keyvan.ai)

---

<p align="center">
  Made with love in Germany
</p>
