---------------------------------------------------------------------- This is the API documentation for the athome library. ---------------------------------------------------------------------- ## Config The pydantic-settings surface over ~/.athome/config.toml. SectionSettings(_case_sensitive: 'bool | None' = None, _nested_model_default_partial_update: 'bool | None' = None, _env_prefix: 'str | None' = None, _env_prefix_target: 'EnvPrefixTarget | None' = None, _env_file: 'DotenvType | None' = PosixPath('.'), _env_file_encoding: 'str | None' = None, _env_ignore_empty: 'bool | None' = None, _env_nested_delimiter: 'str | None' = None, _env_nested_max_split: 'int | None' = None, _env_parse_none_str: 'str | None' = None, _env_parse_enums: 'bool | None' = None, _cli_prog_name: 'str | None' = None, _cli_parse_args: 'bool | list[str] | tuple[str, ...] | None' = None, _cli_settings_source: 'CliSettingsSource[Any] | None' = None, _cli_parse_none_str: 'str | None' = None, _cli_hide_none_type: 'bool | None' = None, _cli_avoid_json: 'bool | None' = None, _cli_enforce_required: 'bool | None' = None, _cli_use_class_docs_for_groups: 'bool | None' = None, _cli_exit_on_error: 'bool | None' = None, _cli_prefix: 'str | None' = None, _cli_flag_prefix_char: 'str | None' = None, _cli_implicit_flags: "bool | Literal['dual', 'toggle'] | None" = None, _cli_ignore_unknown_args: 'bool | None' = None, _cli_kebab_case: "bool | Literal['all', 'no_enums'] | None" = None, _cli_shortcuts: 'Mapping[str, str | list[str]] | None' = None, _secrets_dir: 'PathType | None' = None, _build_sources: 'tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None' = None) -> None Base for every athome settings model; binds one [section] of ~/.athome/config.toml. Precedence: init kwargs > env (ATHOME_
_) > TOML section > defaults. AthomeSettings(_case_sensitive: 'bool | None' = None, _nested_model_default_partial_update: 'bool | None' = None, _env_prefix: 'str | None' = None, _env_prefix_target: 'EnvPrefixTarget | None' = None, _env_file: 'DotenvType | None' = PosixPath('.'), _env_file_encoding: 'str | None' = None, _env_ignore_empty: 'bool | None' = None, _env_nested_delimiter: 'str | None' = None, _env_nested_max_split: 'int | None' = None, _env_parse_none_str: 'str | None' = None, _env_parse_enums: 'bool | None' = None, _cli_prog_name: 'str | None' = None, _cli_parse_args: 'bool | list[str] | tuple[str, ...] | None' = None, _cli_settings_source: 'CliSettingsSource[Any] | None' = None, _cli_parse_none_str: 'str | None' = None, _cli_hide_none_type: 'bool | None' = None, _cli_avoid_json: 'bool | None' = None, _cli_enforce_required: 'bool | None' = None, _cli_use_class_docs_for_groups: 'bool | None' = None, _cli_exit_on_error: 'bool | None' = None, _cli_prefix: 'str | None' = None, _cli_flag_prefix_char: 'str | None' = None, _cli_implicit_flags: "bool | Literal['dual', 'toggle'] | None" = None, _cli_ignore_unknown_args: 'bool | None' = None, _cli_kebab_case: "bool | Literal['all', 'no_enums'] | None" = None, _cli_shortcuts: 'Mapping[str, str | list[str]] | None' = None, _secrets_dir: 'PathType | None' = None, _build_sources: 'tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None' = None, *, cache_root: pathlib._local.Path = PosixPath('~/.athome/cache'), logs_root: pathlib._local.Path = PosixPath('~/.athome/logs'), batches_root: pathlib._local.Path = PosixPath('~/.athome/batches'), env_prefix_cmd: str | None = None) -> None Root settings: the shared filesystem roots and the machine env prefix. load(model: 'type[S]') -> 'S' Construct a settings model once per process (cleared in tests via ``load.cache_clear()``). ## Cache Content+version-keyed caching with atomic staging writes. Cache(namespace: 'str', version: 'int', root: 'Path') -> None A namespaced, versioned, content-keyed blob/directory cache under ``cache_root``. Entries live at ``//v//`` — the version is part of the path, so bumping it is the only invalidation. Every write stages a temp sibling and publishes it with a single atomic :func:`os.replace`, so a reader never observes a partial entry. Example: >>> cache = Cache.open("frames", version=1) >>> path = await cache.put_bytes(cache.key("clip", 7), jpeg) CacheKey(digest: 'str') -> None A content-derived cache address (blake2b-128 hex digest). CacheStats(namespace: 'str', entries: 'int', bytes: 'int') -> None Entry and byte totals for one cache namespace. cached(*, ns: 'str', version: 'int') -> 'Callable[[F], F]' Decorate an async function to memoize its pickled result in ``Cache.open(ns, version=version)``. The key is the function's qualified name plus a canonical encoding of the call arguments; arguments must be hashable primitives or tuples thereof, or :class:`CacheKeyError` is raised. Example: >>> @cached(ns="ocr", version=2) ... async def read(page: int) -> str: ... stats_all() -> 'list[CacheStats]' Aggregate entry and byte totals for every namespace under ``cache_root`` (across all versions). 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. ## Workers Sidecar subprocesses speaking the length-prefixed wire protocol. ## Progress Resumable work-sets, crash-safe run sinks, phase gating. ## launchd Declarative launchd agents. ## Detach Sentinel-tracked detached overnight runs. ## Sync Verified rsync mirroring. ## Store The shared aiosqlite scaffold. ## Serve Recipe-driven local model servers. RapidMlxSettings and LlamaServerSettings carry the engine-selection guidance. ## Idle A generic idle-unload lifecycle — single-flight load, reference-counted use, and a TTL reaper that unloads a value once it sits idle. ## 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. ## 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. ## Embed Batch text-embedding backends and a digest-keyed incremental index with MMR rerank. ## Registry Content-addressed artifact versions with an atomic current promotion. ## Train LoRA fine-tuning over tinker, local mlx-lm, or modal. ## 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. ## Gate Promotion-gate statistics with an explicit higher-is-fire contract; behind the gate extra. ## OCR types Protocols for token- and document-level OCR engines. ## Errors The exception root the CLI renders. AthomeError Root of every athome error; the CLI renders these as clean stderr + exit 1. ---------------------------------------------------------------------- This is the CLI documentation for the package. ---------------------------------------------------------------------- ## CLI: athome ``` Usage: athome [OPTIONS] COMMAND [ARGS]... The plumbing every local AI experiment rebuilds, built once. Options: --version Show the version and exit. --help Show this message and exit. Commands: bakeoff Run an A/B/N endpoint bake-off from a spec module. batch Submit, poll, and collect 50%-off provider batch jobs. cache Inspect the shared content-keyed cache. hf Pull and push pinned Hugging Face snapshots. launchd List, inspect, and remove athome launchd agents. ocr Read an image or PDF into Markdown. research Run and inspect overnight autoresearch loops. run Launch and track detached overnight runs. serve Start, stop, and inspect local model servers. status Show launchd agents and configured-server health. stt Transcribe audio and manage transcribe.cpp GGUF weights. sync Mirror a tree with sha256 verification. train Fine-tune a LoRA, bake it off, and register the artifact. ```