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.

Installation

Starter project

We recommend starting with the default Avalanche project, which includes everything you need to get started quickly on your first workflow. Just create an empty directory, cd into it and run:

uvx avalanche-ai init

Follow the instruction to set up your LLM provider

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

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

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.

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.

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.

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

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.