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:

   python -m pip install aim
   

2. Confirm the package and entry points:

   python -c "import aim; print(getattr(aim, '__version__', 'unknown'))"
   aim version
   

3. For a reusable diagnostic, run:

   python scripts/check_aim_environment.py --check-optional
   

4. 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

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

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.