API Reference & Protocol Specification
Complete technical specifications for the Python SDK, Node.js SDK, CLI entry points, and OpenAI v1 REST/SSE endpoints.
1. Python SDK (`termux_llamacpp`)
LlamaRuntime
Main runtime factory and supervisor controller.
| Method Signature | Return Type | Description |
|---|---|---|
LlamaRuntime(config: Optional[RuntimeConfig]) |
LlamaRuntime |
Initializes runtime environment, directories, and binary verifiers. |
runtime.serve(model: str, host="127.0.0.1", port=8080, ctx_size=2048, threads=4) |
ServerInstance |
Spawns native backend and reverse proxy supervisor with lifecycle locks. |
runtime.models.download(repo_or_alias: str, filename=None) |
Path |
Downloads GGUF model with streaming SHA-256 verification and resume support. |
runtime.models.search(query: str, deep_crawl=False) |
List[Dict] |
Discovers compatible GGUF repositories on Hugging Face Hub. |
ServerConfig Dataclass
| Field | Type | Default | Description |
|---|---|---|---|
public_host | str | "127.0.0.1" | Supervisor public proxy bind interface. |
public_port | int | 8080 | Supervisor public port for OpenAI clients. |
native_port | int | 18080 | Loopback port for native llama-server backend. |
ctx_size | int | 2048 | Total token context buffer allocation. |
threads | int | 4 | Number of compute CPU threads for inference. |
no_mmap | bool | True | Direct sequential memory loading for Android resilience. |
2. REST & SSE Endpoints Schema
GET /health
Returns health state and active loaded model metadata.
{
"status": "ok",
"ready": true,
"service": "llama-server",
"protocolVersion": "1.0",
"model": {
"id": "Llama-3.2-3B-Instruct-Q4_K_M.gguf",
"sha256": "3B4C..."
}
}POST /v1/chat/completions
OpenAI-compliant chat completions with full streaming support.
| Parameter | Type | Required | Description |
|---|---|---|---|
messages | Array[Object] | Yes | Conversation messages array (role, content). |
max_tokens | int | No (512) | Maximum completion token generation budget. |
temperature | float | No (0.7) | Sampling randomness (0.0 for deterministic greedy). |
stream | bool | No (false) | Enables Server-Sent Events (SSE) token streaming. |