Skip to main content

agenticml-lite

agenticml-lite is a local-first experiment tracker. Training writes metrics, config, code, and media to files on disk, and agenticml ui serves a TensorBoard-style dashboard from those files. There is no server, database, or Docker image to run. Upload to AgenticML is optional, with agenticml login and agenticml sync. Install the package as agenticml-lite and import it as agenticml. The API is pre-alpha (0.1.0.dev0).

Documentation: https://agenticml.github.io/agenticml-lite/

Install

pip install agenticml-lite

pip install "agenticml-lite[system]"   # psutil: CPU, memory, disk
pip install "agenticml-lite[gpu]"      # NVIDIA GPU metrics via pynvml
pip install "agenticml-lite[media]"    # Pillow, for numpy and PIL images

Quickstart

import agenticml

agenticml.init(
    project="demo",
    name="exp1",
    config={"learning_rate": 0.01, "epochs": 10},
    tags=["baseline"],
)

for step in range(10):
    agenticml.log({"loss": 1 / (step + 1), "accuracy": step / 10}, step=step)

agenticml.summary["best_loss"] = 0.1
agenticml.finish()

init(project, name, ...) starts the one active run. Omit project and it defaults to the repository or directory name (AGENTICML_PROJECT overrides that; an explicit project wins). Omit name and it defaults to the main script's path relative to the repo root (e.g. scripts/train.py), or its absolute path outside a repo (empty without a main file). log advances the step when step is omitted; commit=False merges later metrics into the same step. config and summary are dicts on the active run. init(verbose=True) prints the run id, the run directory, and the agenticml ui command.

init also turns on runtime code snapshots and PyTorch component detection (auto_track=True). Automatic loss / learning-rate / epoch metrics and TensorBoard mirroring stay off until you pass auto_metrics=True and sync_tensorboard=True. System metrics are on (every 10 seconds) when psutil is installed; system_metrics=False disables them.

agenticml.log({"pred": agenticml.Image("pred.png", caption="val")})
agenticml.log_artifact("model.pt", name="checkpoint")          # reference
agenticml.log_artifact("model.pt", name="checkpoint", copy=True)  # snapshot bytes
agenticml.track_model(model)  # after the object exists

Image accepts a path, bytes, a file object, a PIL image, or a numpy array. Numpy arrays and PIL images need the media extra. track_optimizer, track_loss, and track_dataloader work the same way as track_model.

Zero-code

agenticml run executes a script inside a run. The script can omit import agenticml.

agenticml run --project demo -- python train.py --lr 1e-3
agenticml python train.py --lr 1e-3          # same interpreter, or re-exec
agenticml run -m mypkg.train --epochs 3
agenticml run -- python examples/train_toy.py --lr 0.05 --epochs 5

Command forms

There are several ways to write the same launch. All of them run the target in-process as __main__ inside one tracked run. The run forms take agenticml options; the bare agenticml python form does not, so set AGENTICML_* environment variables there. They differ in how you name the interpreter and the target, so pick the one that matches how you already start training.

Form Use it when Equivalent to
agenticml run train.py [args] You just want to track a script with the current interpreter. Shortest form. agenticml run -- python train.py [args]
agenticml run -m pkg.train [args] Your entry point is a module (python -m pkg.train), so relative imports and package layout keep working. agenticml run -- python -m pkg.train [args]
agenticml run -- python train.py [args] You are wrapping an existing command line, for example from a Makefile, a shell script or a README. Swap python for agenticml run -- and nothing else changes. agenticml python train.py [args]
agenticml python train.py [args] You want the least typing and no run or --. It reads as "python, but tracked". Options come from AGENTICML_* variables. agenticml run -- python train.py [args]
agenticml run --project demo -- python -u train.py You need Python flags (-u, -X, -W, ...) or a specific interpreter such as python3.11 or a venv's python. Agenticml re-launches itself under that interpreter, so agenticml-lite must be installed there. agenticml python -u train.py (options via env vars)
python -m agenticml run train.py agenticml is not on PATH (for example inside torchrun, accelerate launch, or a scheduler that takes a Python command). agenticml run train.py

Rules that apply to every form:

  • Agenticml options (--project, --name, ...) must come before the script or module. Everything after the target is the script's own argv, passed through untouched.
  • With run, the -- separator is optional when the target is a bare script or -m module. It is needed in front of python ... so that the options before it are not read as Python flags.
  • The default run name is the script's repo-relative path (e.g. scripts/train.py), or the module's file path for -m, unless --name is given.
  • python -c "..." and reading the script from stdin are not supported. Put the code in a file.
  • Only Python targets are supported. To track a shell script, call agenticml run -- python ... from inside it.
  • Multi-GPU: launch as torchrun ... -m agenticml run -- train.py. Only rank 0 logs.

Options go before the script; everything after it is the script's own argv. See agenticml run -h. --project, --name, --tags, --notes, --group, --job-type, --mode, --dir, and --log-every read AGENTICML_PROJECT, AGENTICML_NAME, AGENTICML_TAGS, AGENTICML_NOTES, AGENTICML_GROUP, AGENTICML_JOB_TYPE, AGENTICML_MODE, AGENTICML_DIR, and AGENTICML_LOG_EVERY. The off switches are in the table. --verbose has no variable.

--task sets the run's task and overrides AGENTICML_TASK, the parent's task, an agenticml.toml task, and the entry script's folder (see docs/SDK.md). With an explicit parent that is readable, in the same project, and has a task, a differing --task or valid AGENTICML_TASK logs a warning that the lineage link crosses tasks. --allow-cross-task or AGENTICML_ALLOW_CROSS_TASK=1 silences it.

--parent RUN_ID (env AGENTICML_PARENT) selects an explicit lineage parent. New runs inherit the parent's task unless --task or a valid AGENTICML_TASK supplies one. A parent in another project is recorded, but its task is not inherited. An invalid --parent / AGENTICML_PARENT is a usage error (exit 2). --parent only applies to new runs: a resumed run keeps its stored parent, with a warning if it differs.

What Where it comes from Turn off
Config argparse parses of sys.argv, and @hydra.main --no-capture-args (AGENTICML_CAPTURE_ARGS=0)
Code snapshot imported project modules and files opened for reading always on under agenticml run (track_source=False on Run)
Model, optimizer, loss, dataloader PyTorch construction hooks --no-auto-track (AGENTICML_AUTO_TRACK=0)
auto/loss, auto/lr, auto/epoch backward() and optimizer.step() --no-auto-metrics (AGENTICML_AUTO_METRICS=0); --log-every N
TensorBoard SummaryWriter / tensorboardX (scalars, images, figures, hparams) --no-tensorboard (AGENTICML_SYNC_TENSORBOARD=0)
System metrics psutil, plus pynvml when installed always requested under agenticml run (needs the system extra)

Loss is unscaled under GradScaler and averaged over gradient-accumulation steps. Several optimizers are prefixed (auto/<name>/loss, auto/<name>/lr); auto/epoch stays unprefixed. TensorBoard event files are still written. Keys passed to init(config=...) win over captured hyperparameters.

A script that calls agenticml.init() joins the launcher's run. Exit 0 finishes as finished; any other exit finishes as crashed, with _exit_code and _exception in the summary. The script's exit code is preserved. SIGTERM finishes the run and exits 143.

The zero-code toy example captures config, code and system information, but no training metrics: its pure-Python loop has no framework hooks. examples/train_toy.py --explicit is the same loop calling the Python API itself to log metrics. See examples/README.md.

Viewing

agenticml ui          # http://127.0.0.1:6006
agenticml ls          # newest first
agenticml ui --open --port 6006 --host 127.0.0.1
agenticml ui --read-only
agenticml ls --project demo --json

agenticml ui binds to 127.0.0.1 and port 6006. On loopback it answers only loopback Host headers. --dir selects the store (else AGENTICML_DIR, else ~/.agenticml). ls prints run id, project, name, status, created time, and last step. A run stays running while its lifetime lock is held, even when it logs infrequently. If the lock is free, it is shown as crashed; sync finalizes it with _exit_reason: "process died". On filesystems without locking, mtimes older than 120 seconds are the fallback for stale status.

The dashboard pages do not show run notes. Launch notes (--notes / init(notes=)) are still stored with the run, and the server keeps the /api/runs/<id>/notes endpoint, which is the only write it accepts; --read-only disables it (recommended when exposing a non-loopback --host).

Where data lives

The store root is init(dir=...), else AGENTICML_DIR, else ~/.agenticml. Layout (details in docs/FORMAT.md):

<root>/
  objects/<hh>/<sha256>          content-addressed bytes, shared by every run
  runs/<run_id>/
    meta.json                    project, config, status, summary, env, git
    events.jsonl                 config updates, code, artifacts, finish
    notes.md                     run note (Markdown, up to 256 KiB)
    sync.json                    per-host upload cursor, after a sync
    scalars/<id>.bin             8 bytes per point: uint32 step, float32 value
    scalars/<id>.ovw             overview, at finish, if the series has > 65536 points
    scalars/_time.bin            one record per scalar flush
    scalars/index.json
    media/index.json

New run ids look like 20261027T021500-ab12cd34 (UTC). Each scalar point is 8 bytes in <id>.bin. An overview is written at finish only when a series has more than 65,536 points, and it is at most 40 + 36×2048 = 73,768 bytes. Worst-case overview overhead is about 14% of the raw series (the 73,768-byte cap next to a 65,537-point <id>.bin); the share falls as the series grows, to about 0.6 B/pt past ~120,000 points. At or below 65,536 points the reader builds the overview from <id>.bin on demand. TensorBoard tfevents are ~51 B/pt, and the old JSONL journal was ~57 B/pt.

Code snapshots and media are stored once, keyed by SHA-256. The same bytes logged again share one object. Default snapshot caps are 10 MB per file and 100 MB total. Media indexes retain at most 64 rows per key by default, thinning older rows as new media arrives (AGENTICML_MEDIA_MAX_PER_KEY overrides the cap). Artifacts are a path, size, and mtime unless copy=True, which hashes the bytes into objects/.

Disk

agenticml du
agenticml gc --dry-run
agenticml gc --older-than DAYS --keep-last N
agenticml gc --include-unsynced
agenticml sync --all --prune

agenticml du reports how much space the local store uses. agenticml gc removes runs. Only synced runs are eligible unless you pass --include-unsynced. --older-than and --keep-last narrow the set. --dry-run prints the plan and deletes nothing. agenticml sync --prune drops raw <id>.bin files for series that already have an overview; series of 65,536 points or fewer keep their .bin (≤ 512 KB each). A pruned run cannot be resumed or synced to another host, or uploaded again after sync --reset. Unreferenced objects have a one-hour grace period before gc removes them. Agenticml warns when the store exceeds AGENTICML_MAX_BYTES (default 5 GiB).

Upload

agenticml login --host https://api.agenticml.xyz
agenticml whoami
agenticml logout
agenticml sync RUN_ID [RUN_ID ...]
agenticml sync --all
agenticml sync --all --watch 30 --dry-run
agenticml sync RUN_ID --reset

login checks the key (skip with --no-verify) and writes ~/.config/agenticml/credentials.json at mode 0600. The directory is AGENTICML_CONFIG_DIR, else $XDG_CONFIG_HOME/agenticml, else ~/.config/agenticml. The default host is https://api.agenticml.xyz. Use the agenticml login prompt to enter the key, or AGENTICML_API_KEY for sync. Avoid command-line --key / --api-key: their values are visible in ps. login also accepts stdin. sync takes the key from --api-key, then AGENTICML_API_KEY, then the file. whoami uses AGENTICML_API_KEY, then the file. whoami --offline skips the server check. logout removes the saved key for one host. On login, whoami, and sync, --insecure allows http:// to a non-local host; localhost does not need it.

Sync is incremental and resumable. A cursor in runs/<id>/sync.json stores scalar byte offsets and which code, media, and artifacts were sent. An interrupted sync retries at most the in-flight batch. --all selects runs that are incomplete or changed. --watch N repeats every N seconds until every selected run has synced, failed permanently, or gone stale. --dry-run prints counts without sending or saving state. --reset clears the saved remote id for explicit run ids on this host, and it rejects --all.

Uploaded: project, name, config, tags, notes, group, job type, env, git, the parent's remote id, finite scalar points, code files, media, artifacts, and the summary plus status at finalize. copy=True artifacts come from the object store. By-reference artifacts are read from the logged path when it is still a regular file with the same size and mtime.

Server-side gaps: created_at and finished_at are stamped by the server at sync time. Config keys cannot be deleted remotely, and group / job_type cannot be cleared (a null is omitted and the stored value stays).

Configuration

Variable Default Purpose
AGENTICML_DIR ~/.agenticml Store root. init(dir=) and --dir win.
AGENTICML_MODE local local, offline (alias of local), or disabled. Other values warn and use local.
AGENTICML_HOST https://api.agenticml.xyz Server for login, whoami, and sync.
AGENTICML_API_KEY unset Key for sync and whoami. login ignores it.
AGENTICML_CONFIG_DIR ~/.config/agenticml Credential directory. Wins over XDG_CONFIG_HOME.
AGENTICML_MAX_BYTES 5 GiB Warn when the local store is larger than this. Nothing is deleted automatically.
AGENTICML_MEDIA_MAX_PER_KEY 64 Media index rows kept per key. Further rows are thinned by step.
AGENTICML_MEDIA_MAX_PX 1024 Longest side of a logged image, when Pillow is installed.

agenticml run settings use the variables listed under Zero-code. Boolean switches treat 0, false, no, and off as off.

Performance

From python scripts/bench.py --quick on one machine. Timings and bytes/point move with CPU, disk, and Python.

Metric This run Target
import agenticml (median of 5) 39.4 ms < 100 ms
log() ×10 scalars, median (10,000 calls) 2.70 µs < 10 µs
log() ×10 scalars, p99 8.91 µs
disk, whole scalars/ dir (100,000 points) 8.01 B/pt ≤ 9.0 B/pt (8 B raw + overview)
UI cold start, /api/runs (101 runs) 8 ms < 1 s
scalar request, 100,000-point series (median of 20) 14.16 ms < 20 ms
TensorBoard tfevents not installed

The disk row is ten series of 10,000 points. Each series is under 65,536 points, so finish writes no overview and the directory stays at 8.01 B/pt, inside the 9.0 B/pt check. A series past 65,536 points adds one overview of at most 73,768 bytes. python scripts/bench.py without --quick uses 100,000 log calls, a 1,000,000-point run, and 1,000 small runs.

Distributed, resume, disabled

Rank 0 logs. init(only_main_process=True) (the default) gives every other rank a no-op run, using RANK, PMI_RANK, OMPI_COMM_WORLD_RANK, SLURM_PROCID, then LOCAL_RANK. Put the tracker inside the launcher so every rank runs the script:

torchrun --nproc_per_node 4 -m agenticml run -- train.py

Resume with the same id. resume="must" errors if it is missing; resume="allow" opens it or creates it. The default resume="never" rejects an id. A pruned run (overview present, raw series file gone) cannot be resumed.

agenticml.init(project="demo", name="exp1", id=run_id, resume="allow")

mode="disabled" or AGENTICML_MODE=disabled makes log, finish, artifacts, and the track_* helpers no-ops. With verbose=True, init prints agenticml: tracking disabled.

Development

pip install -e ".[dev]"
pytest
python scripts/bench.py --quick

Releasing

GitHub Actions publishes to PyPI with Trusted Publishing (no API tokens).

  • TestPyPI dry run: run the "Publish to TestPyPI" workflow by hand from the Actions tab. Re-running with a version that is already there is a no-op.
  • PyPI: push a v* tag. The workflow fails if the tag does not match the version in pyproject.toml and src/agenticml/__init__.py.
# bump version in pyproject.toml and src/agenticml/__init__.py
git commit -am "release: v0.1.0"
git tag v0.1.0
git push origin v0.1.0

License

MIT — see LICENSE.

Metadata

Release files for agenticml-lite 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agenticml-lite 1.0.0
File Size Uploaded Provenance Actions
agenticml_lite-1.0.0.tar.gz 428.2 kB With provenance Details for agenticml_lite-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agenticml-lite 1.0.0
File Interpreter ABI Platform Actions
agenticml_lite-1.0.0-py3-none-any.whl Python 3 none any Details for agenticml_lite-1.0.0-py3-none-any.whl

Total release size: 732.0 kB

Release files / agenticml_lite-1.0.0.tar.gz

Download URL agenticml_lite-1.0.0.tar.gz
Size 428.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ee8694a77ba49d0a0b4e43f6f26bccf0ec61b3d3989df823e62597284eea5184
BLAKE2b-256 checksum
How to use checksums
361fb37f2178a8c1e074fd60bc31dff832137a8b52c83479e6f47f6939c3a539
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / agenticml_lite-1.0.0-py3-none-any.whl

Download URL agenticml_lite-1.0.0-py3-none-any.whl
Size 303.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d3cd92a16ff325483efae51f9476e68c87f708258daddf5c902db8e303086dfd
BLAKE2b-256 checksum
How to use checksums
af2d982c8c240a0ade675f0639758d9fdf350898bcd692666da4c0b80cfb1265
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for agenticml-lite 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agenticml_lite-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page