clox-client 1.0.0
Python client SDK for Clox Document Processing API
License: MIT
Requires Python: >=3.10
Keywords: clox, document-processing, ocr, api-client, sdk

# Clox Client SDK

[![PyPI version](https://badge.fury.io/py/clox-client.svg)](https://badge.fury.io/py/clox-client)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Python client SDK for the Clox Document Processing API.

## Features

- 🔐 Simple API key authentication
- 📄 Document processing (PDF, images)
- 📦 Batch operations
- 📊 Dashboard statistics
- 🔄 Automatic retries and error handling
- 🎯 Type hints and comprehensive documentation
- ⚡ Async-ready with requests session

## Installation

```bash
pip install clox-client
```

## Quick Start

```python
from clox_client import Clox

# Initialize with your API key
client = Clox(
    api_url="https://api.clox.ai",
    api_key="your_api_key"
)

# Process a document
result = client.process_document("invoice.pdf")
print(f"Document ID: {result['document_id']}")
print(f"Is Fraud: {result.get('is_fraud')}")
```

## Configuration

### Using API Key Directly

```python
from clox_client import Clox

client = Clox(
    api_url="https://api.clox.ai",
    api_key="clox_your_api_key_here"
)
```

### Using Environment Variables (Recommended)

```bash
export CLOX_API_URL="https://api.clox.ai"
export CLOX_API_KEY="clox_your_api_key_here"
```

```python
from clox_client import Clox

# Client reads from environment automatically
client = Clox()
result = client.process_document("invoice.pdf")
```

## Usage Examples

### Process a Single Document

```python
# Process PDF
result = client.process_document("invoice.pdf")

# Process image
result = client.process_document("receipt.jpg")

# Process file-like object
with open("document.pdf", "rb") as f:
    result = client.process_document(f, filename="document.pdf")

# Access results
print(f"Document ID: {result['document_id']}")
print(f"Is Fraud: {result.get('is_fraud')}")
```

### Batch Processing

```python
# Process multiple documents in a single request
batch_result = client.process_documents(files=["doc1.pdf", "doc2.jpg"])  # returns { batch_id, ... }
batch_id = batch_result["batch_id"]

# Get batch details
details = client.get_batch_details(batch_id)
print(f"Batch ID: {batch_id}")
print(f"Num Documents: {len(details.get('documents', []))}")

# List recent batch requests
batch_requests = client.get_batch_requests(page=1, limit=10)
print(batch_requests.get("batches"))
```

### Get Dashboard Statistics

```python
stats = client.get_dashboard_stats()
print(f"Total Documents: {stats['total_documents']}")
print(f"Documents Today: {stats['documents_today']}")
```

### List Documents

```python
# List all documents
docs = client.list_documents(page=1, limit=20)

# Filter by batch_id
docs_in_batch = client.list_documents(page=1, limit=20, batch_id="your_batch_id")
```

### Health Check

```python
health = client.health_check()
print(f"API Status: {health['status']}")
```

## API Methods

| Method | Description |
|--------|-------------|
| `process_document(file)` | Process a single document (path or file-like) |
| `process_documents(files)` | Process multiple documents in one request |
| `get_document(document_id)` | Download the original/processed document bytes |
| `get_annotated_document(document_id)` | Download annotated document bytes |
| `list_documents(page=1, limit=10, batch_id=None)` | List documents with pagination |
| `get_batch_requests(page=1, limit=10)` | List recent batch requests |
| `get_batch_details(batch_id)` | Get detailed batch info |
| `create_user(user_data)` | Create a new user |
| `list_users()` | List all users |
| `update_user(user_id, user_data)` | Update user |
| `delete_user(user_id)` | Delete user |
| `get_dashboard_stats()` | Get statistics |
| `health_check()` | Check API health |

## Error Handling

```python
from clox_client import Clox, CloxException, CloxAuthenticationError, CloxAPIError

try:
    client = Clox(api_key="your_api_key")
    result = client.process_document("invoice.pdf")

except CloxAuthenticationError as e:
    print(f"Authentication failed: {e}")

except CloxAPIError as e:
    print(f"API error: {e}")

except CloxException as e:
    print(f"Client error: {e}")
```

## Advanced Usage

### Context Manager

```python
with Clox(api_key="your_api_key") as client:
    result = client.process_document("invoice.pdf")
    print(result)
# Session automatically closed
```

### Custom Timeout and Retries

```python
client = Clox(
    api_key="your_api_key",
    timeout=60,  # 60 seconds timeout
    max_retries=5  # Retry up to 5 times
)
```

### Process Multiple Files in Parallel

```python
from concurrent.futures import ThreadPoolExecutor

files = ["doc1.pdf", "doc2.pdf", "doc3.pdf"]

def process_file(file_path):
    return client.process_document(file_path)

with ThreadPoolExecutor(max_workers=5) as executor:
    results = list(executor.map(process_file, files))
```

## Requirements

- Python 3.10 or higher
- `requests` library (installed automatically)

## Get Your API Key

To use the Clox Client SDK, you need an API key:

1. Sign up at [https://clox.ai](https://clox.ai)
2. Go to your dashboard
3. Generate an API key
4. Copy your key (starts with `clox_`)

## Security

- ✅ Always use environment variables for API keys
- ✅ Never commit API keys to version control
- ✅ Rotate keys regularly
- ✅ Use different keys for dev/staging/production

## Support

- **Documentation**: [https://docs.clox.ai](https://docs.clox.ai)
- **Issues**: [https://github.com/clox-ai/client-sdk/issues](https://github.com/clox-ai/client-sdk/issues)  
- **Email**: support@clox.ai

## License

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

## Links

- **Homepage**: [https://clox.ai](https://clox.ai)
- **Documentation**: [https://docs.clox.ai/client](https://docs.clox.ai/client)
- **GitHub**: [https://github.com/clox-ai/client-sdk](https://github.com/clox-ai/clox-client)
- **PyPI**: [https://pypi.org/project/clox-client/](https://pypi.org/project/clox-client/)

---

Made with ❤️ by the Clox Team