---

name: tracking-sdk description: "Use Aim's Python SDK to create local repositories and runs, track metrics/params/media/artifacts/logs, query sequences, and validate SDK instrumentation safely." disable-model-invocation: true metadata: disco-role: operating repo-skill: aim scope: sub-skill license: Apache 2.0

Aim tracking SDK

Use this sub-skill when the task is to instrument Python code with Aim, open or initialize a local Aim repository from Python, create/resume/read runs, track scalar/object sequences, attach run metadata, query tracked data, build dataframes, or diagnose SDK-level missing-data issues.

Route away from this sub-skill when the user asks for:

• CLI command syntax, UI/server startup, remote server operation, storage maintenance, or destructive run management: use cli-and-services.
• Framework callbacks/loggers, optional ML framework integrations, or TensorBoard conversion/sync: use framework-integrations.

What to read

• references/sdk-api-reference.md for Run, Repo, Sequence, SequenceCollection, object constructors, artifacts, logging, lifecycle, and known signature caveats.
• references/tracking-workflows.md for copyable SDK instrumentation patterns, including train/validation loops with params and media.
• references/query-and-data-model.md for query expressions, contexts, sequence iteration, dataframes, and query edge cases.
• references/troubleshooting.md for missing metrics, type compatibility, temporary-directory cleanup, read-only misuse, system tracking, and validation steps.
• scripts/aim_sdk_smoke.py to create a tiny local repo, track scalars/media, query results, exercise dataframe paths when available, and verify the read-only caveat safely.

Operating guardrails

1. Prefer explicit repository paths in automation: create or open Repo.from_path(str(repo_dir), init=True) and pass the Repo object to Run(repo=repo, ...).
2. Close Run objects and then close Repo objects explicitly before deleting temporary directories or ending validation processes.
3. Disable background/system capture for short tests unless the user specifically needs it: Run(system_tracking_interval=None, log_system_params=False, capture_terminal_logs=False).
4. Use Run(run_hash, repo=repo, read_only=True) or repo.get_run(run_hash) for read access. In the verified Aim version, Repo(..., read_only=True) raises NotImplementedError.
5. Keep each sequence homogeneous for a fixed (run, name, context) tuple. Use distinct contexts such as {"subset": "train"} and {"subset": "val"} when logging the same metric name for different phases.
6. Use QueryReportMode.DISABLED in scripts and tests to avoid progress-bar side effects.
7. Do not start long-running UI/server processes or run destructive storage commands from this sub-skill.

Minimal 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}
    for step in range(3):
        run.track(1.0 / (step + 1), name="loss", step=step, epoch=0, context={"subset": "train"})
        run.track(0.8 / (step + 1), name="loss", step=step, epoch=0, context={"subset": "val"})
finally:
    run.close()
    repo.close()