annie.core.config

Runtime configuration for Annie.

All settings are path-agnostic: nothing absolute is baked into the repository. Defaults come from environment variables (prefixed ANNIE_) so the same code runs on any machine — set them on your dev box and your private paths never leak into the public repo — and every folder can still be overridden at runtime from the Dataset tab’s pickers.

The infrastructure layer owns this module; higher layers read settings rather than touching the environment directly.

Attributes

settings

The process-wide settings instance.

Classes

Settings

User-facing configuration, resolved once at import time.

Functions

annie_home(→ pathlib.Path)

The Annie home directory (env ANNIE_HOME), defaulting to ~/.annie.

Module Contents

annie.core.config.annie_home() → pathlib.Path

The Annie home directory (env ANNIE_HOME), defaulting to ~/.annie.

Config-pinned review databases (annie_<config-stem>.db) live directly here, so a saved dataset always reopens against the same DB regardless of where the config file is stored.

The path is resolved, because it is compared against resolved DB paths to decide whether a config may store its database as a portable bare filename (see annie.dataset.datasets.to_config_dict()). An unresolved home would fail that comparison whenever it contains a symlink — which is the default on macOS, where /tmp links to /private/tmp — silently pinning an absolute path instead.

class annie.core.config.Settings

User-facing configuration, resolved once at import time.

videos_dir

Folder of source .mp4 files (env ANNIE_VIDEO_DIR).

vdet_dir

Folder of raw-detection .vdet files (env ANNIE_VDET_DIR).

track_dir

Folder of __track{N}.csv files (env ANNIE_TRACK_DIR).

participants_file

The protagonist heuristic CSV (uuid,track_id); the Annotator’s Export writes corrections to its _manual sibling (env ANNIE_PROTAGONIST_CSV).

labels_csv

A labels CSV file to seed as a label source on startup (env ANNIE_LABEL_CSV).

labels_key

The key column in labels_csv (env ANNIE_LABEL_KEY); auto-detected from the header when omitted.

labels_values

Comma-separated value columns from labels_csv (env ANNIE_LABEL_VALUES); defaults to all non-key columns.

db_path

SQLite file for this session’s review status (good/bad/notes). Defaults to <ANNIE_HOME>/annie_env.db (a stable per-environment database); set ANNIE_DB_PATH to pin a different path. Loading a saved config switches this to the config’s own annie_<stem>.db.

db_path_is_explicit

True when ANNIE_DB_PATH was set, so the UI can show “existing DB” mode instead of “new session DB” mode on startup.

annie_home

The Annie home directory (env ANNIE_HOME, default ~/.annie); config-pinned review databases live directly here.

logs_dir

Directory that receives per-session log files (<ANNIE_HOME>/logs).

sessions_dir

Directory that receives per-session SQLite databases (<ANNIE_HOME>/sessions).

temp_dir

Scratch directory for rendered preview clips and exports. Defaults to <ANNIE_HOME>/tmp (falling back to ~/.annie/tmp) so it lands on the same persistent location as logs and sessions; override with ANNIE_TEMP_DIR.

config_dir

Optional extra directory scanned for user-saved dataset configs (env ANNIE_CONFIG_DIR). Useful in Docker where the container-side data/config/ is ephemeral; set this to a path on a persistent volume so saved configs survive restarts.

data_dir

Optional override for the bundled data directory (env ANNIE_DATA_DIR). Needed for non-editable installs (Docker, PyPI) where the package lives in site-packages and cannot locate data by walking up from __file__; point it at the checked-out data.

video_extensions

Accepted source-video suffixes (lower-case, dotted).

vdet_extension

Suffix identifying a raw-detection file.

track_glob

Glob identifying derived single-track files.

render_max_workers

Maximum concurrent render jobs.

preview_max_workers

Maximum concurrent preview decodes (env ANNIE_PREVIEW_WORKERS; default: CPU count minus two, at least two).

temp_ttl_seconds

Age after which a rendered clip is swept (default 3 minutes).

host

Interface the NiceGUI server binds to.

port

Port the NiceGUI server listens on.

open_browser

Whether to open the default web browser at the app URL on startup (env ANNIE_OPEN_BROWSER). Off by default so dev, CI, and the headless Docker server are unaffected; the Windows launcher (which runs the server in a container and must open the browser on the host) sets it, and it is also handy for a local end-user launch where no terminal-savvy user is watching for the URL.

annie.core.config.settings

The process-wide settings instance.

Mutate its fields (e.g. from the Dataset tab) to change behaviour at runtime without re-importing.