Skip to content

paths

diapason.core.paths

Central, env-aware resolution of Diapason' home directory.

Diapason keeps all of its runtime state (config, databases, caches, logs, credentials, skills, recipes, …) under a single root so it never clutters the user's home directory beyond one directory. That root is resolved here, with the following precedence (highest first):

  1. $DIAPASON_HOME (legacy: $OPENJARVIS_HOME/$JARVIS_HOME) — explicit override (also honored by the shell installer, see scripts/install/install.sh).
  2. $XDG_DATA_HOME/diapason — when $XDG_DATA_HOME is set, follow the XDG Base Directory spec by nesting a single diapason directory under it. We deliberately use ONE directory rather than splitting across XDG config/data/cache so the install tree stays self-contained and relocatable.
  3. ~/.diapason — the historical default. With no env vars set, the resolved path is exactly this, so existing installs are untouched.

config.py re-exports :func:get_config_dir results through the legacy DEFAULT_CONFIG_DIR/DEFAULT_CONFIG_PATH names (computed dynamically) so the ~45 modules that import those names keep working while honoring the override. Modules that previously hardcoded Path.home() / ".diapason" should call :func:get_config_dir (or :func:get_data_dir / :func:get_cache_dir) instead.

Defense in depth: the resolved root must never live inside the Diapason source tree (a misconfigured $DIAPASON_HOME pointing at the repo would otherwise scatter runtime artifacts into the working tree). This mirrors the guard in learning/spec_search/storage/paths.py and fails loudly per REVIEW.md's no-silent-failure discipline.

ConfigurationError

Bases: RuntimeError

Raised when the resolved home directory would violate isolation guarantees.

get_cache_dir()

Resolve the directory for regenerable caches (eval datasets, etc.).

Lives at <root>/cache so caches stay inside the single Diapason directory instead of scattering across ~/.cache.

get_config_dir()

Resolve Diapason' single root directory, honoring env overrides.

Precedence: $DIAPASON_HOME > $XDG_DATA_HOME/diapason > ~/.diapason. The result is always absolute and is rejected if it falls inside the Diapason source tree.

get_config_path()

Resolve the path to config.toml under the Diapason root.

get_data_dir()

Resolve the directory for persistent data (databases, blobs, …).

Consolidated under the single root; identical to :func:get_config_dir. Provided as a distinct name so call sites read intentionally.