Avalanche

Avalanche makes agents first-class steps in typed data pipelines. Compose adaptive agent work with deterministic Python transformations in one DAG, run it through the Avalanche operator, and inspect every run from the web UI.

crafted with ♥ in MTL · NYC · FLP
by Trampoline AI

Note

Avalanche is an early release candidate intended for local development and experimentation. APIs and operational behavior may change before a stable release.

Requirements

• Python 3.11, 3.12, or 3.13.
• A LLM provider API key or Codex subscription for agent steps.
• uv (recommended, https://docs.astral.sh/uv/)

Quickstart

Move into an empty directory, then run this command to initialize a starter project with the Avalanche skill installed and an example workflow:

uvx avalanche-ai init

Follow the instructions to set up your LLM provider. Then finally, run the demo:

uv run ava dev

This starts the operator and opens the browser UI at http://127.0.0.1:7435.

You can then use the provided avalanche skill to create your own workflow by describing your wanted outcome to your agent:

/avalanche <outcome>

Installation

Option A — Starter project (recommended)

Create an empty directory, move into it, and run:

uvx avalanche-ai init

Follow the instructions to set up your LLM provider.

This installs a ready-to-run starter project with project dependencies, the Avalanche authoring skill, provider setup, and an example workflow. Its key structure is:

.
├── .agent/
│   └── skills/
│       └── avalanche/                # Avalanche workflow creation skill
├── scripts/
│   └── configure-provider.sh         # LLM provider setup
├── src/                              # workflows live here
│   └── binary_converter/
│       └── flow.py                   # included example workflow
├── AGENTS.md                       
├── pyproject.toml                  
└── uv.lock

When run from an interactive terminal, the bootstrapper offers provider setup immediately. To change providers or credentials later in the starter project:

bash scripts/configure-provider.sh

Local checkout dependencies

To develop Avalanche and PredictRLM alongside a new workspace, initialize an empty directory with editable dependencies:

uvx avalanche-ai init --editable-deps

This clones both Trampoline AI projects into .trampoline-ai/ and configures them as local editable dependencies, so changes to either checkout are used immediately by the workspace.

Option B — Existing project

Avalanche is also usable as a project dependency.

Add Avalanche to an existing project:

uv add avalanche-ai

Install the avalanche skill in the same project:

npx skills add Trampoline-AI/avalanche

Usage

Creating a workflow

Avalanche workflows chain deterministic @ava.step and agent-backed @ava.agent_step nodes inside an @ava.workflow.

@ava.step
def step1() -> str:
    return "Hello world"

@ava.agent_step(ava.Signature("text: str -> completion: str"))
async def step2(text: str, *, agent: ava.Agent) -> str:
    return (await agent(text=text)).completion

@ava.workflow
def feedback_workflow():
    return step1() >> step2()

We recommend using the skill directly in order to have your agent align on a goal and build a workflow for you.

Open your coding agent in the same project where you installed avalanche, then:

/avalanche <Describe your wanted outcome here>

for codex:

$avalanche <Describe your wanted outcome here>

Running the operator and Web UI

In a workspace configured with [tool.avalanche].flow_targets, the operator scans that code for workflows, then loads and runs them:

uv run ava operator

The Web UI reflects the state of the operator:

uv run ava web

Start the operator and Web UI together from a configured workspace:

uv run ava dev

ava init writes this workspace configuration, so the starter command scans every Python workflow below src/:

[tool.avalanche]
flow_targets = ["src"]

operator and dev use flow_targets when positional FLOW values are omitted. Configuration paths are relative to that pyproject.toml. Passing one or more FLOW values replaces the configuration rather than adding to it:

uv run ava operator ./flows ./shared_flows --port 7433

Without explicit targets or a nonempty flow_targets setting, the command stops before starting services. It never scans the current directory by default.

Discovery allows 60 seconds per scan by default. Pass --discovery-timeout SECONDS to ava operator or ava dev to set a different positive, finite limit.

Warning

Discovery imports eligible Python modules beneath each target. Use a specific flow file or dedicated flow directory, not a mixed repository root.

Similarily, you can pass --connect to the Web UI to change the operator url to connect to:

uv run ava web --connect localhost:7433

The operator defaults to 127.0.0.1:7433 and the Web UI to http://127.0.0.1:7435.

Embedding the operator UI

@trampoline-ai/operator-ui is the embeddable React package for an Avalanche operator interface. It exports OperatorUi, WorkflowWorkspace, GrpcWebOperatorApi, and their typed host APIs. The embedding host owns its OperatorApi implementation and presentation configuration.

After a version is released, configure the GitHub Packages scope and an authenticated token outside source control:

@trampoline-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Then install that version and its styles:

pnpm add @trampoline-ai/operator-ui@<version>

import "@trampoline-ai/operator-ui/styles.css";
import { OperatorUi } from "@trampoline-ai/operator-ui";

Avalanche does not provide a remote operator endpoint or authentication boundary for an embedding host.

Releasing Avalanche and the operator UI

The Python distribution and @trampoline-ai/operator-ui share one version and one Avalanche vX.Y.Z release tag. There are no separate operator UI releases, even when only the backend changes. Use the UI version matching your Avalanche operator.

1. Update pyproject.toml, src/avalanche/__init__.py, and web/operator/package.json together, and run uv lock. Stable versions are identical; prereleases use Python spelling such as 0.4.0rc1 and npm spelling 0.4.0-rc1 (likewise Python a/b map to npm alpha/beta).
2. Move the unreleased changelog entries under the new version.
3. Run make web-test, make web-lint, make web-assets-check, and uv build. From web/operator, run pnpm pack to check the npm archive.
4. Merge the release commit to main, then create and push the matching Avalanche tag, such as v0.4.0 or v0.4.0-rc1. Prereleases must have patch version zero.

The Release workflow checks both versions, generated clients, browser tests and assets, and the npm archive before publishing either package. It publishes Python distributions to PyPI and the UI to GitHub Packages (latest for stable versions, next for prereleases). The GitHub Release appears only after both publishes succeed.

The two registries cannot publish atomically. If one publish fails, rerun the failed jobs in the same workflow run to reuse its validated artifacts; do not move the tag or bump just one package. PyPI skips files already uploaded. The npm publisher skips an existing version only when its archive integrity matches, and fails on conflicting contents or registry errors. Re-running an already published UI does not move its npm distribution tag, so retrying an older release does not change latest or next.

Running a workflow

Once you have the operator running, you can either start workflows directly in the web UI, or start runs from your command line in a different terminal:

uv run ava run <workflow_name>

TUI

Avalanche also ships with a Terminal UI, that you can launch on the operator:

uv run ava tui --connect localhost:7433

The operator defaults to port 7433.

Workflow inputs

Avalanche supports passing inputs to workflows using the BaseInput class. Learn more in the DAG API's input and context guide. You can pass inputs directly in the Web UI using small JSON editor, or through the command line:

uv run ava run <workflow_name> --input '{"key": "value"}'

Embedded workflows

You can run a workflow directly from Python. .run() returns an awaitable RunHandle; call .result() to wait synchronously:

run = feedback_workflow().run(executor=ava.LocalExecutor())
print(run.run_id)
result = run.result()

Quick Example

import random
import avalanche as ava

@ava.source
def generate_binary() -> str:
    length = random.randint(128, 256)
    return "1" + "".join(random.choice("01") for _ in range(length - 1))

@ava.agent_step(
    ava.Signature(
        "binary: str -> decimal: str",
    ),
    lm="openai/gpt-5.6-terra",
)
async def convert_binary(binary: str, *, agent: ava.Agent) -> str:
    return (await agent(binary=binary)).decimal

@ava.dest
def print_result(result: str) -> str:
    print(result)
    return result


@ava.workflow
def binary_converter():
    return generate_binary() >> convert_binary() >> print_result()

Examples

The examples/ directory contains runnable workflows. Start with the customer feedback review, a production-shaped agentic data-transformation workflow; the rest are focused pattern demos.

Example	Description
Customer feedback review	End-to-end agentic workflow: parallel theme/risk analysis of a feedback workbook, deterministic reconciliation, and published Excel + Word review pack.
complex_dag_pattern.py	Local DAG API with explicit data passing, fan-out, and fan-in onava.LocalExecutor.
stream_pattern.py	Stream-based incremental processing with local Iceberg tables.
cursor_pattern.py	Manual checkpoint control with cursors for advanced incremental flows.
document_file_workflow.py	Typedava.File inputs and outputs through a BaseInput workflow.
operator_workflow.py	Flow file for the local operator and connected TUI path.

See examples/README.md for how to run each example.

LLM providers and models

Avalanche sends agent-model requests through LiteLLM. Any provider and model supported by LiteLLM is therefore supported by Avalanche. Configure the provider credentials as environment variables documented in LiteLLM's provider guide; the process running the operator must have access to those variables.

We select models on each @ava.agent_step with LiteLLM's provider-qualified model identifier. lm selects the main model and sub_lm selects the sub-model:

@ava.agent_step(
    ExtractThemes,
    lm="openai/gpt-5.6-terra",
    sub_lm="gemini/gemini-3.5-flash",
)
async def extract_themes(..., *, agent: ava.Agent) -> ThemeReport:
    ...

When a workflow's agent steps share models, we set them once with @ava.workflow(agent_defaults=...):

@ava.workflow(
    agent_defaults={
        "lm": "openai/gpt-5.6-terra",
        "sub_lm": "gemini/gemini-3.5-flash",
    }
)
def feedback_workflow():
    return extract_themes()

An lm or sub_lm passed to an individual agent step overrides the same workflow default. agent_defaults configures runtime options only; signatures, skills, and tools remain defined on each agent step.

Optional components

Extra	Purpose
ray	Ray-backed workflow execution
lance	Lance storage backend

The remaining extras can be combined:

uv add "avalanche-ai[ray,lance]"

Documentation

• DAG API
• Agent steps
• Data model and storage API
• Execution services
• Architecture
• Examples
• Changelog

Contributing

Contributions are welcome. See CONTRIBUTING.md for local setup, quality gates, and pull request expectations.

License

Avalanche is licensed under the Apache License 2.0.