# API Reference


## Config


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


[config.SectionSettings](config.md#athome.config.SectionSettings)  
Base for every athome settings model; binds one \[section\] of ~/.athome/config.toml.

[config.AthomeSettings](config.md#athome.config.AthomeSettings)  
Root settings: the shared filesystem roots and the machine env prefix.

[config.load()](config.md#athome.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](cache.md#athome.cache.Cache)  
A namespaced, versioned, content-keyed blob/directory cache under `cache_root`.

[cache.CacheKey](cache.md#athome.cache.CacheKey)  
A content-derived cache address (blake2b-128 hex digest).

[cache.CacheStats](cache.md#athome.cache.CacheStats)  
Entry and byte totals for one cache namespace.

[cache.cached()](cache.md#athome.cache.cached)  
Decorate an async function to memoize its pickled result in `Cache.open(ns, version=version)`.

[cache.stats_all()](cache.md#athome.cache.stats_all)  
Aggregate entry and byte totals for every namespace under `cache_root` (across all versions).

[cache.CacheKeyError](cache.md#athome.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](llm-cache.md#athome.llmcache.LlmCacheMode)  
How `CachingTransport` treats each request against the store.

[llmcache.LlmCacheSettings](llm-cache.md#athome.llmcache.LlmCacheSettings)  
The `[llmcache]` section: default cache mode and key schema version.

[llmcache.CachingTransport](llm-cache.md#athome.llmcache.CachingTransport)  
Record/replay layer keyed on sha256(schema_version, method, scheme, host, port, path, sorted-query, body).

[llmcache.RetryTransport](llm-cache.md#athome.llmcache.RetryTransport)  
Retries 429/5xx/transport errors with capped exponential backoff (default 3 tries).

[llmcache.transport()](llm-cache.md#athome.llmcache.transport)  
Build the record-replay transport stack for an `httpx.AsyncClient`.

[llmcache.LlmCacheMiss](llm-cache.md#athome.llmcache.LlmCacheMiss)  
Raised in `LlmCacheMode.REPLAY` when a request has no recorded response.


## Workers


Sidecar subprocesses speaking the length-prefixed wire protocol.


[workers.WorkerTransport](workers.md#athome.workers.WorkerTransport)  
The async surface a sidecar exposes: a wire method call, plus shutdown.

[workers.WorkerSpec](workers.md#athome.workers.WorkerSpec)  
How to spawn a sidecar: the command, an environment overlay, and a working directory.

[workers.PipeWorker](workers.md#athome.workers.PipeWorker)  
A lazily-spawned sidecar subprocess speaking length-prefixed wire frames over stdio.

[workers.WorkerPool](workers.md#athome.workers.WorkerPool)  
A fixed pool of `PipeWorker` sidecars with digest-keyed prefetch and lease affinity.

[workers.serve()](workers.md#athome.workers.serve)  
Run a sidecar's frame loop until the parent closes the pipe.

[workers.WorkerError](workers.md#athome.workers.WorkerError)  
A sidecar reported an error through the wire, or its process failed.

[workers.WorkerCrashed](workers.md#athome.workers.WorkerCrashed)  
A sidecar process exited before replying; carries its return code and stderr tail.

[workers.HandshakeMismatch](workers.md#athome.workers.HandshakeMismatch)  
A sidecar announced a wire version the parent does not speak.

[wire.validate()](workers.md#athome.wire.validate)  
Structurally verify that `obj` is a `Wire` value, normalized to exact wire types.

[wire.encode()](workers.md#athome.wire.encode)  
Validate `obj` and serialize it into a length-prefixed wire frame.

[wire.decode()](workers.md#athome.wire.decode)  
Decode a length-prefixed wire frame produced by `encode()` back into a `Wire`.

[wire.WireError](workers.md#athome.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](progress.md#athome.progress.WorkSet)  
A resumable set of work units journaled as JSONL; errors are retried on resume.

[progress.RunSink](progress.md#athome.progress.RunSink)  
Crash-safe incremental JSONL sink with a failure budget.

[progress.Phases](progress.md#athome.progress.Phases)  
Ordered phase markers gating multi-stage runs.

[progress.FailureBudgetExceeded](progress.md#athome.progress.FailureBudgetExceeded)  
Raised when a `RunSink`'s recorded failures exceed its budget.

[progress.PhaseMissing](progress.md#athome.progress.PhaseMissing)  
Raised by `Phases.require` when a required phase has not been marked.


## launchd


Declarative launchd agents.


[launchd.AgentSpec](launchd.md#athome.launchd.AgentSpec)  
A declarative launchd LaunchAgent: what to run, when, and where its logs go.

[launchd.Calendar](launchd.md#athome.launchd.Calendar)  
A wall-clock trigger: every day at `hour`:`minute`, or a single `weekday` (0=Sunday).

[launchd.Interval](launchd.md#athome.launchd.Interval)  
A relative trigger: fire every `seconds` since the last launch.

[launchd.KeepAlive](launchd.md#athome.launchd.KeepAlive)  
An always-on daemon: launchd respawns it whenever it exits, and runs it at load.

[launchd.AgentStatus](launchd.md#athome.launchd.AgentStatus)  
The live state of one agent: whether its plist is installed and its bootstrapped process running.

[launchd.plist_dict()](launchd.md#athome.launchd.plist_dict)  
Render `spec` to the launchd plist dictionary launchctl loads.

[launchd.install()](launchd.md#athome.launchd.install)  
Write `spec`'s plist and (re)load it into the user's GUI domain; return the plist path.

[launchd.uninstall()](launchd.md#athome.launchd.uninstall)  
Boot the agent out of the GUI domain and remove its plist.

[launchd.status()](launchd.md#athome.launchd.status)  
Report `label`'s installed/running state by parsing `launchctl print gui/<uid>/<label>`.

[launchd.installed()](launchd.md#athome.launchd.installed)  
List the labels of every athome-written LaunchAgent, optionally narrowed to those under `prefix`.

[launchd.LaunchdError](launchd.md#athome.launchd.LaunchdError)  
Raised when a launchctl invocation fails -- most often a non-zero bootstrap.


## Detach


Sentinel-tracked detached overnight runs.


[detach.DetachedRun](detach.md#athome.detach.DetachedRun)  
A launched detached run: its name, session-leader pid, and the log receiving its output.

[detach.launch()](detach.md#athome.detach.launch)  
Launch `command` as a detached, session-leader subprocess that outlives the caller.

[detach.wait()](detach.md#athome.detach.wait)  
Poll until the run's process has exited and its `.exit` file appears, then return that code.

[detach.running()](detach.md#athome.detach.running)  
Return the pid of the live run named `name` (pid file + `kill -0`), or None if none is alive.

[detach.DetachError](detach.md#athome.detach.DetachError)  
Raised when a detached run cannot start -- most often a live run already owns the name.


## Sync


Verified rsync mirroring.


[sync.mirror()](sync.md#athome.sync.mirror)  
Replicate `src` onto `dst` (a local path or `"host:path"`) and verify it by sha256.

[sync.SyncReport](sync.md#athome.sync.SyncReport)  
The outcome of a verified `mirror()`: file/byte counts and swept AppleDoubles.

[sync.SyncVerificationError](sync.md#athome.sync.SyncVerificationError)  
A mirror could not be verified clean; carries the unverified file list in `mismatches`.


## Store


The shared aiosqlite scaffold.


[store.Store](store.md#athome.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](serve.md#athome.serve.RapidMlxSettings)  
The `[serve.rapid-mlx]` section: the daily-pinned rapid-mlx version, model, and port.

[serve.MlxVlmSettings](serve.md#athome.serve.MlxVlmSettings)  
The `[serve.mlx-vlm]` section: the daily-pinned mlx-vlm version, vision model, and port.

[serve.LlamaServerSettings](serve.md#athome.serve.LlamaServerSettings)  
The `[serve.llama-server]` section: a full llama-server command string and its port.

[serve.ManagedServer](serve.md#athome.serve.ManagedServer)  
A recipe-configured OpenAI-compatible server with lifecycle + health, over any backend.

[serve.ServerHandle](serve.md#athome.serve.ServerHandle)  
A running recipe's port (`None` for a hosted endpoint), pid (`None` for a launchd

[serve.up()](serve.md#athome.serve.up)  
Ensure `recipe` is running and healthy, returning its handle.

[serve.down()](serve.md#athome.serve.down)  
Stop `recipe` -- launchd uninstall or detached-process kill.

[serve.settings_for()](serve.md#athome.serve.settings_for)  

[serve.command_for()](serve.md#athome.serve.command_for)  
The recipe's command vector; `model` and `port` override its configured pair.

[serve.probe_all()](serve.md#athome.serve.probe_all)  
Report the health of every configured recipe, without waking a scale-to-zero endpoint.

[serve.ServeError](serve.md#athome.serve.ServeError)  
Raised when a managed server cannot be started, stopped, or reached.

[serve.HealthTimeout](serve.md#athome.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](idle.md#athome.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](activator.md#athome.activator.ActivatorSettings)  
The `[serve.activator]` section: the child command and the proxy's bind + policy knobs.

[activator.Activator](activator.md#athome.activator.Activator)  
The single-policy idle-unload proxy: one `~athome.idle.IdleResource`, an allowlist app.

[activator.serve_activator()](activator.md#athome.activator.serve_activator)  
Run the activator proxy under uvicorn, binding `host` (or the configured host) and its port.

[activator.ActivatorError](activator.md#athome.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](stt.md#athome.stt.Transcriber)  
A lazily-loaded transcribe.cpp model with a single serialized compute lane.

[stt.SttStream](stt.md#athome.stt.SttStream)  
A live streaming transcription; use it as an async context manager to guarantee close.

[stt.Transcript](stt.md#athome.stt.Transcript)  
A fully materialized transcription.

[stt.Segment](stt.md#athome.stt.Segment)  
A contiguous run of speech with its span in **seconds** and the words it covers.

[stt.Word](stt.md#athome.stt.Word)  
One recognized word with its span in **seconds** from the start of the audio.

[stt.VARIANTS](stt.md#athome.stt.VARIANTS)  

[stt.gguf_path()](stt.md#athome.stt.gguf_path)  
Materialize one quant of `variant` from the HF cache and return its `.gguf` path.

[stt.decode()](stt.md#athome.stt.decode)  
Decode any audio container to 16 kHz mono float32 PCM via an ffmpeg subprocess.

[stt.f32_from_s16()](stt.md#athome.stt.f32_from_s16)  
Convert little-endian signed-16-bit PCM to float32 samples in `[-1.0, 1.0)`.

[stt.SttServeSettings](stt.md#athome.stt.SttServeSettings)  
The `[serve.stt]` section: the served variant, quant, bind address, and idle window.

[stt.SttServer](stt.md#athome.stt.SttServer)  
The transcription app: one `~athome.stt.engine.Transcriber` behind an allowlist of routes.

[stt.serve_stt()](stt.md#athome.stt.serve_stt)  
Run the STT server under uvicorn, binding the inherited `fd` or the configured host/port.

[stt.SttError](stt.md#athome.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](embed.md#athome.embed.EmbedBackend)  
A batch text-embedding backend producing an `(n, dim)` float32 matrix.

[embed.ApiBackend](embed.md#athome.embed.ApiBackend)  
An OpenAI-compatible `/embeddings` endpoint as an embedding backend.

[embed.LocalBackend](embed.md#athome.embed.LocalBackend)  
A local sentence-transformers model as an embedding backend (lazy import).

[embed.VoyageEmbedBackend](embed.md#athome.embed.VoyageEmbedBackend)  
The Voyage AI `/embeddings` API as an embedding backend (lazy import, `embed-voyage` extra).

[embed.EmbedIndex](embed.md#athome.embed.EmbedIndex)  
A content-digest-keyed incremental embedding matrix persisted under `cache_root`.

[embed.EmbedSettings](embed.md#athome.embed.EmbedSettings)  
The `[embed]` section: the bearer key for OpenAI-compatible embedding endpoints.

[embed.VoyageSettings](embed.md#athome.embed.VoyageSettings)  
The `[embed.voyage]` section: the Voyage AI key, model, and batching budgets.

[embed.EmbedError](embed.md#athome.embed.EmbedError)  
An embedding backend or index operation failed.


## Registry


Content-addressed artifact versions with an atomic current promotion.


[registry.VersionInfo](registry.md#athome.registry.VersionInfo)  
One registered artifact version.

[registry.versions()](registry.md#athome.registry.versions)  
Every registered version of an artifact family under `root`, oldest first.

[registry.current()](registry.md#athome.registry.current)  
The promoted version the `current` symlink names, or `None` when nothing is promoted.

[registry.register()](registry.md#athome.registry.register)  
Writes a new immutable version directory under `root`; never flips `current`.

[registry.promote()](registry.md#athome.registry.promote)  
Atomically flips `current` to the named version (full name or `v<NNN>` prefix).

[registry.rollback()](registry.md#athome.registry.rollback)  
Repoints `current` to the version registered just before the current promotion.

[registry.prune()](registry.md#athome.registry.prune)  
Deletes all but the newest `keep` versions of `name`, never the one `current` points to.

[registry.components()](registry.md#athome.registry.components)  
Every artifact family with at least one registered version under `root`, sorted.

[registry.RegistryError](registry.md#athome.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](train.md#athome.train.TrainSpec)  
One fine-tuning request, backend-agnostic.

[train.TrainResult](train.md#athome.train.TrainResult)  
The outcome of one `run`: the artifact, its eval scalar, and its registry entry.

[train.Checkpoint](train.md#athome.train.Checkpoint)  
The servable artifact one backend produced: a standalone 4-bit MLX model directory.

[train.Adapter](train.md#athome.train.Adapter)  
A materialized non-fused MLX adapter that can be served or fused later.

[train.BaseModelSpec](train.md#athome.train.BaseModelSpec)  
One base model addressed across every backend, pinned to exact weights.

[train.Hyperparams](train.md#athome.train.Hyperparams)  
The optimization knobs shared by every backend.

[train.LoraSpec](train.md#athome.train.LoraSpec)  
The LoRA adapter's shape: its rank, scale, and which modules it wraps.

[train.HfDatasetRef](train.md#athome.train.HfDatasetRef)  
A cc-steer HuggingFace export: one config of one dataset repo.

[train.LocalJsonlRef](train.md#athome.train.LocalJsonlRef)  
A local jsonl corpus: one `.jsonl` file, or a directory of them.

[train.Rows](train.md#athome.train.Rows)  
An in-memory SFT corpus: examples a caller already holds, with no jsonl detour.

[train.TrainSettings](train.md#athome.train.TrainSettings)  
Backend selection, the mlx-lm sidecar pin, and the train roots, bound to `[train]`.

[train.TinkerSettings](train.md#athome.train.TinkerSettings)  
Tinker credentials, spend cap, and per-model token prices, bound to `[train.tinker]`.

[train.TinkerPrice](train.md#athome.train.TinkerPrice)  
One Tinker base model's per-million-token price, split by the token class it bills.

[train.TrainBackend](train.md#athome.train.TrainBackend)  
What every training backend exposes: a cheap probe, its methods, and a train call.

[train.tinker.TinkerBackend](train.md#athome.train.tinker.TinkerBackend)  
LoRA fine-tuning on Tinker's managed trainers, converging on a fused local MLX model.

[train.CheckpointPolicy](train.md#athome.train.CheckpointPolicy)  
Which fractions of a run to snapshot as intermediate checkpoints, and for how long.

[train.EvalRow](train.md#athome.train.EvalRow)  
A pre-tokenized weighted scoring row, mapping one-to-one onto a Tinker `Datum`.

[train.ScoredSequence](train.md#athome.train.ScoredSequence)  
One eval row's score against a checkpoint's weights.

[train.SavedCheckpoint](train.md#athome.train.SavedCheckpoint)  
A Tinker sampler checkpoint saved mid-run, with its eval scores against those weights.

[train.StepRecord](train.md#athome.train.StepRecord)  
One training step's telemetry.

[train.TrainReport](train.md#athome.train.TrainReport)  
Everything one `fit` produced: its per-step records and its saved checkpoints.

[train.retrain](train.md#athome.train.retrain)  

[train.RetrainOutcome](train.md#athome.train.RetrainOutcome)  
Everything one `retrain()` produced, with no side effect taken on the caller's behalf.

[train.run()](train.md#athome.train.run)  
Train `spec`, score the artifact against `evaluation`, and register what came out.

[train.evaluate()](train.md#athome.train.evaluate)  
Serve `checkpoint`'s fused artifact and bake it off against `evaluation`'s arms.

[train.register()](train.md#athome.train.register)  
Register the fused MLX directory `mlx_path` under the `name` family in `root`.

[train.model_path()](train.md#athome.train.model_path)  
The registry's own copy of `version`'s fused MLX model -- the artifact to serve.

[train.select()](train.md#athome.train.select)  
Pick the backend that runs `spec`, preferring tinker, then local, then modal.

[train.lora_keys()](train.md#athome.train.lora_keys)  
The modules an adapter actually wraps: `target_modules` filtered by the LoRA toggles.

[train.std_lora_keys()](train.md#athome.train.std_lora_keys)  
The standard modules `lora`'s toggles select, ignoring its `target_modules`.

[train.spend_cap()](train.md#athome.train.spend_cap)  
The dollar cap binding this run: the spec's `max_usd` when it set one, else `default`.

[train.NoBackendAvailable](train.md#athome.train.NoBackendAvailable)  
Raised when no backend can run the request: none is available, or the override cannot.

[train.UnservableBase](train.md#athome.train.UnservableBase)  
Raised when the spec's base model cannot produce a servable fused MLX artifact.

[train.UnsupportedLoraShape](train.md#athome.train.UnsupportedLoraShape)  
Raised when a `LoraSpec` asks for an adapter the MLX fuse path cannot express.

[train.InsufficientData](train.md#athome.train.InsufficientData)  
Raised when the surviving training pool holds fewer examples than one batch.

[train.OverlongEvalRows](train.md#athome.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](tinker-engine.md#athome.train.engine.TrainOp)  
One optimization step: a forward-backward and its optim step as a single value.

[train.engine.ScoreOp](tinker-engine.md#athome.train.engine.ScoreOp)  
A batched forward pass scoring `datums`, billed as prefill.

[train.engine.SnapshotOp](tinker-engine.md#athome.train.engine.SnapshotOp)  
Save the current weights for sampling, optionally scoring eval datums against them.

[train.engine.CrossEntropy](tinker-engine.md#athome.train.engine.CrossEntropy)  
Tinker's named `cross_entropy` loss: one forward-backward pass per step.

[train.engine.Custom](tinker-engine.md#athome.train.engine.Custom)  
A client-side loss (DPO): a forward pass and a surrogate backward, so two passes per step.

[train.engine.TrainDone](tinker-engine.md#athome.train.engine.TrainDone)  
The result of a `TrainOp`: its op and the forward-backward output for the fold.

[train.engine.ScoreDone](tinker-engine.md#athome.train.engine.ScoreDone)  
The result of a `ScoreOp`: its op and one logprob output per scored datum.

[train.engine.SnapshotDone](tinker-engine.md#athome.train.engine.SnapshotDone)  
The result of a `SnapshotOp`: both saved paths and eval outputs, or None outputs when bare.

[train.engine.execute()](tinker-engine.md#athome.train.engine.execute)  
Submit `schedule`'s ops to `client` and yield their results in submission order.

[train.engine.projection()](tinker-engine.md#athome.train.engine.projection)  
The dollar cost `schedule` will bill at `price` -- a pure fold over the same value `execute` runs.

[train.engine.token_count()](tinker-engine.md#athome.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](gate.md#athome.train.gate.GateVerdict)  
The gate's decision over a candidate's scores.

[train.gate.GateResult](gate.md#athome.train.gate.GateResult)  
The corrected paired gate over a candidate and incumbent at matched budget.

[train.gate.corrected_gate()](gate.md#athome.train.gate.corrected_gate)  
Evaluate the corrected paired gate over common rows at matched budget.

[train.gate.sentinel_auc()](gate.md#athome.train.gate.sentinel_auc)  
Return ROC-AUC for explicitly oriented higher-is-fire scores.

[train.gate.sign_test_p()](gate.md#athome.train.gate.sign_test_p)  
Return the exact two-sided sign-test p-value over discordant pairs.

[train.gate.threshold_for_budget()](gate.md#athome.train.gate.threshold_for_budget)  
Return a threshold whose exceedance count stays within an alert budget.

[train.gate.matched_fire_mask()](gate.md#athome.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](ocr-types.md#athome.ocr.Box)  
Pixel rectangle in top-left-origin image coordinates.

[ocr.OcrToken](ocr-types.md#athome.ocr.OcrToken)  
A single recognized token with its bounding box and recognizer confidence.

[ocr.Document](ocr-types.md#athome.ocr.Document)  
A page read by a document-OCR engine.

[ocr.TokenOcr](ocr-types.md#athome.ocr.TokenOcr)  
Token-level OCR: geometry + confidence per token (the ensemble substrate).

[ocr.DocOcr](ocr-types.md#athome.ocr.DocOcr)  
Page-level document OCR (VLM engines): image in, structured markdown out.


## Errors


The exception root the CLI renders.


[errors.AthomeError](errors.md#athome.errors.AthomeError)  
Root of every athome error; the CLI renders these as clean stderr + exit 1.