PyHellen - Historical Languages NLP API

REST API for historical linguistic tagging using Pie Extended.

Features

• Multiple Languages: 7 built-in historical language models (can be activated/deactivated)
• High Performance: Concurrent batch processing, LRU caching with TTL
• Streaming: NDJSON and Server-Sent Events (SSE) formats
• GPU Support: Automatic CUDA detection and utilization
• Production Ready: Health checks, model preloading, comprehensive API
• Token Authentication: Optional token-based security with scopes (read, write, admin)
• SQLite Database: Persistent storage for models, tokens, cache, audit logs, and metrics
• Admin API: Model activation/deactivation and token management
• Request Logging: Track all API requests with detailed metrics
• Audit Trail: Complete audit logging for security-sensitive operations

Supported Languages

Code	Language	Code	Language
lasla	Classical Latin	freem	Early Modern French
grc	Ancient Greek	fr	Classical French
fro	Old French	dum	Old Dutch
frm	Middle French	occ_cont	Occitan

Quick Start

With Docker (recommended)

# CPU
docker run -p 8000:8000 ghcr.io/grand-siecle/pyhellen:latest

# Or with docker-compose
docker-compose -f docker/docker-compose.yml up -d pyhellen

Manual Installation

pip install -r requirements.txt
cp edit_dot_env .env
python -m app.main

API available at http://localhost:8000 | Docs at /docs

Usage

# Tag text
curl "http://localhost:8000/api/tag/lasla?text=Gallia%20est%20omnis%20divisa"

# Batch processing
curl -X POST "http://localhost:8000/api/batch/lasla" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Text 1", "Text 2"], "lower": false}'

# Streaming (NDJSON)
curl -X POST "http://localhost:8000/api/stream/lasla?format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Text 1", "Text 2"]}'

Documentation

Document	Description
API Reference	Complete API endpoints documentation
Authentication	Token-based security setup
Configuration	Environment variables reference
Docker	Docker deployment guide

Development

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=app --cov-report=html

License

GPL-3.0 - See LICENSE