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.

<br>

crafted with ♥ in MTL · NYC · FLPby 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

The operator scans your code for workflows, then loads and runs them:

uv run ava operator

The Web UI reflects the state of the oeprator:

uv run ava web

Start the operator and Web UI together:

uv run ava dev

You can pass --flows to operator or dev to point the operator scan to a certain file or directory:

uv run ava dev --flows ./flow.py

Otherwise, the scan defaults to the current working directory.

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]
ava dev or ava operator without --flows scans every eligible Python file below the current
working directory. Run it only from a dedicated flow workspace; otherwise pass
a specific flow file or flow-only directory with --flows.

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 the operator UI

Release the package independently from the Python distribution:

1. Update web/operator/package.json with the next semantic version.
2. From the repository root, run make web-test and make web-lint.
3. From web/operator, run pnpm pack.
4. Merge the version change to main.
5. Create and push a matching operator-ui-vX.Y.Z tag.

The Release operator UI workflow validates the tag, packs and inspects the archive, then
publishes it to GitHub Packages.

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&#39;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.

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&#39;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

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.