Complete API Reference
Orchestrator, OrchestratorConfig, ModelLifecycle, AuditChain, SecretRedactor
ModelLifecycle States
| State | Description | Allowed Transitions |
COLD | Adapter is registered but no process or memory allocation exists. | → WARM |
WARM | Process is spawned and model weights are being loaded into memory. | → HOT, → ERROR |
HOT | Weights fully loaded; inference engine is initialised and ready. | → ACTIVE, → COLD |
ACTIVE | An inference request is currently in flight on this adapter. | → HOT |
ERROR | An unrecoverable error occurred (OOM, crash, timeout). Requires explicit reset. | → COLD (via reset) |
Orchestrator
| Method | Signature | Returns | Description |
Orchestrator.__init__ | (config: OrchestratorConfig) | — | Initialises the control plane. Acquires the process mutex to prevent duplicate instances. |
.register | (name: str, adapter_type: str, model_path: str, budget_mb: int = 0) | — | Registers an adapter in COLD state. adapter_type is one of 'llm', 'stt', 'tts', 'vision', 'diffusion', etc. |
.load | (name: str) → None | — | Drives the adapter from COLD → WARM → HOT. Blocks until HOT or raises on ERROR. |
.unload | (name: str) → None | — | Drives the adapter from any state → COLD. Kills the backing process and frees memory. |
.call | (name: str, payload: dict, timeout: float = 30.0) → dict | dict | Dispatches a request to the adapter (must be in HOT state). Transitions to ACTIVE during execution and back to HOT on completion. |
.get_lifecycle | (name: str) → ModelLifecycle | ModelLifecycle | Returns the current lifecycle state of the named adapter. |
.list_adapters | () → list[dict] | list[{"name": str, "state": str, "rss_mb": int}] | Returns all registered adapters with their current state and RSS memory usage. |
OrchestratorConfig
| Field | Type | Default | Description |
total_budget_mb | int | 0 | Combined memory budget for all managed adapters. 0 = no limit (reliant on Android LMK). |
tailscale_key | str | '' | Tailscale auth key for distributed clustering. Empty disables the clustering feature. |
pin_pairing_port | int | 29501 | UDP port for zero-config 6-digit PIN pairing handshakes. |
audit_log_path | str | '~/.ameva/audit.log' | Path for the tamper-evident SHA-256 hash-chained audit log. |
redact_secrets | bool | True | Enables automatic redaction of Bearer tokens, API keys, and URL credentials from all logged output. |
AuditChain
| Method | Signature | Returns | Description |
AuditChain.__init__ | (log_path: str) | — | Opens or resumes an existing SHA-256 hash-chained audit log at log_path. |
.append | (event: str, metadata: dict = {}) → str | str (entry hash) | Appends a timestamped entry linked to the previous entry's hash. Returns the SHA-256 hash of the new entry. |
.verify | () → bool | bool | Replays the entire chain and verifies hash continuity. Returns False on any tampering. |
SecretRedactor
| Method | Signature | Returns | Description |
SecretRedactor.redact | (text: str) → str | str | Scans for and masks Bearer tokens (Authorization: Bearer ****), API keys, passwords in URLs, and base64-encoded credentials. |
SecretRedactor.add_pattern | (pattern: str, replacement: str = '[REDACTED]') | — | Adds a custom regex pattern to the redaction pipeline. |