Skip to content

api.md

Latest commit

 

History

History
286 lines (220 loc) · 4.52 KB

api.md

File metadata and controls

286 lines (220 loc) · 4.52 KB

API Reference

Complete documentation of all PyHellen API endpoints.

NLP Endpoints

List Languages

GET /api/languages

Returns all available language models.

Response:

{
  "languages": [
    {"code": "lasla", "name": "Classical Latin", "description": "..."},
    {"code": "grc", "name": "Ancient Greek", "description": "..."}
  ],
  "count": 7
}

Tag Text (GET)

GET /api/tag/{model}?text={text}&lower={boolean}
Parameter Type Description
model string Model code (e.g., lasla, grc)
text string Text to process (max 10,000 chars)
lower boolean Lowercase text before processing (default: false)

Response:

{
  "result": [
    {"form": "Gallia", "lemma": "Gallia", "pos": "NOMpro", "morph": "Case=Nom|Numb=Sing"},
    {"form": "est", "lemma": "sum", "pos": "VER", "morph": "Mood=Ind|Numb=Sing|Tense=Pres"}
  ],
  "processing_time_ms": 45.23,
  "model": "lasla",
  "from_cache": false
}

Tag Text (POST)

POST /api/tag/{model}
Content-Type: application/json

{
  "text": "Gallia est omnis divisa",
  "lower": false
}

Same response as GET version.

Batch Processing

POST /api/batch/{model}?concurrent={boolean}
Content-Type: application/json

{
  "texts": ["Text 1", "Text 2", "Text 3"],
  "lower": false
}
Parameter Type Description
concurrent boolean Use concurrent processing (default: true)

Response:

{
  "results": [[...], [...], [...]],
  "total_texts": 3,
  "processing_time_ms": 123.45,
  "model": "lasla",
  "cache_hits": 1
}

Streaming

POST /api/stream/{model}?format={format}
Content-Type: application/json

{
  "texts": ["Text 1", "Text 2"],
  "lower": false
}
Format Content-Type Description
ndjson application/x-ndjson Newline Delimited JSON (default)
sse text/event-stream Server-Sent Events
plain text/plain Plain text

NDJSON Response:

{"index": 0, "text": "Text 1", "result": [...], "processing_time_ms": 42.1, "from_cache": false}
{"index": 1, "text": "Text 2", "result": [...], "processing_time_ms": 38.5, "from_cache": false}

SSE Response:

event: result
data: {"index": 0, "text": "Text 1", "result": [...], "progress": "1/2"}

event: result
data: {"index": 1, "text": "Text 2", "result": [...], "progress": "2/2"}

event: complete
data: {"total": 2, "processing_time_ms": 80.6}

Model Management

List Models

GET /api/models

Response:

{
  "models": {
    "lasla": {"status": "loaded", "device": "cpu"},
    "grc": {"status": "not loaded", "device": null}
  }
}

Get Model Info

GET /api/models/{model}

Response:

{
  "name": "lasla",
  "status": "loaded",
  "device": "cpu",
  "batch_size": 256,
  "files": [...],
  "total_size_mb": 150.5,
  "has_custom_processor": false
}

Load Model

POST /api/models/{model}/load

Preloads a model into memory.

Response:

{
  "status": "loaded",
  "model": "lasla",
  "load_time_ms": 2500.0,
  "device": "cpu"
}

Unload Model

POST /api/models/{model}/unload

Unloads a model from memory to free resources.

Cache Management

Get Cache Stats

GET /api/cache/stats

Response:

{
  "size": 150,
  "max_size": 1000,
  "hits": 500,
  "misses": 200,
  "hit_rate": 0.71
}

Clear Cache

POST /api/cache/clear

Cleanup Expired

POST /api/cache/cleanup

Metrics

Get Metrics

GET /api/metrics

Requires admin scope if authentication is enabled.

Service Endpoints

Health Check

GET /service/health

Response:

{
  "status": "healthy"
}

API Status

GET /service/api/status

Response:

{
  "status": "running",
  "version": "0.0.1",
  "device": "cpu",
  "cuda_available": false,
  "models_loaded": ["lasla"],
  "uptime_seconds": 3600
}

Admin Endpoints

See Authentication for details on admin endpoints.

Error Responses

All errors follow this format:

{
  "detail": "Error message here"
}
Status Code Description
400 Bad request (invalid input)
401 Unauthorized (missing/invalid token)
403 Forbidden (insufficient permissions)
404 Model or resource not found
503 Model could not be loaded
500 Internal server error