tracking-sdk

# 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 ```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} 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() ```