flowra 0.0.1__tar.gz

flowra-0.0.1/.claude/commands/update-pricing.md

@@ -0,0 +1,48 @@
+# Update Pricing
+
+Update the LLM pricing tables in `flowra/llm/pricing/` with current pricing from the web.
+
+## Instructions
+
+You are updating the hardcoded pricing tables for LLM models used by this project.
+
+### Project structure
+
+Pricing is split into three modules by API protocol (not by vendor):
+
+- `flowra/llm/pricing/anthropic.py` — Anthropic Claude models. Fields: input, output, cache_read, cache_creation_5m, cache_creation_1h.
+- `flowra/llm/pricing/openai.py` — OpenAI + OpenAI-compatible (Mercury/Inception, etc.). Fields: input, output, cache_read. Cache creation is free.
+- `flowra/llm/pricing/google.py` — Google Gemini models. Fields: input, output, cache_read. Cache creation is free.
+
+Each module has a `PRICING: list[tuple[str, ModelPricing]]` table ordered longest-key-first for correct substring matching.
+
+### Steps to follow
+
+1. **Read current pricing tables**: Read all three files in `flowra/llm/pricing/` to see existing models and prices.
+
+2. **Determine which models to update**:
+   - If the user provided arguments (e.g., `/update-pricing all Gemini models`), search for pricing for those specific models PLUS all existing models in the tables.
+   - If no arguments were provided, refresh pricing for all existing models in all three tables.
+
+3. **Web search for current pricing**: Use WebSearch to find the most up-to-date pricing for:
+   - All models currently in the pricing tables
+   - Any additional models the user requested
+   - Search for official pricing pages: Anthropic (anthropic.com/pricing), OpenAI (openai.com/api/pricing), Google Cloud (cloud.google.com/vertex-ai/generative-ai/pricing)
+
+4. **Update the pricing tables**:
+   - Update existing entries with the latest pricing
+   - Add new entries for any models the user requested
+   - Remove entries for deprecated/discontinued models if appropriate
+   - **IMPORTANT**: Keep keys ordered longest-first to ensure correct substring matching. For example, `"gpt-4o-mini"` must come before `"gpt-4o"`.
+   - Place new models in the correct position by key length
+
+5. **Verify the changes**: After updating, briefly summarize what was changed (which models were updated, added, or removed) per module.
+
+## Important notes
+
+- All prices are in dollars per 1 million tokens
+- `cache_read` should be 0 for models that don't support prompt caching
+- Anthropic has separate 5-minute and 1-hour cache creation prices. 5-minute = 1.25x base input, 1-hour = 2x base input. Cache read is the same for both TTLs (0.1x base input).
+- OpenAI and Google cache creation is free (automatic) — no cache_creation field in their ModelPricing
+- Model matching uses substring matching, so keys should be specific enough to avoid false matches but general enough to match version suffixes (e.g., `"claude-sonnet-4-5"` matches `"claude-sonnet-4-5@20250929"`)
+- Always prioritize official pricing pages from model providers

flowra-0.0.1/.env.example

@@ -0,0 +1,8 @@
+VERTEX_CREDENTIALS=
+VERTEX_PROJECT_NAME=
+VERTEX_LOCATION=
+OPENAI_API_KEY=
+OPENAI_BASE_URL=https://eu.api.openai.com/v1
+OPENAI_ORGANIZATION=
+INCEPTION_BASE_URL=https://api.inceptionlabs.ai/v1
+INCEPTION_API_KEY=

flowra-0.0.1/.github/workflows/master.yml

@@ -0,0 +1,40 @@
+name: master
+
+on:
+  push:
+    branches:
+    - master
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test_lint:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python ${{ matrix.python }}
+        run: echo ${{ matrix.python }} > .python-version
+      - name: Install deps
+        run: MODE=ci make deps
+      - name: Run lint
+        run: MODE=ci make lint
+      - name: Run all tests
+        run: MODE=ci make test
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_ORGANIZATION: ${{ secrets.OPENAI_ORGANIZATION }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          VERTEX_PROJECT_NAME: ${{ vars.VERTEX_PROJECT_NAME }}
+          VERTEX_LOCATION: ${{ vars.VERTEX_LOCATION }}
+          VERTEX_CREDENTIALS: ${{ secrets.VERTEX_CREDENTIALS }}

flowra-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,132 @@
+name: publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      type:
+        description: "Release type"
+        required: true
+        type: choice
+        options:
+          - pre-release
+          - release
+
+jobs:
+  publish_prerelease:
+    if: inputs.type == 'pre-release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install deps
+        run: MODE=ci make deps
+      - name: Run lint
+        run: MODE=ci make lint
+      - name: Run all tests
+        run: MODE=ci make test
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_ORGANIZATION: ${{ secrets.OPENAI_ORGANIZATION }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          VERTEX_PROJECT_NAME: ${{ vars.VERTEX_PROJECT_NAME }}
+          VERTEX_LOCATION: ${{ vars.VERTEX_LOCATION }}
+          VERTEX_CREDENTIALS: ${{ secrets.VERTEX_CREDENTIALS }}
+      - name: Set dev version
+        id: version
+        run: |
+          BASE=$(grep -oP '(?<=__version__ = ")[^"]+' flowra/version.py)
+          VERSION="${BASE}.dev${{ github.run_number }}"
+          sed -i "s/^__version__ = .*/__version__ = \"$VERSION\"/" flowra/version.py
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish dist/*
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      - name: Summary
+        run: echo "Published **${{ steps.version.outputs.version }}** to PyPI" >> $GITHUB_STEP_SUMMARY
+
+  publish_release:
+    if: inputs.type == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install deps
+        run: MODE=ci make deps
+      - name: Run lint
+        run: MODE=ci make lint
+      - name: Run all tests
+        run: MODE=ci make test
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_ORGANIZATION: ${{ secrets.OPENAI_ORGANIZATION }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          VERTEX_PROJECT_NAME: ${{ vars.VERTEX_PROJECT_NAME }}
+          VERTEX_LOCATION: ${{ vars.VERTEX_LOCATION }}
+          VERTEX_CREDENTIALS: ${{ secrets.VERTEX_CREDENTIALS }}
+      - name: Read version
+        id: version
+        run: |
+          VERSION=$(grep -oP '(?<=__version__ = ")[^"]+' flowra/version.py)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+      - name: Validate changelog
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          if ! grep -q "^## \[$VERSION\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no section for version $VERSION"
+            exit 1
+          fi
+      - name: Validate branch
+        run: |
+          if [ "${{ github.ref_name }}" != "master" ]; then
+            echo "::error::Release must be published from master, got ${{ github.ref_name }}"
+            exit 1
+          fi
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish dist/*
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      - name: Create git tag
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          git tag "v$VERSION"
+          git push origin "v$VERSION"
+      - name: Extract changelog
+        id: changelog
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
+          echo "body<<$EOF" >> $GITHUB_OUTPUT
+          sed -n "/^## \[$VERSION\]/,/^## \[/{/^## \[/!p}" CHANGELOG.md >> $GITHUB_OUTPUT
+          echo "$EOF" >> $GITHUB_OUTPUT
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          body: ${{ steps.changelog.outputs.body }}
+          files: dist/*
+      - name: Bump version for next development cycle
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          # Bump patch: 0.1.0 -> 0.1.1
+          NEXT=$(echo "$VERSION" | awk -F. '{print $1"."$2"."$3+1}')
+          sed -i "s/^__version__ = .*/__version__ = \"$NEXT\"/" flowra/version.py
+          # Add new Unreleased section to changelog
+          sed -i "s/^## \[$VERSION\]/## [Unreleased]\n\n## [$VERSION]/" CHANGELOG.md
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add flowra/version.py CHANGELOG.md
+          git commit -m "Bump version to $NEXT after $VERSION release"
+          git push origin master
+      - name: Summary
+        run: echo "Published **${{ steps.version.outputs.version }}** to PyPI" >> $GITHUB_STEP_SUMMARY

flowra-0.0.1/.github/workflows/pull_request.yml

@@ -0,0 +1,32 @@
+name: pull_request
+
+on:
+  pull_request:
+    branches: [ master ]
+
+concurrency:
+  group: pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  test_and_lint:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python ${{ matrix.python }}
+        run: echo ${{ matrix.python }} > .python-version
+      - name: Install deps
+        run: MODE=ci make deps
+      - name: Run lint
+        run: MODE=ci make lint
+      - name: Run unit tests
+        run: MODE=ci make test-unit

flowra-0.0.1/.github/workflows/pull_request_e2e.yml

@@ -0,0 +1,45 @@
+name: pull_request_e2e
+
+on:
+  pull_request_target:
+    branches: [ master ]
+    types: [opened, synchronize, reopened, labeled]
+
+concurrency:
+  group: pr-e2e-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  test_e2e:
+    if: >-
+      contains(github.event.pull_request.labels.*.name, 'e2e')
+      || github.event.pull_request.author_association == 'OWNER'
+      || github.event.pull_request.author_association == 'MEMBER'
+      || github.event.pull_request.author_association == 'COLLABORATOR'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout PR code
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python ${{ matrix.python }}
+        run: echo ${{ matrix.python }} > .python-version
+      - name: Install deps
+        run: MODE=ci make deps
+      - name: Run e2e tests
+        run: MODE=ci make test-e2e
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_ORGANIZATION: ${{ secrets.OPENAI_ORGANIZATION }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          VERTEX_PROJECT_NAME: ${{ vars.VERTEX_PROJECT_NAME }}
+          VERTEX_LOCATION: ${{ vars.VERTEX_LOCATION }}
+          VERTEX_CREDENTIALS: ${{ secrets.VERTEX_CREDENTIALS }}

flowra-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.ruff_cache/
+.pytest_cache/
+.pyright/
+*.egg
+/.idea/
+.chat_sessions/
+logs/

flowra-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12

flowra-0.0.1/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com),
+and this project adheres to [Semantic Versioning](https://semver.org).
+
+## [0.0.1] - 2026-03-07
+
+Initial release.
+
+### Added
+- State machine agents with `@step` methods, `Goto`, `Spawn`, and stored values (`Scalar`, `AppendOnlyList`)
+- Provider-agnostic LLM abstraction (`LLMProvider`, `LLMRequest`, `LLMResponse`)
+- LLM providers: `AnthropicVertexProvider`, `GoogleVertexProvider`, `OpenAIProvider`
+- Tool integration: `@tool` decorator, MCP server support, DI into tool handlers
+- Execution engine with persistence, crash recovery, and cooperative interrupts
+- Pre-built agents: `ChatAgent` (multi-turn chat) and `ToolLoopAgent` (tool loop with hooks)
+- `ChatHooks` with `on_save_turn_messages` for transient message filtering
+- Optional provider dependencies via extras: `flowra[anthropic]`, `flowra[openai]`, `flowra[google]`, `flowra[all]`
+- Python 3.12, 3.13, 3.14 support

flowra-0.0.1/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+- `make deps` — install dependencies (`uv sync`; in CI with `MODE=ci` uses `--locked --no-cache`)
+- `make lock` — upgrade all dependencies (`uv lock --upgrade`)
+- `make lint` — ruff check + ruff format + pyright (auto-fixes locally; in CI with `MODE=ci` checks only)
+- `make test` — run all tests in parallel (`-n auto`)
+- `make test name="some_name"` — filter tests by name (`-k`)
+- `make test parallel=0` — run tests sequentially
+- `make test args="-vv"` — pass extra pytest arguments
+- `make check` — lint + test
+- `make example1` — run menu agent (functional style)
+- `make example2` — run menu agent (class-based style)
+- `make chat` — run interactive console chat example
+- `make chat resume=last` — resume the last chat session
+- `make chat resume=<session_id>` — resume a specific session
+- `make chat input="..."` — send a single message (batch mode)
+- `make chat crash=0.5 input="..."` — crash recovery demo
+- `make chat-tui` — run TUI chat with interrupt support
+- `make chat-tui resume=last` — resume the last TUI session
+
+## Architecture
+
+Python 3.12+ library. Package manager: **uv**. All config in `pyproject.toml`.
+
+### LLM abstraction (`flowra/llm/`)
+
+Provider-agnostic interface for calling LLMs:
+
+- `LLMProvider` (abc) — single method `async call(LLMRequest) -> LLMResponse`
+- `LLMRequest` — model, messages, tools, json_schema, temperature, max_tokens, stop_sequences
+- `LLMResponse` — message (AssistantMessage), stop_reason, usage
+- `Usage` — input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, cost_usd. Token contract: `input_tokens` excludes cached tokens
+- Messages: `SystemMessage`, `UserMessage`, `AssistantMessage` — system messages must be at the beginning of the messages list
+- Blocks: `TextBlock` (with `cache: bool` for prompt caching), `ImageBlock`, `ToolUseBlock`, `ToolResultBlock`
+- `Tool` — name, description, input_schema, output_schema, cache
+
+Providers live in `flowra/llm/providers/`. Currently: `AnthropicVertexProvider`, `OpenAIProvider`, `GoogleVertexProvider`.
+
+Pricing utilities live in `flowra/llm/pricing/` — per-protocol cost estimation (anthropic, openai, google). Providers use these to populate `Usage.cost_usd`.
+
+## Code Review
+
+Review prompts live in `docs/review_prompts/`:
+
+- `step1_structure.md` — package structure and responsibility
+- `step2_code_style.md` — code style rules (**canonical source of all style rules**)
+- `step3_documentation.md` — documentation completeness and quality
+- `step4_doc_readability.md` — documentation readability (as a first-time reader)
+- `step5_doc_audit.md` — documentation audit against source code
+- `step6_tests.md` — test quality and coverage
+
+### Tests
+
+Test directory structure mirrors `flowra/`. E2E tests use `_e2e` suffix (e.g., `test_anthropic_e2e.py`). Environment variables loaded from `.env` via Makefile.

flowra-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anna Money
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowra-0.0.1/Makefile

@@ -0,0 +1,61 @@
+-include .env
+export
+
+deps:
+ifeq ($(MODE), ci)
+	uv sync --all-extras --locked --no-cache
+else
+	uv sync --all-extras
+endif
+
+lock:
+	uv lock --upgrade
+
+lint:
+ifeq ($(MODE), ci)
+	uv run ruff check flowra/ tests/ examples/
+	uv run ruff format --check flowra/ tests/ examples/
+else
+	uv run ruff check --fix flowra/ tests/ examples/
+	uv run ruff format flowra/ tests/ examples/
+endif
+	uv run pyright
+
+# ── test parameters ──────────────────────────────────────────────────
+# Examples:
+#   make test                          # all tests, parallel
+#   make test name="some_name"         # filter by name (-k)
+#   make test parallel=0               # sequential
+#   make test parallel=4               # 4 workers
+#   make test name="e2e" parallel=0    # filter + sequential
+_TEST_ARGS = $(if $(parallel),$(if $(filter 0,$(parallel)),,-n $(parallel)),-n auto) \
+             $(if $(name),-k $(name))
+
+test:
+	uv run pytest tests/ $(_TEST_ARGS) $(args)
+
+test-unit:
+	uv run pytest tests/ --ignore=tests/llm/providers $(_TEST_ARGS) $(args)
+
+test-e2e:
+	uv run pytest tests/llm/providers/ -k e2e $(_TEST_ARGS) $(args)
+
+check: lint test
+
+example1:
+	uv run python examples/menu_agent.py $(args)
+
+example2:
+	uv run python examples/menu_agent_class.py $(args)
+
+chat:
+	CRASH_CHANCE=$(or $(crash),0) TOOL_DELAY=$(or $(delay),0) uv run python examples/console_chat.py $(if $(model),--model $(model)) $(if $(resume),--resume $(resume)) $(if $(input),--input "$(input)") $(args)
+# make chat                        — new session
+# make chat resume=last            — resume last session
+# make chat resume=<session_id>    — resume specific session
+# make chat input="What is 2+2?"   — batch mode (single message)
+# make chat crash=0.5 input="..."  — crash recovery demo
+# make chat delay=3                — slow tools (seconds)
+
+chat-tui:
+	CRASH_CHANCE=$(or $(crash),0) TOOL_DELAY=$(or $(delay),0) uv run python examples/tui_chat.py $(if $(model),--model $(model)) $(if $(resume),--resume $(resume)) $(args)

flowra-0.0.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: flowra
+Version: 0.0.1
+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.85
+Provides-Extra: all
+Requires-Dist: anthropic[vertex]; extra == 'all'
+Requires-Dist: google-genai; extra == 'all'
+Requires-Dist: openai; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic[vertex]; extra == 'anthropic'
+Provides-Extra: google
+Requires-Dist: google-genai; extra == 'google'
+Provides-Extra: openai
+Requires-Dist: openai; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Flowra
+
+**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 classes with `@step` methods that
+  transition via `Goto`, `Spawn` (parallel children), or return a result
+- **Persistent state** — `Scalar[T]` and `AppendOnlyList[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
+- **LLM abstraction** — provider-agnostic `LLMProvider` interface with immutable
+  message types (ships `AnthropicVertexProvider`, `GoogleVertexProvider`, `OpenAIProvider`)
+- **Cooperative interrupts** — `InterruptToken` for graceful cancellation across
+  the entire execution tree
+- **Pre-built agents** — `ChatAgent` (multi-turn chat with session history) and
+  `ToolLoopAgent` (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[all]
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from flowra.lib.chat import ChatAgent, ChatConfig, ChatResult, ChatSpec
+from flowra.lib import LLMConfig
+from flowra.llm import LLMProvider, SystemMessage, TextBlock
+from flowra.llm.providers.anthropic_vertex import AnthropicVertexProvider
+from flowra.runtime import AgentRuntime
+from flowra.tools import ToolRegistry
+
+
+async def main() -> None:
+    provider = AnthropicVertexProvider()
+
+    async with await ToolRegistry.create([]) as registry:
+        config = ChatConfig(
+            llm_config=LLMConfig(model="claude-sonnet-4-5@20250929"),
+            system_messages=[
+                SystemMessage(blocks=[TextBlock(text="You are a helpful assistant.")])
+            ],
+        )
+
+        runtime = AgentRuntime(
+            agents={"chat": ChatAgent},
+            services={
+                LLMProvider: provider,
+                ToolRegistry: registry,
+                ChatConfig: config,
+            },
+        )
+
+        while True:
+            user_input = input("You: ")
+            if not user_input:
+                break
+
+            result = await runtime.run(
+                agent=ChatAgent, step=ChatAgent.process_message,
+                spec=ChatSpec(user_message=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/      # State machine framework (@step, Goto, Spawn, stored values)
+├── runtime/    # Execution engine, persistence, interrupt support
+└── lib/        # Pre-built agents (ChatAgent, ToolLoopAgent, hooks, caching)
+```
+
+See [docs/architecture.md](docs/architecture.md) for the full dependency graph and
+data flow. Each package has its own documentation in `docs/`.
+
+## Development
+
+```bash
+make deps      # install dependencies (uv sync)
+make check     # lint + test
+make chat      # run interactive console chat example
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — package structure and data flow
+- [LLM](docs/llm.md) — message types, provider interface
+- [Tools](docs/tools.md) — tool definition and execution
+- [Agent](docs/agent.md) — state machine framework
+- [Runtime](docs/runtime.md) — execution engine and persistence
+- [Lib](docs/lib.md) — pre-built agents, hooks, caching