Metadata-Version: 2.4
Name: agenticml-py
Version: 0.0.2
Summary: Python SDK for the AgenticML platform. Installs as `agenticml-py`, imports as `agenticml`.
Author-email: Gaurav Singh <gaurav.singh@agenticml.xyz>
License: MIT
Project-URL: Homepage, https://agenticml.xyz
Project-URL: Source, https://github.com/agenticML/agenticml
Project-URL: Issues, https://github.com/agenticML/agenticml/issues
Keywords: mlops,experiment-tracking,machine-learning,agentic
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Provides-Extra: system
Requires-Dist: psutil>=5.9; extra == "system"
Provides-Extra: gpu
Requires-Dist: nvidia-ml-py>=12; extra == "gpu"
Provides-Extra: media
Requires-Dist: Pillow>=10.0; extra == "media"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: psutil>=5.9; extra == "dev"
Requires-Dist: Pillow>=10.0; extra == "dev"
Requires-Dist: responses>=0.24; extra == "dev"
Dynamic: license-file

# agenticml-py

Python SDK for the [AgenticML](https://agenticml.xyz) 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

```bash
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

```python
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.
- **Code snapshots**: every file in your repo (respecting `.gitignore` + `.agenticmlignore`) plus AST-traced local imports. Content-addressed: re-runs only upload bytes the server doesn't have. 10 MB/file, 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

| Env var                 | Default                       | Purpose                               |
| ----------------------- | ----------------------------- | ------------------------------------- |
| `AGENTICML_HOST`        | `https://api.agenticml.xyz`   | Server base URL                       |
| `AGENTICML_API_KEY`     | _(none)_                      | Sent as `Authorization: Bearer <key>` |
| `AGENTICML_MODE`        | `online`                      | `online`, `offline`, or `disabled`    |
| `AGENTICML_OFFLINE_DIR` | `~/.agenticml/offline`        | Where offline journals are written    |

## Offline mode

```bash
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

```bash
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*`:

```bash
# 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](LICENSE).
