buildathena-sdk 0.3.20

Athena Labs Python SDK for agentic ML workflow orchestration

buildathena-sdk

Python SDK for building blocks and workflows on the Athena Labs 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

pip install buildathena-sdk

Requires Python 3.11+.

Quick Start

Define a block, read resolved config from ctx.config, emit metrics and progress, and register an explicit artifact when you want a durable named asset:

from athena import BlockContext, ConfigRef, block

@block(
    name="TrainModel",
    config=ConfigRef(search_path="conf", config_name="train"),
)
async def train_model(ctx: BlockContext) -> dict:
    epochs = int(ctx.config.get("epochs", 100))
    learning_rate = float(ctx.config.get("learning_rate", 1e-3))

    for epoch in range(epochs):
        loss = train_epoch(lr=learning_rate)
        await ctx.emit_metric("loss", loss, step=epoch)
        await ctx.emit_progress(epoch + 1, 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

Block inputs come from the Python signature after ctx. Athena hydrates those arguments from upstream outputs before invoking the block:

@block(name="Evaluate", outputs=["report"])
async def evaluate(ctx: BlockContext, checkpoint) -> dict:
    checkpoint_ref = 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:

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

Declare outputs on the decorator and return a mapping with exactly those keys.

Cooperative Pause

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

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

BlockContext API

Method / Accessor	Description
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:

# 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 for $include, $extends, and ${ref} substitution.

Documentation

• Getting Started — installation and first workflow
• SDK Reference — decorators, config, and discovery
• BlockContext API — full method reference
• Features — gates, inspectors, caching, and more
• knowledge-base/current/architecture/sdk.md — internal architecture and implementation reference

License

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