Metadata-Version: 2.4
Name: flujo
Version: 0.4.35
Summary: Production-ready orchestration for AI agents, built with Pydantic.
Project-URL: Homepage, https://github.com/aandresalvarez/flujo
Project-URL: Repository, https://github.com/aandresalvarez/flujo
Project-URL: Documentation, https://aandresalvarez.github.io/flujo/
Project-URL: Bug_Tracker, https://github.com/aandresalvarez/flujo/issues
Project-URL: Changelog, https://github.com/aandresalvarez/flujo/blob/main/CHANGELOG.md
Author-email: Alvaro <aandresalvarez@gmail.com>
License: AGPL-3.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: pydantic-ai>=0.4.2
Requires-Dist: pydantic-evals>=0.0.47
Requires-Dist: pydantic-settings
Requires-Dist: pydantic<2.13,>=2.11.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: tenacity>=8.2
Requires-Dist: typer>=0.12
Provides-Extra: bench
Requires-Dist: numpy; extra == 'bench'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'bench'
Provides-Extra: dev
Requires-Dist: bandit>=1.7.5; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: cyclonedx-py; extra == 'dev'
Requires-Dist: cyclonedx-python-lib<9,>=5.2.0; extra == 'dev'
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: logfire>=0.3; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pip-audit; extra == 'dev'
Requires-Dist: prometheus-client<0.23.0,>=0.22.1; extra == 'dev'
Requires-Dist: psutil>=5.9.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-xdist; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: sqlvalidator>=0.0.8; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: vcrpy; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Provides-Extra: lens
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.20; extra == 'lens'
Requires-Dist: opentelemetry-sdk<2.0,>=1.20; extra == 'lens'
Requires-Dist: prometheus-client<0.23.0,>=0.22.1; extra == 'lens'
Provides-Extra: logfire
Requires-Dist: logfire>=0.3; extra == 'logfire'
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-sdk>=1.26; extra == 'opentelemetry'
Provides-Extra: prometheus
Requires-Dist: prometheus-client<0.23.0,>=0.22.1; extra == 'prometheus'
Provides-Extra: sql
Requires-Dist: sqlvalidator>=0.0.8; extra == 'sql'
Description-Content-Type: text/markdown

<div align="center">

<img src="assets/flujo.png" alt="Flujo logo" width="180"/>

**Beyond Agents: Build AI Employees.**

</div>

---

> **TL;DR**
> Flujo is a Python framework that turns AI **agents** into production‑grade **digital employees**—with persistent memory, proactive budgeting, and continuous learning.

> **Approaching v1.0**  Core APIs (`@step`, `>>`, `Flujo`, state back‑ends) are stable. Pin your version and watch the changelog.

> **Flexible Licensing**  Dual‑licensed **AGPL‑3.0 / Commercial**. See [`LICENSE`](LICENSE) for details.

---

# Meet Flujo — The Framework for AI Employees That Deliver

Moving AI from prototype to production shouldn't mean chaos. Flujo provides the framework to build AI workflows as reliable, accountable, and effective as your best employees.

## Give Your AI Agents the Traits of a Perfect Employee

### ✅ Never Forgets (**Durability**)

* **Problem:** AI workflows often crash and lose progress.
* **Flujo's Solution:** Automatically save state with built‑in **SQLite**, resuming exactly where tasks left off.

### ✅ Keeps Spending in Check (**Governance**)

* **Problem:** AI processes can overspend unpredictably.
* **Flujo's Solution:** Set strict usage limits (e.g., `$0.50` per run); proactive cost guards halt execution before you overspend.

### ✅ Learns from Mistakes (**Improvement Loop**)

* **Problem:** Debugging AI is slow and manual.
* **Flujo's Solution:** `flujo improve` analyzes failures and auto‑generates concrete prompt and config suggestions.

### ✅ Knows When to Escalate (**Safety Rails**)

* **Problem:** AI can't handle every edge‑case alone.
* **Flujo's Solution:** Route edge cases to human approval with `Step.branch_on` and `Step.human_in_the_loop`.

### ✅ Communicates Clearly (**Observability**)

* **Problem:** AI tasks are a black box until they fail.
* **Flujo's Solution:** Get real‑time updates via event hooks and full run histories with the `flujo lens` CLI.

---

## Simple Python Workflow, Powerful Results

```python
from flujo import step, Flujo, Step, make_agent_async

@step
async def validate_input(text: str) -> str:
    if not text:
        raise ValueError("Input required.")
    return text

summariser = make_agent_async(
    model="openai:gpt-4o-mini",
    system_prompt="You are an expert summariser.",
    output_type=str,
)

pipeline = validate_input >> Step.model_validate({"name": "Summarise", "agent": summariser})

print(Flujo(pipeline).run("Flujo is...").step_history[-1].output)
```

---

## The Flujo Advantage

* ✅ **Build Autonomous Systems:** Compose agents that handle routine work and escalate edge cases with `Step.human_in_the_loop`.
* ✅ **Run with Production-Grade Efficiency:** Execute tasks concurrently with `Step.parallel`, eliminate redundant work with `Step.cached`, and rely on a high‑performance runtime.
* ✅ **Maintain Full Accountability:** Get a complete, persistent history of every run. Use the `flujo lens` CLI to trace decisions and debug failures.
* ✅ **Integrate with Your Stack:** `@step` turns any `async` Python code into a durable workflow component. Event hooks connect Flujo to your existing monitoring and notification tools.

---

## Showcase: A Stateful, Budget‑Aware AI Financial Analyst

This example builds a multi‑agent workflow that analyzes a list of companies, persists its state to SQLite, and halts if the total cost exceeds a 15¢ budget.

```python
# examples/financial_analyst.py
from flujo import (
    Flujo, Step, step, UsageLimits, make_agent_async
)
from flujo.state import SQLiteBackend
from flujo.domain.models import PipelineContext
from flujo.domain.dsl.step import adapter_step
from pydantic import Field

# 1️⃣ Define a shared context ("memory") for the run
class MarketCtx(PipelineContext):
    companies: list[str] = Field(default_factory=list)

# 2️⃣ Define steps using Python code and AI agents
@step
async def fetch_data(company: str) -> dict:
    return {"company": company, "data": f"Financial info for {company}"}

@adapter_step
async def select_data(fetched: dict) -> str:
    return fetched.get("data", "")

summariser = make_agent_async(
    model="openai:gpt-4o-mini",
    system_prompt="Summarise the financial data point.",
    output_type=str,
)

# 3️⃣ Compose steps into a high‑level workflow
analysis_flow = fetch_data >> select_data >> Step.model_validate({
    "name": "Summarise",
    "agent": summariser
})

pipeline = Step.map_over(
    "AnalyseAllCompanies",
    analysis_flow,
    iterable_input="companies",
)

# 4️⃣ Execute the workflow with durability and governance
runner = Flujo(
    pipeline,
    context_model=MarketCtx,
    state_backend=SQLiteBackend("financial_reports.db"),
    usage_limits=UsageLimits(total_cost_usd_limit=0.15),
)

result = runner.run(
    initial_input=None,
    initial_context_data={"companies": ["Alpha", "Beta", "Gamma"]},
)
print(result.step_history[-1].output)
```

> This example is fully runnable. Copy it to a file and run with your `OPENAI_API_KEY`.

---

## Flujo vs Alternatives

| Feature                   | **Flujo**         | LangChain / LangGraph | Crew AI     | n8n / Make     |
| ------------------------- | ----------------- | --------------------- | ----------- | -------------- |
| Built‑in Persistent State | ✅ SQLite          | ⚠️ External store     | ⚠️ External | 🔒 Hidden SaaS |
| Proactive Cost Governor   | ✅                 | ❌                     | ❌           | ❌              |
| Self‑Improvement Loop     | ✅ `flujo improve` | ⚠️ Observe‑only       | ❌           | ❌              |
| Self‑Hosting Friendly     | ✅                 | ⚠️ Needs infra        | ⚠️ Needs DB | ❌              |
| Licence                   | AGPL / Commercial | MIT                   | MIT         | Proprietary    |

---

## Roadmap — Reliability at Scale

| Capability                | Status        |
| ------------------------- | ------------- |
| ✅ Persistent & Durable    | **Done**      |
| ✅ Budget Controls         | **Done**      |
| ✅ Parallel & Caching      | **Done**      |
| ✅ Conditional Routing     | **Done**      |
| 🟡 Notifications & Hooks  | *In Progress* |
| 🗺️ Security & Compliance | *Upcoming*    |

---

## Quick Start (60 seconds)

### For Users
```bash
pip install flujo

echo '
from flujo import step

@step
async def hello(name: str) -> str:
    return f"Hello, {name}!"

# The `flujo run` CLI looks for a top‑level variable named "pipeline"
pipeline = hello
' > hello_pipeline.py

flujo run hello_pipeline.py --input "Flujo"
```

> Expected output: `Hello, Flujo!`

### For Developers
```bash
# Clone and install with robust verification
git clone https://github.com/aandresalvarez/flujo.git
cd flujo
make install-robust

# Run tests
make test

# Try the quickstart example
python examples/00_quickstart.py
```

> See [INSTALLATION.md](INSTALLATION.md) for comprehensive setup instructions.

---

## Get Involved

* 📖 **[Documentation](docs/index.md)** — Guides, tutorials, API reference
* 💰 **[Budget-Aware Workflows](docs/cookbook/budget_aware_workflows.md)** — Production cost control with loops and parallel execution
* 🤝 **[Contribute](CONTRIBUTING.md)** — Join the community and shape Flujo's future

---

## Licensing

Flexible **AGPL‑3.0 / Commercial**. See the [`LICENSE`](LICENSE) file for details.
