Complete API Reference

Orchestrator, OrchestratorConfig, ModelLifecycle, AuditChain, SecretRedactor

ModelLifecycle States

StateDescriptionAllowed Transitions
COLDAdapter is registered but no process or memory allocation exists.→ WARM
WARMProcess is spawned and model weights are being loaded into memory.→ HOT, → ERROR
HOTWeights fully loaded; inference engine is initialised and ready.→ ACTIVE, → COLD
ACTIVEAn inference request is currently in flight on this adapter.→ HOT
ERRORAn unrecoverable error occurred (OOM, crash, timeout). Requires explicit reset.→ COLD (via reset)

Orchestrator

MethodSignatureReturnsDescription
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) → dictdictDispatches 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) → ModelLifecycleModelLifecycleReturns 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

FieldTypeDefaultDescription
total_budget_mbint0Combined memory budget for all managed adapters. 0 = no limit (reliant on Android LMK).
tailscale_keystr''Tailscale auth key for distributed clustering. Empty disables the clustering feature.
pin_pairing_portint29501UDP port for zero-config 6-digit PIN pairing handshakes.
audit_log_pathstr'~/.ameva/audit.log'Path for the tamper-evident SHA-256 hash-chained audit log.
redact_secretsboolTrueEnables automatic redaction of Bearer tokens, API keys, and URL credentials from all logged output.

AuditChain

MethodSignatureReturnsDescription
AuditChain.__init__(log_path: str)—Opens or resumes an existing SHA-256 hash-chained audit log at log_path.
.append(event: str, metadata: dict = {}) → strstr (entry hash)Appends a timestamped entry linked to the previous entry's hash. Returns the SHA-256 hash of the new entry.
.verify() → boolboolReplays the entire chain and verifies hash continuity. Returns False on any tampering.

SecretRedactor

MethodSignatureReturnsDescription
SecretRedactor.redact(text: str) → strstrScans 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.