aim

# Aim repo skill Use this skill when a task involves Aim experiment tracking: Python SDK instrumentation, local Aim repositories, run/metric/media/artifact logging, query expressions, Aim CLI/UI/server operation, remote tracking, storage/run maintenance, watcher notifications, or ML framework callback integrations. ## First checks 1. Install the base public package when Aim is not already available: ```bash python -m pip install aim ``` 2. Confirm the package and entry points: ```bash python -c "import aim; print(getattr(aim, '__version__', 'unknown'))" aim version ``` 3. For a reusable diagnostic, run: ```bash python scripts/check_aim_environment.py --check-optional ``` 3. Prefer explicit repository paths in both CLI and SDK workflows. Avoid relying on whatever current directory the agent or job scheduler happens to use. ## Route by task - **Python instrumentation, SDK APIs, metrics/media/params/artifacts, local repo lifecycle, query language, or missing tracked data**: read `sub-skills/tracking-sdk/SKILL.md`. - **CLI commands, local UI, remote tracking server, notebook UI, run/storage maintenance, conversion command discovery, or watcher/notifier operation**: read `sub-skills/cli-and-services/SKILL.md`. - **PyTorch/Lightning/Hugging Face/Keras/XGBoost/CatBoost/LightGBM/Optuna/other framework callbacks, optional dependency errors, direct `Run.track` fallbacks, or TensorBoard migration/sync**: read `sub-skills/framework-integrations/SKILL.md`. ## Root references - `references/package-overview.md` explains Aim's repo/run/sequence/context model and common end-to-end flow. - `references/troubleshooting.md` covers package-level install/import, version, repository path, cleanup, optional dependency, service, and storage-risk issues. - `references/repo-provenance.md` records the source commit, package versions, evidence paths, and refresh baseline. - `references/repo-routing-metadata.json` is structured router metadata for managed repo-skill import tooling. ## Root script - `scripts/check_aim_environment.py` checks Aim import/version/signatures, safe CLI help/version commands, and optional dependency availability without installing packages, starting services, or mutating repositories. ## Operating guardrails - Do not run `aim up`, `aim server`, or `aim-watcher start` unless the user asked for a long-running service and gave host/port/lifetime expectations. - Do not run destructive or storage-mutating commands (`aim runs rm`, `aim storage restore`, `aim storage prune`, `aim storage reindex`, or similar) without listing targets, checking backup/restore context, and getting explicit confirmation. - Do not install broad ML framework stacks for examples by default. Install or validate only the specific optional dependency required by the user's chosen integration. - Close Aim `Run` and `Repo` resources explicitly in scripts, especially before deleting temporary repositories. - Keep generated guidance self-contained. If a workflow needs executable help, use the bundled scripts in this skill tree rather than original repository examples or tests. ## Minimal SDK pattern ```python from aim import Repo, Run repo = Repo.from_path("./aim-repo", init=True) run = Run(repo=repo, experiment="demo", system_tracking_interval=None, capture_terminal_logs=False) try: run["hparams"] = {"lr": 1e-3, "batch_size": 32} run.track(0.5, name="loss", step=0, epoch=0, context={"subset": "train"}) finally: run.close() repo.close() ``` ## Minimal CLI pattern ```bash aim init --repo ./aim-repo aim up --repo ./aim-repo --host 127.0.0.1 --port 43800 ``` For remote training, route to `cli-and-services`: usually start `aim server` on the storage host and point SDK clients at an `aim://...` URL.