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. 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: AGENTICML_MODE=offline writes a journal locally; agenticml sync replays it.
• Distributed-aware: standard rank env vars detected; non-rank-0 ranks become silent no-ops.

Configuration

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.

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_MODE=offline python train.py
# ...later, from a machine with network access:
agenticml sync --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.