Metadata-Version: 2.5
Name: flowra
Version: 0.0.76
Summary: Flowra — flow infrastructure for building stateful LLM agents
Project-URL: Repository, https://github.com/anna-money/flowra
Project-URL: Changelog, https://github.com/anna-money/flowra/blob/master/CHANGELOG.md
Project-URL: Author, https://github.com/spaceorc
Author: Ivan Dashkevich
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28
Requires-Dist: jsonschema>=4.26
Requires-Dist: marshmallow-recipe>=0.0.95
Provides-Extra: anthropic
Requires-Dist: anthropic[vertex]; extra == 'anthropic'
Provides-Extra: google
Requires-Dist: google-genai; extra == 'google'
Provides-Extra: mlflow
Requires-Dist: mlflow>=3.1; extra == 'mlflow'
Provides-Extra: openai
Requires-Dist: openai; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Provides-Extra: providers
Requires-Dist: anthropic[vertex]; extra == 'providers'
Requires-Dist: google-genai; extra == 'providers'
Requires-Dist: openai; extra == 'providers'
Description-Content-Type: text/markdown

# Flowra

[![PyPI](https://img.shields.io/pypi/v/flowra)](https://pypi.org/project/flowra/)
[![Python](https://img.shields.io/pypi/pyversions/flowra)](https://pypi.org/project/flowra/)
[![License](https://img.shields.io/pypi/l/flowra)](https://github.com/anna-money/flowra/blob/master/LICENSE)
[![CI](https://github.com/anna-money/flowra/actions/workflows/master.yml/badge.svg)](https://github.com/anna-money/flowra/actions/workflows/master.yml)

**Flow infra** for building stateful, persistent LLM agents with tool use,
parallel execution, and crash recovery. Requires Python 3.12+.

## Features

- **State machine agents** — define agents as `Agent[Spec, Result]` classes with
  `@step` methods, a single entry point, and typed spec/result contracts
- **Persistent state** — `Scalar[T]` and `MutableList[T]` with incremental
  dirty-tracking and pluggable storage (in-memory, file-based, or custom)
- **Tool integration** — `@tool` decorator for local functions, MCP server support,
  DI into tool handlers, agents as tools for LLM-driven delegation
- **LLM abstraction** — provider-agnostic `LLMProvider` interface with immutable
  message types and real-time streaming (ships `AnthropicVertexProvider`, `AnthropicFoundryProvider`, `OpenAIProvider`, `AzureOpenAIProvider`, `OpenAIResponsesProvider`, `GoogleVertexProvider`)
- **Agents as tools** — `@agent_tool` decorator exposes an agent as a tool the
  LLM can call autonomously; sub-agent runs its own system prompt and tool loop
- **Cooperative interrupts** — `InterruptToken` for graceful cancellation across
  the entire execution tree
- **Pre-built agents** — `ChatAgent` (multi-turn chat with session history) and
  `TurnAgent` (single-turn LLM tool loop with hooks and caching)

## Installation

```bash
# Base package (no LLM providers)
pip install flowra

# With specific providers
pip install flowra[anthropic]
pip install flowra[openai]
pip install flowra[google]

# All providers
pip install flowra[providers]
```

## Quick start

```python
import asyncio

from flowra.agent import AgentRuntime, InMemorySessionStorage
from flowra.lib import LLMConfig
from flowra.lib.chat import ChatAgent, ChatConfig, ChatResult, ChatSpec
from flowra.llm import SystemMessage, TextBlock
from flowra.llm.providers.openai import OpenAIProvider


async def main() -> None:
    async with OpenAIProvider(api_key="sk-...") as provider:
        config = ChatConfig(
            llm_config=LLMConfig(provider=provider, model="gpt-4o"),
            system=[SystemMessage(blocks=[TextBlock(text="You are a helpful assistant.")])],
        )

        runtime = AgentRuntime(
            agents={"chat": ChatAgent},
            storage=InMemorySessionStorage(),
            services={ChatConfig: config},
        )

        while True:
            user_input = input("You: ")
            if not user_input:
                break

            result = await runtime.run(agent=ChatAgent, spec=ChatSpec.text(user_input))

            if isinstance(result, ChatResult) and result.response:
                print(f"Assistant: {result.response}")


asyncio.run(main())
```

## Package structure

```
flowra/
├── llm/        # LLM abstraction (messages, blocks, provider interface)
├── tools/      # Tool definition, registration, execution
├── agent/      # Agent framework + execution engine + persistence
└── lib/        # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)
```

## Documentation

- **[Getting Started](docs/getting-started.md)** — from installation to a working
  chatbot with tools in 5 minutes
- [Working with LLMs](docs/llm.md) — providers, streaming, structured output,
  caching, extended thinking
- [Tools](docs/tools.md) — tool groups, MCP servers, service injection
- [Agents](docs/agents.md) — custom agents, state machines, control flow,
  parallel execution
- [Patterns](docs/patterns.md) — multi-agent patterns: router, pipeline, race,
  fan-out
- [Observability](docs/observability.md) — hooks, spans, MLflow and OTel
  integrations

## Development

```bash
make deps      # install dependencies (uv sync)
make check     # lint + test
make chat      # run interactive console chat example
```
