Metadata-Version: 2.4
Name: buildathena-sdk
Version: 0.3.3
Summary: Athena Labs Python SDK for agentic ML workflow orchestration
Project-URL: Homepage, https://buildathena.dev
Project-URL: Documentation, https://buildathena.dev/docs/sdk
Author-email: Athena <richard@buildathena.dev>
License: Proprietary
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: click<9.0.0,>=8.0.0
Requires-Dist: httpx<1.0.0,>=0.26.0
Requires-Dist: pydantic<3.0.0,>=2.5.0
Requires-Dist: pyyaml<7.0.0,>=6.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.2.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Description-Content-Type: text/markdown

<!-- Verified against codebase: 2026-03-21 -->

# buildathena-sdk

[![PyPI version](https://img.shields.io/pypi/v/buildathena-sdk)](https://pypi.org/project/buildathena-sdk/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)](https://buildathena.dev)

Python SDK for building blocks and workflows on the [Athena Labs](https://buildathena.dev) ML orchestration platform. Athena Labs makes ML workflows reproducible, observable, interruptible, and composable through a DAG execution engine with an AI agent that can build, run, monitor, and fix pipelines.

> **Alpha software** — APIs may change between releases. Pin your version in production.

## Installation

```bash
pip install buildathena-sdk
```

Requires Python 3.11+.

## Quick Start

Define a block with a Pydantic config class, emit metrics and progress, and register an explicit artifact when you want a durable named asset:

```python
from pydantic import BaseModel
from athena import block, BlockContext

class TrainConfig(BaseModel):
    epochs: int = 100
    learning_rate: float = 1e-3

@block(name="TrainModel", outputs=["checkpoint"], config=TrainConfig)
async def train_model(ctx: BlockContext, config: TrainConfig) -> dict:
    for epoch in range(config.epochs):
        loss = train_epoch(lr=config.learning_rate)
        await ctx.emit_metric("loss", loss, step=epoch)
        await ctx.emit_progress(epoch + 1, config.epochs)
        await ctx.check_pause()  # cooperative pause point

    checkpoint = await ctx.artifacts.register("model.pt", schema_type="checkpoint")
    return {"checkpoint": checkpoint.as_ref()}
```

## Consuming Inputs

Blocks declare their inputs and access upstream outputs through `ctx.inputs`:

```python
@block(name="Evaluate", inputs=["checkpoint"], outputs=["report"])
async def evaluate(ctx: BlockContext, config) -> dict:
    checkpoint_ref = ctx.inputs["checkpoint"]
    checkpoint_path = await ctx.artifacts.resolve(checkpoint_ref)
    model = load_model(checkpoint_path)
    score = run_eval(model)
    await ctx.emit_metric("accuracy", score)
    return {"report": {"accuracy": score}}
```

## Credentials

Declare required secrets in the `@block` decorator and access them at runtime via `ctx.secrets`. Credentials are encrypted at rest and injected only during execution:

```python
@block(name="FetchData", secrets=["API_KEY"], outputs=["dataset"])
async def fetch_data(ctx: BlockContext, config) -> dict:
    key = ctx.secrets["API_KEY"]
    data = await download(api_key=key)
    return {"dataset": data}
```

## Cooperative Pause

Call `check_pause()` inside long-running loops to let Athena Labs pause the block between iterations without losing progress:

```python
for epoch in range(config.epochs):
    train_step()
    await ctx.check_pause()  # yields control if a pause was requested
```

## BlockContext API

| Method / Accessor | Description |
|---|---|
| `ctx.inputs["name"]` | Access upstream block outputs |
| `ctx.secrets["KEY"]` | Access declared secrets |
| `await ctx.emit_metric(name, value, step=, labels=)` | Emit one scalar metric |
| `await ctx.emit_metrics({"loss": loss, "accuracy": acc}, step=, labels=)` | Emit multiple scalar metrics |
| `await ctx.emit_progress(current, total, message=)` | Emit progress (current/total) |
| `await ctx.emit_log(message, level=, source=)` | Emit a structured log event |
| `await ctx.check_pause()` | Cooperative pause checkpoint |
| `await ctx.artifacts.register(source, schema_type=, format=, name=, tags=, metadata=)` | Create a durable artifact |
| `artifact.as_ref()` / `artifact.as_data()` | Choose pointer or hydrated downstream delivery |
| `await ctx.artifacts.resolve(ref)` | Resolve any Athena-readable artifact to a local path |
| `await ctx.artifacts.load(ref)` | Load and deserialize a formatted artifact |

## Config System

Athena Labs supports YAML configuration with composition, inheritance, and variable substitution:

```yaml
# base.yaml
training:
  epochs: 100
  optimizer: adam

# experiment.yaml
$extends: base.yaml
training:
  epochs: 200
  learning_rate: ${LR:-1e-3}
```

See the [full config docs](https://buildathena.dev/docs/sdk) for `$include`, `$extends`, and `${ref}` substitution.

## Documentation

- [Getting Started](https://buildathena.dev/docs/setup) — installation and first workflow
- [SDK Reference](https://buildathena.dev/docs/sdk) — decorators, config, and discovery
- [BlockContext API](https://buildathena.dev/docs/sdk/block-context) — full method reference
- [Features](https://buildathena.dev/docs/features) — gates, inspectors, caching, and more
- [knowledge-base/current/architecture/sdk.md](../../../knowledge-base/current/architecture/sdk.md) — internal architecture and implementation reference

## License

Proprietary - Copyright (c) 2026 Athena Labs Research Inc. All rights reserved.
