project-ara 0.0.1__py3-none-any.whl

ara/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Will Sarg
+"""Project ARA — AI Runs Anywhere.
+
+Backend-agnostic local inference. Core is pure Python; hardware-specific
+engines load lazily behind a backend protocol (see docs in the project_ara vault).
+"""

ara/acquire.py

@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Will Sarg
+"""Model acquisition — backend-neutral downloads into the HF cache.
+
+``download(repo_id)`` fetches a model; ``repo_size_gb`` / ``free_disk_gb`` back the
+pre-download disk check. Uses ``huggingface_hub`` directly, which produces the exact
+cache layout that mlx_lm / wmx-suite reads.
+
+No token required for ungated models (e.g. mlx-community/*). Set HF_TOKEN or
+HUGGING_FACE_HUB_TOKEN for gated ones, or HF_ENDPOINT for a mirror.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+# Headroom we insist on beyond the raw download, so a fetch never fills the disk
+# (unpacking, the snapshot's own .incomplete temp files, normal system churn).
+DISK_BUFFER_GB = 2.0
+
+# A well-formed Hugging Face repo id: ``name`` or ``org/name``, each segment starting with an
+# alphanumeric. Rejects anything an out-of-process worker's argparse could mis-read as a flag or
+# path — a leading ``-``, an ``=``, whitespace, ``..`` traversal, extra slashes. The model is a
+# *sink arg* (it becomes argv for the engine worker), so ARA validates its shape before it ever
+# leaves the process. Defensive: the value is a local CLI arg, but cheap to get right.
+_MODEL_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)?$")
+
+
+def valid_model_id(model: str) -> bool:
+    """True if *model* is a well-formed HF repo id (``org/name`` or ``name``), safe to pass as a
+    worker argv positional. Rejects flag-like / traversal / malformed values."""
+    return isinstance(model, str) and _MODEL_ID_RE.match(model) is not None
+
+
+def is_local_gguf(model: str) -> bool:
+    """True if *model* points at an existing local ``.gguf`` file that's safe as a worker argv
+    positional (never flag-like). The engine workers already resolve a ``.gguf`` path directly, so
+    this lets the CLI accept loose GGUF files on disk (e.g. a local model library) without
+    weakening the repo-id guard. The leading-``-`` ban preserves the argv-injection guarantee — a
+    real file path is a safe positional. (Slug: 2026-06-25-local-gguf-cli-support)"""
+    return (isinstance(model, str) and model.endswith(".gguf")
+            and not model.startswith("-") and os.path.isfile(model))
+
+
+def valid_model_ref(model: str) -> bool:
+    """True if *model* is a usable model reference safe to pass to an engine worker: a well-formed
+    HF repo id, or a local ``.gguf`` file path. The single guard the CLI applies before a model
+    becomes worker argv. (Slug: 2026-06-25-local-gguf-cli-support)"""
+    return valid_model_id(model) or is_local_gguf(model)
+
+
+_REASON_GATED = "gated"
+_REASON_NOT_FOUND = "not_found"
+_REASON_AUTH = "auth"
+_REASON_OFFLINE = "offline"
+_REASON_UNKNOWN = "unknown"
+
+
+def classify_repo_error(exc: BaseException) -> str:
+    """Map a Hugging Face (or network) exception to a small honest reason string.
+
+    Returns one of: ``"gated"``, ``"not_found"``, ``"auth"``, ``"offline"``, ``"unknown"``.
+    Pure function — safe to call with any exception type, including non-HF ones.
+    Imported lazily so this module stays cheap at import time.
+    """
+    from huggingface_hub.errors import (
+        GatedRepoError, HfHubHTTPError, LocalEntryNotFoundError,
+        OfflineModeIsEnabled, RepositoryNotFoundError,
+    )
+
+    if isinstance(exc, GatedRepoError):
+        return _REASON_GATED
+    if isinstance(exc, RepositoryNotFoundError):
+        return _REASON_NOT_FOUND
+    if isinstance(exc, (LocalEntryNotFoundError, OfflineModeIsEnabled)):
+        return _REASON_OFFLINE
+    if isinstance(exc, ConnectionError):
+        return _REASON_OFFLINE
+    if isinstance(exc, HfHubHTTPError) and getattr(
+            getattr(exc, "response", None), "status_code", None) == 401:
+        return _REASON_AUTH
+    return _REASON_UNKNOWN
+
+
+def probe_repo(repo_id: str) -> dict:
+    """Probe *repo_id* and return ``{"size_gb": float|None, "reason": str|None}``.
+
+    ``reason`` is None on success; one of the ``classify_repo_error`` strings on failure.
+    ``size_gb`` is None when the size can't be read (empty repo or any error).
+    Use this when the caller needs to surface *why* a fetch failed (e.g. the CLI).
+    ``repo_size_gb`` is still the right call when only the size matters.
+    """
+    from huggingface_hub import HfApi
+
+    try:
+        info = HfApi().model_info(repo_id, files_metadata=True)
+        total = sum(s.size for s in (info.siblings or []) if s.size)
+        return {"size_gb": round(total / 1e9, 3) if total else None, "reason": None}
+    except Exception as exc:
+        return {"size_gb": None, "reason": classify_repo_error(exc)}
+
+
+def repo_size_gb(repo_id: str) -> float | None:
+    """Total download size of *repo_id* in GB (decimal). None if it can't be read
+    (offline, private, or an API hiccup) — callers treat None as 'size unknown'."""
+    return probe_repo(repo_id)["size_gb"]
+
+
+def free_disk_gb() -> float | None:
+    """Free space (GB, decimal) on the volume holding the home directory."""
+    import shutil
+    from pathlib import Path
+
+    try:
+        return shutil.disk_usage(Path.home()).free / 1e9
+    except Exception:
+        return None
+
+
+def download(repo_id: str, *, progress: bool = False) -> None:
+    """Download *repo_id* into the HF cache. Network + disk only, no engine load.
+
+    ``progress=True`` enables HF's native tqdm bars for the duration of this call;
+    ``progress=False`` (default) silences them so the caller owns the output.
+    The prior bar state is always restored in ``finally`` regardless of which path
+    ran or whether the download succeeded.
+    """
+    from huggingface_hub import snapshot_download
+    from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars
+
+    was_disabled = are_progress_bars_disabled()
+    if progress:
+        enable_progress_bars()
+    else:
+        disable_progress_bars()
+    try:
+        snapshot_download(repo_id)
+    finally:
+        if was_disabled:
+            disable_progress_bars()
+        else:
+            enable_progress_bars()

ara/apps.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Will Sarg
+"""Inventory of AI/ML applications installed on the machine — GUI apps in /Applications
+plus Homebrew packages — matched against a curated catalog of known AI/ML software.
+
+A different lens from ENGINES (what ARA can launch) and FRAMEWORKS (python libraries):
+this is "what AI software is installed here," organized by what it's for. Read-only.
+macOS-focused (scans /Applications + Homebrew); degrades to whatever it can find elsewhere.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ara import versions
+
+# Category keys in display order, with their section sub-headers.
+CATEGORY_LABEL = {
+    "runner": "model runners",
+    "image": "image generation",
+    "speech": "speech / audio",
+    "toolkit": "ML toolkits",
+    "assistant": "AI assistants",
+    "coding": "AI coding",
+}
+_ORDER = list(CATEGORY_LABEL)
+
+# (label, category, [.app bundle names], [brew formula/cask tokens]). Curated — matched
+# exactly (case-insensitive), no keyword guessing, so a hit is always a real known app.
+CATALOG: list[tuple[str, str, list[str], list[str]]] = [
+    # local model runners / chat frontends
+    ("LM Studio", "runner", ["LM Studio"], ["lm-studio"]),
+    ("Ollama", "runner", ["Ollama"], ["ollama"]),
+    ("GPT4All", "runner", ["GPT4All", "gpt4all"], ["gpt4all"]),
+    ("Jan", "runner", ["Jan"], ["jan"]),
+    ("Msty", "runner", ["Msty"], ["msty"]),
+    ("Enchanted", "runner", ["Enchanted"], []),
+    ("Ollamac", "runner", ["Ollamac"], []),
+    ("Pinokio", "runner", ["Pinokio"], ["pinokio"]),
+    ("Transformer Lab", "runner", ["Transformer Lab"], []),
+    # image generation
+    ("DiffusionBee", "image", ["DiffusionBee"], ["diffusionbee"]),
+    ("Draw Things", "image", ["Draw Things"], []),
+    ("ComfyUI", "image", ["ComfyUI"], []),
+    ("InvokeAI", "image", ["InvokeAI"], []),
+    ("Diffusers", "image", ["Diffusers"], []),
+    ("Fooocus", "image", ["Fooocus"], []),
+    # speech / audio
+    ("MacWhisper", "speech", ["MacWhisper"], ["macwhisper"]),
+    ("superwhisper", "speech", ["superwhisper"], ["superwhisper"]),
+    ("VoiceInk", "speech", ["VoiceInk"], ["voiceink"]),
+    ("Aiko", "speech", ["Aiko"], []),
+    ("Whisper Transcription", "speech", ["Whisper Transcription"], []),
+    # ML toolkits / CLIs (largely Homebrew)
+    ("llama.cpp", "toolkit", [], ["llama.cpp"]),
+    ("whisper.cpp", "toolkit", [], ["whisper-cpp"]),
+    ("MLX", "toolkit", [], ["mlx", "mlx-c"]),
+    ("ggml", "toolkit", [], ["ggml"]),
+    ("ONNX Runtime", "toolkit", [], ["onnxruntime"]),
+    ("PyTorch", "toolkit", [], ["pytorch"]),
+    ("TensorFlow", "toolkit", [], ["tensorflow"]),
+    ("Hugging Face CLI", "toolkit", [], ["huggingface-cli"]),
+    # AI assistants (cloud clients) and AI coding tools
+    ("ChatGPT", "assistant", ["ChatGPT"], ["chatgpt"]),
+    ("Claude", "assistant", ["Claude"], ["claude"]),
+    ("Perplexity", "assistant", ["Perplexity"], ["perplexity"]),
+    ("Cursor", "coding", ["Cursor"], ["cursor"]),
+    ("Windsurf", "coding", ["Windsurf"], ["windsurf"]),
+    ("Antigravity", "coding", ["Antigravity"], []),
+    # Codex ships as two distinct artifacts — keep them separate so their independent
+    # versions aren't compared as "drift" (the .app is com.openai.codex; the cask is the CLI).
+    ("Codex", "coding", ["Codex"], []),
+    ("Codex CLI", "coding", [], ["codex"]),
+    ("CodexBar", "coding", ["CodexBar"], ["codexbar"]),
+    ("Claude Code", "coding", [], ["claude-code"]),
+    ("GitHub Copilot", "coding", ["GitHub Copilot"], ["copilot"]),
+    ("Warp", "coding", ["Warp"], ["warp"]),
+]
+
+
+@dataclass(frozen=True)
+class App:
+    label: str
+    category: str
+    in_app: bool        # a .app bundle is present in an Applications folder
+    cask: bool          # installed as a Homebrew cask (which IS how its .app got there)
+    formula: bool       # installed as a Homebrew formula (CLI)
+    version: str | None = None          # what's actually installed (.app plist for GUIs)
+    brew_recorded: str | None = None     # Homebrew's receipt version, when it manages this
+    cask_token: str | None = None        # the matched brew cask token (for drift remediation)
+    installed_at: float | None = None    # epoch mtime/birthtime, for "recently installed"
+
+    @property
+    def homebrew(self) -> bool:
+        return self.cask or self.formula
+
+    @property
+    def drift(self) -> bool:
+        """A cask GUI app whose installed (.app) version has self-updated past Homebrew's
+        frozen receipt — so `brew` no longer reflects reality (and `brew upgrade` may clobber).
+        Requires an actual installed .app, so a CLI-only cask never counts as drift."""
+        return bool(self.cask and self.in_app and self.brew_recorded and self.version
+                    and self.version != self.brew_recorded)
+
+    @property
+    def duplicate(self) -> bool:
+        """Two independent installs of the same tool: a CLI formula alongside a GUI
+        install (cask or a hand-dropped .app), or both a cask and a formula. A cask plus
+        its own .app is NOT a duplicate — the cask is what put the .app there."""
+        return self.formula and (self.cask or self.in_app)
+
+    @property
+    def source(self) -> str:
+        if self.cask and self.formula:
+            return "Homebrew (cask + formula)"
+        if self.cask:
+            return "Homebrew (cask)"
+        if self.formula and self.in_app:
+            return "Homebrew (formula) + separate app"
+        if self.formula:
+            return "Homebrew (formula)"
+        return "app (not via Homebrew)"
+
+
+_APP_DIRS = (Path("/Applications"), Path.home() / "Applications")
+_BREW_PREFIX = Path("/opt/homebrew") if Path("/opt/homebrew").exists() else Path("/usr/local")
+
+
+def _install_time(bundles: list[str], tokens: list[str], in_app: bool) -> float | None:
+    """Best-effort install/update time: a .app's filesystem time, else a Homebrew dir's.
+    Uses max(mtime, birthtime) — some bundles report a bogus birthtime."""
+    if in_app:
+        for b in bundles:
+            for base in _APP_DIRS:
+                app = base / f"{b}.app"
+                if app.is_dir():
+                    st = app.stat()
+                    return max(st.st_mtime, getattr(st, "st_birthtime", 0) or 0)
+    for t in tokens:
+        for sub in ("Caskroom", "Cellar"):
+            d = _BREW_PREFIX / sub / t
+            if d.is_dir():
+                try:
+                    return max((p.stat().st_mtime for p in d.iterdir()), default=d.stat().st_mtime)
+                except Exception:
+                    return None
+    return None
+
+
+def scan() -> list[App]:
+    """Installed AI/ML apps from the curated catalog, ordered by category then name."""
+    formulae, casks = versions.brew_formulae(), versions.brew_casks()
+    out: list[App] = []
+    for label, category, bundles, tokens in CATALOG:
+        in_app, app_ver = versions.find_app(bundles)
+        cask_ver = next((casks[t] for t in tokens if casks.get(t)), None)
+        formula_ver = next((formulae[t] for t in tokens if formulae.get(t)), None)
+        cask = any(t in casks for t in tokens)
+        formula = any(t in formulae for t in tokens)
+        if not (in_app or cask or formula):
+            continue
+        # The installed truth is the .app's own version; show that. For a cask we also keep
+        # brew's receipt so we can flag self-update drift. A formula (CLI) has no .app, so
+        # its brew version IS the truth.
+        cask_token = next((t for t in tokens if t in casks), None)
+        if cask:
+            version, brew_recorded = (app_ver or cask_ver), cask_ver
+        elif formula:
+            version, brew_recorded = formula_ver, None
+        else:  # hand-installed .app
+            version, brew_recorded = app_ver, None
+        out.append(App(label, category, in_app=in_app, cask=cask, formula=formula,
+                       version=version, brew_recorded=brew_recorded, cask_token=cask_token,
+                       installed_at=_install_time(bundles, tokens, in_app)))
+    out.sort(key=lambda a: (_ORDER.index(a.category), a.label.lower()))
+    return out

ara/backends/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Will Sarg
+"""Hardware backends. Each module is an adapter loaded lazily by the registry."""

ara/backends/ane.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Will Sarg
+"""Apple Neural Engine (ANE / CoreML) — STUB (no implementation yet).
+
+Contract class: **graph-fit** (not a context ramp). The question here isn't "how far
+can KV-cache grow" but "does this fixed, quantized graph map onto the accelerator and
+its memory slice." A different assessment from apple.py, which targets the *GPU*
+(MLX/Metal) on the same chip — a modern Mac carries both backends at once.
+Wall source: unified memory shared with the system; programmed via CoreML.
+"""

ara/backends/apple.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Will Sarg
+"""Apple-Silicon backend adapter — drives wmx-suite's MLX measurement out-of-process.
+
+A lean device oracle, symmetric with backends/cuda.py: it reads the machine's memory wall and
+runs wmx-suite's crash-safe calibration, but it owns **no persistence** — ARA stores and reuses
+the calibration (see cli.render_profile). It never imports wmx in-process: every engine call
+goes through the isolated ``apple`` env via :mod:`ara.engine_env`, so nothing MLX-shaped loads
+in ARA's interpreter and the core stays engine-free at runtime, not just at lock time.
+"""
+from __future__ import annotations
+
+# Core, engine-free helpers (no wmx) — safe to import at module load and patchable in tests.
+from ara import calibration, db, engine_env
+from ara.contracts import driver
+
+# The wmx worker modules ARA drives in the isolated apple env (never imported in-process).
+DEVICE_MODULE = "wmx_suite.device"
+
+# Model ARA calibrates against — smallest SmolLM (MLX 4-bit). Calibration only measures
+# fixed memory overhead, so a tiny instruct model is plenty.
+CALIBRATION_MODEL = "mlx-community/SmolLM-135M-Instruct-4bit"
+
+
+def safe_limits() -> dict:
+    """Read this machine's safe memory limits via the wmx worker. Pure read — no model.
+
+    Stateless: returns the budget with no stored overhead (``calibrated=False``). ARA overlays
+    a previously-measured overhead from its own store — the engine no longer reads a database.
+    """
+    facts = engine_env.run_worker("apple", ["-m", DEVICE_MODULE, "limits"])
+    return {
+        **facts,
+        "overhead_gb": None,        # ARA owns the stored calibration now
+        "calibrated": False,
+        "calibrated_at": None,
+    }
+
+
+def calibration_model_cached(model: str = CALIBRATION_MODEL) -> bool:
+    """Is the calibration model already in the HF cache? (cheap, no load)."""
+    from huggingface_hub import try_to_load_from_cache
+
+    try:
+        return isinstance(try_to_load_from_cache(model, "config.json"), str)
+    except Exception:
+        return False
+
+
+def download_calibration_model(model: str = CALIBRATION_MODEL, *,
+                               progress: bool = False) -> None:
+    """Fetch the calibration model into the HF cache. Network + disk only."""
+    from ara import acquire
+
+    acquire.download(model, progress=progress)
+
+
+def calibrate(model: str = CALIBRATION_MODEL) -> dict:
+    """Run wmx-suite's crash-safe calibration via the worker; return fresh limits + what it
+    measured.
+
+    The worker loads the model and watches memory under wmx-suite's predictive safety ramp,
+    which aborts before approaching the safe budget. ARA only invokes it (out-of-process in the
+    apple env). Surfaces the **effective** cold-start overhead (clamped to the engine's floor:
+    ``max(default, measured)``) as ``overhead_gb`` so ARA can persist it; the raw measurement is
+    in the ``"calibration"`` sub-dict for the caller to show.
+
+    If the worker fails (error dict or exception), returns an uncalibrated result with a
+    ``calibration_error`` field (never ``calibrated=True`` for unobserved data — Rule #3).
+    The safe default overhead is still in effect via ``_budget_params``; callers can detect the
+    condition via ``calibrated=False`` + presence of ``calibration_error``.
+    """
+    limits = safe_limits()
+    try:
+        result = engine_env.run_worker("apple", ["-m", DEVICE_MODULE, "calibrate", model])
+    except Exception as exc:
+        limits["calibrated"] = False
+        limits["overhead_gb"] = None
+        limits["calibration_error"] = (
+            f"calibration unavailable for {model!r}: {exc}"
+        )
+        return limits
+    if result.get("error"):
+        limits["calibrated"] = False
+        limits["overhead_gb"] = None
+        limits["calibration_error"] = (
+            f"calibration unavailable for {model!r}: {result['error']}"
+        )
+        limits["calibration"] = result
+        return limits
+    overheads = [v for v in (result.get("measured_overhead_gb"),
+                             result.get("default_overhead_gb")) if v is not None]
+    limits["overhead_gb"] = max(overheads) if overheads else None
+    limits["calibrated"] = True
+    limits["calibration"] = result
+    return limits
+
+
+# ARA-owned ramp policy (the engine only measures; ARA decides the schedule + safety margin).
+WORKER_MODULE = "wmx_suite.measure_one"
+RAMP_SCHEDULE = [2000, 4000, 8000, 16000, 32000, 65536, 131072]
+DEFAULT_MARGIN_GB = 2.0      # safety cushion below the wall (ARA policy)
+DEFAULT_OVERHEAD_GB = 1.0    # fallback cold-start overhead until calibrated
+
+
+def _budget_params() -> tuple[float, float]:
+    """ARA-owned (margin, overhead). Margin is policy; overhead is this machine's stored
+    calibration for the wmx engine, or a safe default if uncalibrated."""
+    overhead = DEFAULT_OVERHEAD_GB
+    stored = calibration.get_calibration(db.connect(), "wmx")
+    if stored and stored.get("fixed_overhead_gb") is not None:
+        overhead = stored["fixed_overhead_gb"]
+    return DEFAULT_MARGIN_GB, overhead
+
+
+# KV-cache quant lever (parity with the Vulkan lane). ARA's cross-engine `--kv-quant`
+# {f16,q8_0,q4_0} maps to MLX's integer kv-bits (fp16 = no quant). The effective bytes/elem
+# (8-bit/4-bit payload + an fp16 scale+bias per 64-elem group) feeds the KV-aware decode
+# estimate so it reflects the cache actually in use — not always fp16.
+_MLX_KV_BITS = {"f16": None, "q8_0": 8, "q4_0": 4}
+_MLX_KV_BYTES = {"f16": 2.0, "q8_0": 8 / 8 + 2 * 2 / 64, "q4_0": 4 / 8 + 2 * 2 / 64}
+
+
+def _worker_argv(model: str, ctx: int, margin: float, overhead: float, *,
+                 preflight: bool = False, kv_quant: str = "f16") -> list[str]:
+    argv = ["-m", WORKER_MODULE, model, str(ctx),
+            "--margin", str(margin), "--overhead", str(overhead)]
+    if preflight:
+        argv.append("--preflight")
+    bits = _MLX_KV_BITS[kv_quant]
+    if bits is not None:
+        argv += ["--kv-bits", str(bits)]
+    return argv
+
+
+def characterize(model: str, *, progress: bool = False, kv_quant: str = "f16") -> dict:
+    """Measure *model*'s safe context ceiling on this Mac — the thin path.
+
+    Pure wiring: ARA owns the methodology in the engine-agnostic ``contracts.driver`` (the
+    antidote to an Apple-shaped abstraction); this adapter only supplies the Apple specifics —
+    the isolated ``apple`` env, wmx's self-vetoing ``measure_one`` worker, the budget params,
+    and the schedule. ARA never imports wmx in-process. Crash-safety is layered: the driver
+    gates each rung (L1 ``plan_next`` + L2 actual-footprint check), the engine refuses-before-
+    load (L4) and a watchdog aborts mid-probe (L5). Returns ``{model, safe_context, points}``.
+
+    ``progress`` is accepted for interface symmetry with the cpu backend but has no effect
+    here: the HF download bar already ran in-process during the pre-fetch step.
+    """
+    margin, overhead = _budget_params()
+    return driver.characterize(
+        model,
+        preflight=lambda m: engine_env.run_worker(
+            "apple", _worker_argv(m, 0, margin, overhead, preflight=True, kv_quant=kv_quant)),
+        measure=lambda m, ctx: engine_env.run_worker(
+            "apple", _worker_argv(m, ctx, margin, overhead, kv_quant=kv_quant)),
+        schedule=RAMP_SCHEDULE,
+        kv_dtype_bytes=_MLX_KV_BYTES[kv_quant],   # decode-ceiling estimate reflects the cache type
+    )
+
+
+DEFAULT_MAX_TOKENS = 256
+
+
+def generate(model, prompt, *, max_context, max_tokens=DEFAULT_MAX_TOKENS,
+             kv_quant: str = "f16") -> dict:
+    """One-shot MLX completion, governed: max_context is the characterized safe ceiling, so the
+    worker generates under the wall. Out-of-process in the isolated `apple` env via wmx-suite's
+    generate worker; the prompt goes over stdin, never argv. ``kv_quant`` (default ``"f16"``)
+    should match how *model* was characterized. Returns {context, completion} or a refusal
+    {refused, reason}. ARA never imports MLX in-process."""
+    margin, overhead = _budget_params()
+    argv = ["-m", "wmx_suite.generate", model, str(max_context),
+            "--margin", str(margin), "--overhead", str(overhead),
+            "--max-tokens", str(max_tokens)]
+    bits = _MLX_KV_BITS[kv_quant]
+    if bits is not None:
+        argv += ["--kv-bits", str(bits)]
+    return engine_env.run_worker("apple", argv, input=prompt)

ara/backends/coral.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Will Sarg
+"""Google Coral / Edge TPU — STUB (no implementation yet).
+
+Contract class: **graph-fit** (not a context ramp). A fixed-function edge accelerator
+(USB/PCIe/SoM) that runs only INT8 TFLite models compiled by the Edge TPU compiler;
+assessment is "does this compiled graph fit the device's on-chip SRAM + its model
+budget," with overflow spilling to host. Closest neighbour to the MCU/TinyML class.
+Wall source: Edge TPU on-chip memory (+ host RAM for the runtime).
+"""