Metadata-Version: 2.4
Name: hn-deepocr-client
Version: 0.3.0
Summary: Haina Deep OCR API Client SDK
Project-URL: Homepage, https://github.com/yourusername/hn-deepocr-client
Project-URL: Documentation, https://github.com/yourusername/hn-deepocr-client#readme
Project-URL: Repository, https://github.com/yourusername/hn-deepocr-client.git
Project-URL: Issues, https://github.com/yourusername/hn-deepocr-client/issues
Author-email: Haina <support@haina.com>
License: MIT
License-File: LICENSE
Keywords: api,client,ocr,parser,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: requests>=2.32.5
Description-Content-Type: text/markdown

# HN Deep OCR Client

Python SDK for Haina Deep OCR API - PDF parsing and document processing made easy.

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

## Features

- PDF file upload with automatic chunking (configurable chunk size)
- Parsing status polling with optimized timeouts
- Multi-format result generation (ZIP, JSON, Markdown, Image, Formula, Table)
- **Dual algorithm support**: DeepOCR (default) and MinerU engines
- Comprehensive error handling with custom exception classes
- Built-in logging configuration
- Type hints for better IDE support
- Pydantic Settings for configuration management
- Connection pooling and HTTP session reuse
- Intelligent retry mechanism with exponential backoff
- Granular timeout configuration per operation type
- Full test coverage

## Installation

```bash
pip install hn-deepocr-client
```

Or using uv:

```bash
uv add hn-deepocr-client
```

## Quick Start

### 1. Get API Credentials

Apply for Access Key (AK) and Secret Key (SK) from [Haina Platform](https://mkxzg8.yuque.com/hoq002/ilbssv/qmgptn6gltudphik#LoSlF).

### 2. Configure Environment Variables

Create a `.env` file in your project root:

```env
AK=your_access_key_here
SK=your_secret_key_here
PRESIGNED_URL=https://open-sci-datahub.zero2x.org
```

Or use `.env.example` as a template:

```bash
cp .env.example .env
# Edit .env with your credentials
```

### 3. Basic Usage

```python
from hn_deepocr_client import ParserPDF, load_config

config = load_config()

parser = ParserPDF(
    ak=config.AK,
    sk=config.SK,
    presigned_url=config.PRESIGNED_URL,
)

# DeepOCR (default)
result = parser.start(
    file_name="document.pdf",
    file_path="./document.pdf",
)

print(f"Parse completed! DataID: {result['data_id']}")
print(f"Download URLs: {result['download_urls']}")
```

### 4. Using MinerU Algorithm

```python
# Use MinerU engine instead of DeepOCR
result = parser.start(
    file_name="document.pdf",
    file_path="./document.pdf",
    algorithm="mineru",
)

print(f"MinerU parse completed! DataID: {result['data_id']}")
for file_type, url in result.get("download_urls", {}).items():
    print(f"  {file_type}: {url}")
```

### Supported File Types by Algorithm

| File Type | Description | DeepOCR | MinerU |
|-----------|-------------|:-------:|:------:|
| `zip` | Full package (all results) | - | Yes |
| `json` | JSON format | Yes | Yes |
| `markdown` | Markdown (no images) | Yes | Yes |
| `md-figure` | Markdown (with images) | Yes | Yes |
| `figure` | Image files | Yes | Yes |
| `formula` | Formula files | Yes | - |
| `table` | Table files | Yes | - |

## Advanced Usage

### Logging Configuration

The SDK automatically initializes logging when creating a `ParserPDF` instance. By default, logs are written to both console and a rotating file (`logs/pdf_parser.log`).

**Customize log level via constructor:**

```python
import logging

parser = ParserPDF(
    ak=config.AK,
    sk=config.SK,
    presigned_url=config.PRESIGNED_URL,
    log_level=logging.DEBUG,       # or "DEBUG" string
    log_dir="custom_logs",
    log_file="my_app.log",
)
```

**Customize log level via environment variable (in `.env`):**

```env
LOG_LEVEL=DEBUG
LOG_DIR=logs
LOG_FILE=pdf_parser.log
```

Valid log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.

**Customize log level programmatically:**

```python
from hn_deepocr_client import init_logger

init_logger(log_level="DEBUG", log_dir="logs", log_file="app.log")
```

### Custom Configuration

```python
from hn_deepocr_client import ParserPDF, load_config, ConfigurationError

try:
    config = load_config()
    parser = ParserPDF(ak=config.AK, sk=config.SK, presigned_url=config.PRESIGNED_URL)
    data_id = parser.start("document.pdf", "./document.pdf")
except ConfigurationError as e:
    print(f"Configuration error: {e}")
except UploadError as e:
    print(f"Upload failed: {e}")
except ParseError as e:
    print(f"Parse failed: {e}")
```

### Generate Specific Formats Only

```python
# DeepOCR with custom file types
result = parser.start(
    "document.pdf", "./document.pdf",
    file_types=["json", "markdown"],
)

# MinerU with custom file types
result = parser.start(
    "document.pdf", "./document.pdf",
    algorithm="mineru",
    file_types=["zip", "markdown"],
)
```

### File Upload Validation

The SDK validates files before upload:

- `file_name` must match the basename of `file_path` (e.g., `file_name="doc.pdf"` with `file_path="./doc.pdf"`)
- Empty files (0 bytes) are rejected with a clear error message
- Only `.pdf` files are supported
- `part_size` must be between 1MB and 100MB (configurable via `HN_DEEP_OCR_PART_SIZE`)

### Direct API Usage

```python
from hn_deepocr_client import create_token

token = create_token(
    ak="your_ak",
    sk="your_sk",
    url="https://api.example.com/upload",
    request_body='{"file":"test.pdf"}',
)
```

## API Reference

### ParserPDF

Main class for PDF parsing operations.

#### Methods

- `__init__(ak, sk, presigned_url, config=None, http_client=None, log_level=None, log_dir="logs", log_file="pdf_parser.log")` - Initialize parser with optional logging configuration
- `start(file_name: str, file_path: str, generate_all_formats: bool = True, file_types: list[str] | None = None, parse_timeout: int = 1800, algorithm: str = "deepocr") -> dict` - Start full parsing workflow, returns `{"data_id": ..., "download_urls": {...}}`. `algorithm` accepts `"deepocr"` (default) or `"mineru"`.
- `get_parsing_status(data_id: str) -> int` - Query parsing status (1=parsing, 2=success, 3=failed)
- `generate_zips(data_id: str, file_type: str) -> str` - Generate download link for specific format
- `calc_part_count(file_path: str) -> int` - Calculate number of chunks for a file

### Exception Classes

- `HNDeepOCRError` - Base exception class
- `ConfigurationError` - Configuration related errors
- `AuthenticationError` - Authentication failures
- `UploadError` - File upload failures
- `ParseError` - Parsing failures

### Configuration

Configuration is managed via Pydantic Settings. Available options:

#### Core Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| AK | str | (required) | Access Key |
| SK | str | (required) | Secret Key |
| PRESIGNED_URL | str | https://open-sci-datahub.zero2x.org | API base URL |
| LOG_LEVEL | str | INFO | Log level (DEBUG/INFO/WARNING/ERROR/CRITICAL) |
| LOG_DIR | str | logs | Log directory |
| LOG_FILE | str | pdf_parser.log | Log filename |

#### Network Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| HN_DEEP_OCR_TIMEOUT_API | int | 30 | API call timeout (seconds) |
| HN_DEEP_OCR_TIMEOUT_UPLOAD | int | 300 | File upload timeout (seconds) |
| HN_DEEP_OCR_TIMEOUT_STATUS | int | 10 | Status query timeout (seconds) |
| HN_DEEP_OCR_TIMEOUT_MERGE | int | 60 | Merge operation timeout (seconds) |
| HN_DEEP_OCR_MAX_RETRIES_DEFAULT | int | 3 | Default retry count |
| HN_DEEP_OCR_MAX_RETRIES_UPLOAD | int | 5 | Upload retry count |
| HN_DEEP_OCR_BASE_DELAY | float | 1.0 | Base delay for retry backoff |
| HN_DEEP_OCR_CONNECTION_POOL_SIZE | int | 10 | Connection pool size |
| HN_DEEP_OCR_CONNECTION_MAXSIZE | int | 20 | Maximum connections per pool |
| HN_DEEP_OCR_PART_SIZE | int | 10485760 | File chunk size in bytes (10MB, valid range: 1MB~100MB) |

All network configuration options can be set via environment variables with the `HN_DEEP_OCR_` prefix or in your `.env` file.

## Development

### Installation

```bash
git clone https://github.com/yourusername/hn-deepocr-client.git
cd hn-deepocr-client
uv sync
```

### Running Tests

```bash
uv run pytest
```

With coverage:

```bash
uv run pytest --cov=hn_deepocr_client
```

### Code Quality

```bash
# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Fix linting issues
uv run ruff check --fix .

# Type check
uv run mypy .
```

### Examples

See the `examples/` directory for usage examples:

- `basic_usage.py` - Basic usage example
- `advanced_usage.py` - Advanced features and error handling

## Documentation

For more detailed documentation, see:

- [API Reference](docs/api.md)
- [Examples](docs/examples.md)
- [Changelog](CHANGELOG.md)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- Documentation: [https://github.com/yourusername/hn-deepocr-client](https://github.com/yourusername/hn-deepocr-client)
- Issues: [https://github.com/yourusername/hn-deepocr-client/issues](https://github.com/yourusername/hn-deepocr-client/issues)
- Email: support@haina.com

## Acknowledgments

- Built with [Pydantic](https://pydantic-docs.helpmanual.io/)
- Code quality powered by [Ruff](https://github.com/astral-sh/ruff)
- Testing with [pytest](https://docs.pytest.org/)
