--- name: athome description: > The plumbing every local AI experiment rebuilds, built once. Use when writing Python code that uses the athome package. license: PolyForm-Noncommercial-1.0.0 compatibility: Requires Python >=3.13. --- # experiment-at-home The plumbing every local AI experiment rebuilds, built once. ## Installation ```bash pip install athome ``` ## API overview ### Config The pydantic-settings surface over ~/.athome/config.toml. - `config.SectionSettings` - `config.AthomeSettings` - `config.load` ### Cache Content+version-keyed caching with atomic staging writes. - `cache.Cache` - `cache.CacheKey` - `cache.CacheStats` - `cache.cached` - `cache.stats_all` - `cache.CacheKeyError` ### LLM cache Record/replay HTTP caching for OpenAI-shaped clients. - `llmcache.LlmCacheMode` - `llmcache.LlmCacheSettings` - `llmcache.CachingTransport` - `llmcache.RetryTransport` - `llmcache.transport` - `llmcache.LlmCacheMiss` ### Workers Sidecar subprocesses speaking the length-prefixed wire protocol. - `workers.WorkerTransport` - `workers.WorkerSpec` - `workers.PipeWorker` - `workers.WorkerPool` - `workers.serve` - `workers.WorkerError` - `workers.WorkerCrashed` - `workers.HandshakeMismatch` - `wire.validate` - `wire.encode` - `wire.decode` - `wire.WireError` ### Progress Resumable work-sets, crash-safe run sinks, phase gating. - `progress.WorkSet` - `progress.RunSink` - `progress.Phases` - `progress.FailureBudgetExceeded` - `progress.PhaseMissing` ### launchd Declarative launchd agents. - `launchd.AgentSpec` - `launchd.Calendar` - `launchd.Interval` - `launchd.KeepAlive` - `launchd.AgentStatus` - `launchd.plist_dict` - `launchd.install` - `launchd.uninstall` - `launchd.status` - `launchd.installed` - `launchd.LaunchdError` ### Detach Sentinel-tracked detached overnight runs. - `detach.DetachedRun` - `detach.launch` - `detach.wait` - `detach.running` - `detach.DetachError` ### Sync Verified rsync mirroring. - `sync.mirror` - `sync.SyncReport` - `sync.SyncVerificationError` ### Store The shared aiosqlite scaffold. - `store.Store` ### Serve Recipe-driven local model servers. RapidMlxSettings and LlamaServerSettings carry the engine-selection guidance. - `serve.RapidMlxSettings` - `serve.MlxVlmSettings` - `serve.LlamaServerSettings` - `serve.ManagedServer` - `serve.ServerHandle` - `serve.up` - `serve.down` - `serve.settings_for` - `serve.command_for` - `serve.probe_all` - `serve.ServeError` - `serve.HealthTimeout` ### 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` ### 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.Activator` - `activator.serve_activator` - `activator.ActivatorError` ### 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.SttStream` - `stt.Transcript` - `stt.Segment` - `stt.Word` - `stt.VARIANTS` - `stt.gguf_path` - `stt.decode` - `stt.f32_from_s16` - `stt.SttServeSettings` - `stt.SttServer` - `stt.serve_stt` - `stt.SttError` ### Embed Batch text-embedding backends and a digest-keyed incremental index with MMR rerank. - `embed.EmbedBackend` - `embed.ApiBackend` - `embed.LocalBackend` - `embed.VoyageEmbedBackend` - `embed.EmbedIndex` - `embed.EmbedSettings` - `embed.VoyageSettings` - `embed.EmbedError` ### Registry Content-addressed artifact versions with an atomic current promotion. - `registry.VersionInfo` - `registry.versions` - `registry.current` - `registry.register` - `registry.promote` - `registry.rollback` - `registry.prune` - `registry.components` - `registry.RegistryError` ### Train LoRA fine-tuning over tinker, local mlx-lm, or modal. - `train.TrainSpec` - `train.TrainResult` - `train.Checkpoint` - `train.Adapter` - `train.BaseModelSpec` - `train.Hyperparams` - `train.LoraSpec` - `train.HfDatasetRef` - `train.LocalJsonlRef` - `train.Rows` - `train.TrainSettings` - `train.TinkerSettings` - `train.TinkerPrice` - `train.TrainBackend` - `train.tinker.TinkerBackend` - `train.CheckpointPolicy` - `train.EvalRow` - `train.ScoredSequence` - `train.SavedCheckpoint` - `train.StepRecord` - `train.TrainReport` - `train.retrain` - `train.RetrainOutcome` - `train.run` - `train.evaluate` - `train.register` - `train.model_path` - `train.select` - `train.lora_keys` - `train.std_lora_keys` - `train.spend_cap` - `train.NoBackendAvailable` - `train.UnservableBase` - `train.UnsupportedLoraShape` - `train.InsufficientData` - `train.OverlongEvalRows` ### 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` - `train.engine.ScoreOp` - `train.engine.SnapshotOp` - `train.engine.CrossEntropy` - `train.engine.Custom` - `train.engine.TrainDone` - `train.engine.ScoreDone` - `train.engine.SnapshotDone` - `train.engine.execute` - `train.engine.projection` - `train.engine.token_count` ### Gate Promotion-gate statistics with an explicit higher-is-fire contract; behind the gate extra. - `train.gate.GateVerdict` - `train.gate.GateResult` - `train.gate.corrected_gate` - `train.gate.sentinel_auc` - `train.gate.sign_test_p` - `train.gate.threshold_for_budget` - `train.gate.matched_fire_mask` ### OCR types Protocols for token- and document-level OCR engines. - `ocr.Box` - `ocr.OcrToken` - `ocr.Document` - `ocr.TokenOcr` - `ocr.DocOcr` ### Errors The exception root the CLI renders. - `errors.AthomeError` ## Resources - [Full documentation](https://yasyf.github.io/experiment-at-home/) - [llms.txt](llms.txt) — Indexed API reference for LLMs - [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs - [Source code](https://github.com/yasyf/experiment-at-home)