API Reference

Config

The pydantic-settings surface over ~/.athome/config.toml.

config.SectionSettings: Base for every athome settings model; binds one [section] of ~/.athome/config.toml.
config.AthomeSettings: Root settings: the shared filesystem roots and the machine env prefix.
config.load(): Construct a settings model once per process (cleared in tests via load.cache_clear()).

Cache

Content+version-keyed caching with atomic staging writes.

cache.Cache: A namespaced, versioned, content-keyed blob/directory cache under cache_root.
cache.CacheKey: A content-derived cache address (blake2b-128 hex digest).
cache.CacheStats: Entry and byte totals for one cache namespace.
cache.cached(): Decorate an async function to memoize its pickled result in Cache.open(ns, version=version).
cache.stats_all(): Aggregate entry and byte totals for every namespace under cache_root (across all versions).
cache.CacheKeyError: Raised for an invalid cache address: a non-primitive argument, a bad namespace, or a malformed digest.

LLM cache

Record/replay HTTP caching for OpenAI-shaped clients.

llmcache.LlmCacheMode: How CachingTransport treats each request against the store.
llmcache.LlmCacheSettings: The [llmcache] section: default cache mode and key schema version.
llmcache.CachingTransport: Record/replay layer keyed on sha256(schema_version, method, scheme, host, port, path, sorted-query, body).
llmcache.RetryTransport: Retries 429/5xx/transport errors with capped exponential backoff (default 3 tries).
llmcache.transport(): Build the record-replay transport stack for an httpx.AsyncClient.
llmcache.LlmCacheMiss: Raised in LlmCacheMode.REPLAY when a request has no recorded response.

Workers

Sidecar subprocesses speaking the length-prefixed wire protocol.

workers.WorkerTransport: The async surface a sidecar exposes: a wire method call, plus shutdown.
workers.WorkerSpec: How to spawn a sidecar: the command, an environment overlay, and a working directory.
workers.PipeWorker: A lazily-spawned sidecar subprocess speaking length-prefixed wire frames over stdio.
workers.WorkerPool: A fixed pool of PipeWorker sidecars with digest-keyed prefetch and lease affinity.
workers.serve(): Run a sidecar’s frame loop until the parent closes the pipe.
workers.WorkerError: A sidecar reported an error through the wire, or its process failed.
workers.WorkerCrashed: A sidecar process exited before replying; carries its return code and stderr tail.
workers.HandshakeMismatch: A sidecar announced a wire version the parent does not speak.
wire.validate(): Structurally verify that obj is a Wire value, normalized to exact wire types.
wire.encode(): Validate obj and serialize it into a length-prefixed wire frame.
wire.decode(): Decode a length-prefixed wire frame produced by encode() back into a Wire.
wire.WireError: A value is not a valid Wire, or a frame cannot be decoded.

Progress

Resumable work-sets, crash-safe run sinks, phase gating.

progress.WorkSet: A resumable set of work units journaled as JSONL; errors are retried on resume.
progress.RunSink: Crash-safe incremental JSONL sink with a failure budget.
progress.Phases: Ordered phase markers gating multi-stage runs.
progress.FailureBudgetExceeded: Raised when a RunSink’s recorded failures exceed its budget.
progress.PhaseMissing: Raised by Phases.require when a required phase has not been marked.

launchd

Declarative launchd agents.

launchd.AgentSpec: A declarative launchd LaunchAgent: what to run, when, and where its logs go.
launchd.Calendar: A wall-clock trigger: every day at hour:minute, or a single weekday (0=Sunday).
launchd.Interval: A relative trigger: fire every seconds since the last launch.
launchd.KeepAlive: An always-on daemon: launchd respawns it whenever it exits, and runs it at load.
launchd.AgentStatus: The live state of one agent: whether its plist is installed and its bootstrapped process running.
launchd.plist_dict(): Render spec to the launchd plist dictionary launchctl loads.
launchd.install(): Write spec’s plist and (re)load it into the user’s GUI domain; return the plist path.
launchd.uninstall(): Boot the agent out of the GUI domain and remove its plist.
launchd.status(): Report label’s installed/running state by parsing launchctl print gui/<uid>/<label>.
launchd.installed(): List the labels of every athome-written LaunchAgent, optionally narrowed to those under prefix.
launchd.LaunchdError: Raised when a launchctl invocation fails — most often a non-zero bootstrap.

Detach

Sentinel-tracked detached overnight runs.

detach.DetachedRun: A launched detached run: its name, session-leader pid, and the log receiving its output.
detach.launch(): Launch command as a detached, session-leader subprocess that outlives the caller.
detach.wait(): Poll until the run’s process has exited and its .exit file appears, then return that code.
detach.running(): Return the pid of the live run named name (pid file + kill -0), or None if none is alive.
detach.DetachError: Raised when a detached run cannot start — most often a live run already owns the name.

Sync

Verified rsync mirroring.

sync.mirror(): Replicate src onto dst (a local path or "host:path") and verify it by sha256.
sync.SyncReport: The outcome of a verified mirror(): file/byte counts and swept AppleDoubles.
sync.SyncVerificationError: A mirror could not be verified clean; carries the unverified file list in mismatches.

Store

The shared aiosqlite scaffold.

store.Store: An open aiosqlite database with WAL, busy_timeout, and a schema applied.

Serve

Recipe-driven local model servers. RapidMlxSettings and LlamaServerSettings carry the engine-selection guidance.

serve.RapidMlxSettings: The [serve.rapid-mlx] section: the daily-pinned rapid-mlx version, model, and port.
serve.MlxVlmSettings: The [serve.mlx-vlm] section: the daily-pinned mlx-vlm version, vision model, and port.
serve.LlamaServerSettings: The [serve.llama-server] section: a full llama-server command string and its port.
serve.ManagedServer: A recipe-configured OpenAI-compatible server with lifecycle + health, over any backend.
serve.ServerHandle: A running recipe’s port (None for a hosted endpoint), pid (None for a launchd
serve.up(): Ensure recipe is running and healthy, returning its handle.
serve.down(): Stop recipe — launchd uninstall or detached-process kill.
serve.settings_for()
serve.command_for(): The recipe’s command vector; model and port override its configured pair.
serve.probe_all(): Report the health of every configured recipe, without waking a scale-to-zero endpoint.
serve.ServeError: Raised when a managed server cannot be started, stopped, or reached.
serve.HealthTimeout: Raised when a spawned server does not report healthy within the ready timeout.

Idle

A generic idle-unload lifecycle — single-flight load, reference-counted use, and a TTL reaper that unloads a value once it sits idle.

idle.IdleResource: A lazily-loaded value that unloads itself once idle past its TTL.

Activator

A probe-safe idle-unload proxy over IdleResource — probes answer locally while the child is down, wakes spawn it under a single-flight load, and the streamed relay’s inflight count spans the whole response body.

activator.ActivatorSettings: The [serve.activator] section: the child command and the proxy’s bind + policy knobs.
activator.Activator: The single-policy idle-unload proxy: one ~athome.idle.IdleResource, an allowlist app.
activator.serve_activator(): Run the activator proxy under uvicorn, binding host (or the configured host) and its port.
activator.ActivatorError: Root of every activator error surfaced through the proxy.

STT

Speech-to-text over transcribe.cpp — a lazily-loaded model behind one serialized compute lane, committed-delta streaming, and an OpenAI-compatible transcription server.

stt.Transcriber: A lazily-loaded transcribe.cpp model with a single serialized compute lane.
stt.SttStream: A live streaming transcription; use it as an async context manager to guarantee close.
stt.Transcript: A fully materialized transcription.
stt.Segment: A contiguous run of speech with its span in seconds and the words it covers.
stt.Word: One recognized word with its span in seconds from the start of the audio.
stt.VARIANTS
stt.gguf_path(): Materialize one quant of variant from the HF cache and return its .gguf path.
stt.decode(): Decode any audio container to 16 kHz mono float32 PCM via an ffmpeg subprocess.
stt.f32_from_s16(): Convert little-endian signed-16-bit PCM to float32 samples in [-1.0, 1.0).
stt.SttServeSettings: The [serve.stt] section: the served variant, quant, bind address, and idle window.
stt.SttServer: The transcription app: one ~athome.stt.engine.Transcriber behind an allowlist of routes.
stt.serve_stt(): Run the STT server under uvicorn, binding the inherited fd or the configured host/port.
stt.SttError: Raised when a transcription cannot be produced (bad input, an unknown variant, a decode failure).

Embed

Batch text-embedding backends and a digest-keyed incremental index with MMR rerank.

embed.EmbedBackend: A batch text-embedding backend producing an (n, dim) float32 matrix.
embed.ApiBackend: An OpenAI-compatible /embeddings endpoint as an embedding backend.
embed.LocalBackend: A local sentence-transformers model as an embedding backend (lazy import).
embed.VoyageEmbedBackend: The Voyage AI /embeddings API as an embedding backend (lazy import, embed-voyage extra).
embed.EmbedIndex: A content-digest-keyed incremental embedding matrix persisted under cache_root.
embed.EmbedSettings: The [embed] section: the bearer key for OpenAI-compatible embedding endpoints.
embed.VoyageSettings: The [embed.voyage] section: the Voyage AI key, model, and batching budgets.
embed.EmbedError: An embedding backend or index operation failed.

Registry

Content-addressed artifact versions with an atomic current promotion.

registry.VersionInfo: One registered artifact version.
registry.versions(): Every registered version of an artifact family under root, oldest first.
registry.current(): The promoted version the current symlink names, or None when nothing is promoted.
registry.register(): Writes a new immutable version directory under root; never flips current.
registry.promote(): Atomically flips current to the named version (full name or v<NNN> prefix).
registry.rollback(): Repoints current to the version registered just before the current promotion.
registry.prune(): Deletes all but the newest keep versions of name, never the one current points to.
registry.components(): Every artifact family with at least one registered version under root, sorted.
registry.RegistryError: The registry cannot satisfy the request: an unknown version, or an empty registration.

Train

LoRA fine-tuning over tinker, local mlx-lm, or modal.

train.TrainSpec: One fine-tuning request, backend-agnostic.
train.TrainResult: The outcome of one run: the artifact, its eval scalar, and its registry entry.
train.Checkpoint: The servable artifact one backend produced: a standalone 4-bit MLX model directory.
train.Adapter: A materialized non-fused MLX adapter that can be served or fused later.
train.BaseModelSpec: One base model addressed across every backend, pinned to exact weights.
train.Hyperparams: The optimization knobs shared by every backend.
train.LoraSpec: The LoRA adapter’s shape: its rank, scale, and which modules it wraps.
train.HfDatasetRef: A cc-steer HuggingFace export: one config of one dataset repo.
train.LocalJsonlRef: A local jsonl corpus: one .jsonl file, or a directory of them.
train.Rows: An in-memory SFT corpus: examples a caller already holds, with no jsonl detour.
train.TrainSettings: Backend selection, the mlx-lm sidecar pin, and the train roots, bound to [train].
train.TinkerSettings: Tinker credentials, spend cap, and per-model token prices, bound to [train.tinker].
train.TinkerPrice: One Tinker base model’s per-million-token price, split by the token class it bills.
train.TrainBackend: What every training backend exposes: a cheap probe, its methods, and a train call.
train.tinker.TinkerBackend: LoRA fine-tuning on Tinker’s managed trainers, converging on a fused local MLX model.
train.CheckpointPolicy: Which fractions of a run to snapshot as intermediate checkpoints, and for how long.
train.EvalRow: A pre-tokenized weighted scoring row, mapping one-to-one onto a Tinker Datum.
train.ScoredSequence: One eval row’s score against a checkpoint’s weights.
train.SavedCheckpoint: A Tinker sampler checkpoint saved mid-run, with its eval scores against those weights.
train.StepRecord: One training step’s telemetry.
train.TrainReport: Everything one fit produced: its per-step records and its saved checkpoints.
train.retrain
train.RetrainOutcome: Everything one retrain() produced, with no side effect taken on the caller’s behalf.
train.run(): Train spec, score the artifact against evaluation, and register what came out.
train.evaluate(): Serve checkpoint’s fused artifact and bake it off against evaluation’s arms.
train.register(): Register the fused MLX directory mlx_path under the name family in root.
train.model_path(): The registry’s own copy of version’s fused MLX model — the artifact to serve.
train.select(): Pick the backend that runs spec, preferring tinker, then local, then modal.
train.lora_keys(): The modules an adapter actually wraps: target_modules filtered by the LoRA toggles.
train.std_lora_keys(): The standard modules lora’s toggles select, ignoring its target_modules.
train.spend_cap(): The dollar cap binding this run: the spec’s max_usd when it set one, else default.
train.NoBackendAvailable: Raised when no backend can run the request: none is available, or the override cannot.
train.UnservableBase: Raised when the spec’s base model cannot produce a servable fused MLX artifact.
train.UnsupportedLoraShape: Raised when a LoraSpec asks for an adapter the MLX fuse path cannot express.
train.InsufficientData: Raised when the surviving training pool holds fewer examples than one batch.
train.OverlongEvalRows: Raised when any eval row exceeds max_seq_len; the whole frozen set fails up-front.

Tinker engine

The ordered op stream over Tinker’s clock-cycle model — forward/backward and optimizer step as one inseparable op, submit-ahead execution, and a cost projection folded over the same schedule the executor runs.

train.engine.TrainOp: One optimization step: a forward-backward and its optim step as a single value.
train.engine.ScoreOp: A batched forward pass scoring datums, billed as prefill.
train.engine.SnapshotOp: Save the current weights for sampling, optionally scoring eval datums against them.
train.engine.CrossEntropy: Tinker’s named cross_entropy loss: one forward-backward pass per step.
train.engine.Custom: A client-side loss (DPO): a forward pass and a surrogate backward, so two passes per step.
train.engine.TrainDone: The result of a TrainOp: its op and the forward-backward output for the fold.
train.engine.ScoreDone: The result of a ScoreOp: its op and one logprob output per scored datum.
train.engine.SnapshotDone: The result of a SnapshotOp: both saved paths and eval outputs, or None outputs when bare.
train.engine.execute(): Submit schedule’s ops to client and yield their results in submission order.
train.engine.projection(): The dollar cost schedule will bill at price — a pure fold over the same value execute runs.
train.engine.token_count(): The total input-token count across datums — what the metered classes bill against.

Gate

Promotion-gate statistics with an explicit higher-is-fire contract; behind the gate extra.

train.gate.GateVerdict: The gate’s decision over a candidate’s scores.
train.gate.GateResult: The corrected paired gate over a candidate and incumbent at matched budget.
train.gate.corrected_gate(): Evaluate the corrected paired gate over common rows at matched budget.
train.gate.sentinel_auc(): Return ROC-AUC for explicitly oriented higher-is-fire scores.
train.gate.sign_test_p(): Return the exact two-sided sign-test p-value over discordant pairs.
train.gate.threshold_for_budget(): Return a threshold whose exceedance count stays within an alert budget.
train.gate.matched_fire_mask(): Return a higher-is-fire mask matched conservatively to a fire budget.

OCR types

Protocols for token- and document-level OCR engines.

ocr.Box: Pixel rectangle in top-left-origin image coordinates.
ocr.OcrToken: A single recognized token with its bounding box and recognizer confidence.
ocr.Document: A page read by a document-OCR engine.
ocr.TokenOcr: Token-level OCR: geometry + confidence per token (the ensemble substrate).
ocr.DocOcr: Page-level document OCR (VLM engines): image in, structured markdown out.

Errors

The exception root the CLI renders.

errors.AthomeError: Root of every athome error; the CLI renders these as clean stderr + exit 1.