Skip to main content

Python API Reference

cascadeflow exposes a three-tier API for Python. Each tier adds more control.

Quick Start

import cascadeflow

# Tier 1: Global activation
cascadeflow.init(mode="observe")

# Tier 2: Scoped run with constraints
with cascadeflow.run(budget=0.50) as session:
    result = await agent.run("Analyze this data")
    print(session.summary())

# Tier 3: Per-agent policy
@cascadeflow.agent(budget=0.20, compliance="gdpr")
async def my_agent(query: str):
    return await llm.complete(query)

API Surface

FunctionPurposeDocs
cascadeflow.init()Activate the harness globallyReference
cascadeflow.run()Create a scoped run context with constraintsReference
@cascadeflow.agent()Attach per-agent policyReference
HarnessConfigFull configuration dataclassReference
HarnessRunContextSession object with summary() and trace()Reference

Install

pip install cascadeflow
With framework extras:
pip install "cascadeflow[langchain]"
pip install "cascadeflow[openai-agents]"
pip install "cascadeflow[crewai]"
pip install "cascadeflow[google-adk]"

Modes

ModeBehavior
offDisabled — no tracking, no enforcement
observeTrack all calls, log what would happen, enforce nothing
enforceActive control — budget caps, model switching, stop actions

Actions

In enforce mode, the harness can take four actions at each decision boundary:
ActionEffect
allowProceed with the original model
switch_modelRoute to a different model
deny_toolBlock a tool call
stopHalt the run (budget exceeded, policy violation)