clox-client 1.0.0

Python client SDK for Clox Document Processing API

Clox Client SDK

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

pip install clox-client

Quick Start

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

from clox_client import Clox

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

Using Environment Variables (Recommended)

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

from clox_client import Clox

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

Usage Examples

Process a Single Document

# 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

# 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

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

List Documents

# 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

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

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

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

Custom Timeout and Retries

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

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
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
• Issues: https://github.com/clox-ai/client-sdk/issues
• Email: [e-mail]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Homepage: https://clox.ai
• Documentation: https://docs.clox.ai/client
• GitHub: https://github.com/clox-ai/client-sdk
• PyPI: https://pypi.org/project/clox-client/

---

Made with ❤️ by the Clox Team