agenticml-py

Python SDK for the AgenticML experiment-tracking platform — metrics, config, code snapshots, artifacts, media, and system metrics.

⚠️ Pre-alpha. The public API is not yet stable. Pin exact versions if you depend on this.

📦 Note on naming: install as agenticml-py, import as agenticml.

Install

pip install agenticml-py

# Optional extras
pip install "agenticml-py[system]"   # CPU/RAM/disk system metrics
pip install "agenticml-py[gpu]"      # NVIDIA GPU metrics
pip install "agenticml-py[media]"    # Image logging from numpy/PIL

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()

What you get

• Module-level API: init / log / finish / config / summary / log_artifact. One active run per process, like wandb. A Run class is also exported for multi-run cases and as a context manager.
• Auto-incrementing step with optional commit=False to merge metrics from multiple sources at the same step.
• Runtime source snapshots: project code actually imported and project files actually opened for reading. track_model(model) copies architecture .py (plus agenticml/model.json) without uploading site-packages. track_optimizer / track_loss / track_dataloader capture class identity and hyperparameters the same way. Content-addressed: re-runs only upload bytes the server doesn't have. 10 MB/file and 100 MB total caps by default.
• Artifacts with auto-versioning: agenticml.log_artifact(path, name, type, metadata).
• Media: agenticml.Image(data, caption) accepts paths, bytes, PIL.Image, or numpy arrays.
• System metrics: psutil (CPU/RAM/disk) and pynvml (GPU) sampled in the background and logged as _system/....
• Resume: init(id=..., resume="allow"|"must").
• Offline mode: mode="offline" (or AGENTICML_MODE=offline) writes a journal locally; offline_dir= chooses the folder (else AGENTICML_OFFLINE_DIR / ~/.agenticml/offline). agenticml sync replays it.
• Distributed-aware: standard rank env vars detected; non-rank-0 ranks become silent no-ops.

Configuration

init(..., offline_dir=...) is offline-only and overrides AGENTICML_OFFLINE_DIR. Passing it with mode="online" or mode="disabled" raises ValueError. init(..., verbose=True) prints the run id and resolved asset paths (or host) to stdout after the run exists.

Source tracking

Runtime-used tracking is enabled by default. AgenticML observes source modules and input files while the run is active, then creates and uploads a SHA-256 manifest during finish().

agenticml.init(
    project="demo",
    name="training",
    track_source="runtime",             # default
    source_roots=["../shared_templates"],
    extra_files=["settings.yaml"],
)

track_source="repo" retains the earlier full-repository walk with static AST import discovery. track_source=True is a compatibility alias for "runtime"; False disables source tracking. .gitignore and .agenticmlignore apply to automatic discovery in runtime and repository modes; an explicit extra_files/track_files() path overrides those patterns.

Call track_model after the object exists if you need the defining source of one third-party (or local) architecture class. Site-packages remain excluded from automatic scans; only the staged copies are attached. Optimizer, loss, and dataloader objects use the same pattern — hyperparameters and class identity, not weights, tensors, or dataset files. init(model=) / init(optimizer=) are not supported; call the track_* helpers after the objects exist:

agenticml.init(project="demo", name="asr")
model = Wav2Vec2ForCTC.from_pretrained("facebook/wav2vec2-base-960h")
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)
criterion = torch.nn.CrossEntropyLoss()
agenticml.track_model(model)
agenticml.track_optimizer(optimizer)
agenticml.track_loss(criterion)
agenticml.track_dataloader(train_loader, name="train")
agenticml.track_dataloader(val_loader, name="val")

Resource reads before agenticml.init() cannot be observed, so pass those files through extra_files. Imported modules already present in sys.modules are still detected. Snapshot contents are read at finish(); files deleted before then are listed as missing rather than uploaded.

See Runtime source tracking for lifecycle, safety, migration, and troubleshooting details.

Offline mode

agenticml.init(
    project="demo",
    name="asr",
    mode="offline",
    offline_dir="/data/experiments/agenticml",  # optional; else env / ~/.agenticml/offline
    verbose=True,  # print run id + journal/code/artifacts/media paths
)

Assets land in <offline_dir>/<run_id>/ (journal.jsonl, code/, artifacts/, media/). offline_dir is rejected unless the resolved mode is "offline".

AGENTICML_MODE=offline python train.py
# ...later, from a machine with network access:
agenticml sync --dir /data/experiments/agenticml --host https://api.agenticml.xyz --api-key $AGENTICML_API_KEY

Development

git clone https://github.com/agenticML/agenticml.git
cd agenticml
pip install -e ".[dev]"
pytest

Releasing

Releases are published to PyPI via GitHub Actions on tags matching v*:

# bump version in pyproject.toml and src/agenticml/__init__.py
git commit -am "release: v0.0.3"
git tag v0.0.3
git push --tags

License

MIT — see LICENSE.