flowai-cli 0.2.0__py3-none-any.whl

flowai/tools/registry.py

@@ -0,0 +1,84 @@
+"""Tool Registry for tool registration, lookup, schema export, and safe execution."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from flowai.tools.base import BaseTool
+from flowai.tools.decorator import tool
+
+# Called with (tool_name, arguments); return False to refuse the call.
+Approver = Callable[[str, dict], Any]
+
+DENIED_MESSAGE = "The user declined this call. Do not retry it; ask what they would prefer instead."
+
+
+class ToolRegistry:
+    """Central store for agent tools.
+
+    A registry with an `approver` asks before running any tool marked
+    `requires_approval`. Library callers get no approver (they wrote the code
+    themselves); the CLI attaches one, because there the model picks the
+    commands and the user should see them first.
+    """
+
+    def __init__(
+        self,
+        tools: Sequence[BaseTool | Callable[..., Any]] | None = None,
+        approver: Approver | None = None,
+    ):
+        self._tools: dict[str, BaseTool] = {}
+        self.approver = approver
+        if tools:
+            for t in tools:
+                self.register(t)
+
+    def register(self, t: BaseTool | Callable[..., Any]) -> BaseTool:
+        """Register a tool instance or raw function."""
+        if not isinstance(t, BaseTool):
+            t = tool(t)
+        self._tools[t.name] = t
+        return t
+
+    def set_approver(self, approver: Approver | None) -> None:
+        """Attach (or clear) the callback consulted before approval-gated tools run."""
+        self.approver = approver
+
+    def get(self, name: str) -> BaseTool | None:
+        """Retrieve tool by name."""
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[BaseTool]:
+        """Return list of all registered tools."""
+        return list(self._tools.values())
+
+    def get_schemas(self, format: str = "openai") -> list[dict[str, Any]]:
+        """Export tool definitions in openai or anthropic schema format."""
+        if format == "anthropic":
+            return [t.to_anthropic_schema() for t in self._tools.values()]
+        return [t.to_openai_schema() for t in self._tools.values()]
+
+    async def _approved(self, tool_instance: BaseTool, kwargs: dict[str, Any]) -> bool:
+        if not tool_instance.requires_approval or self.approver is None:
+            return True
+        verdict = self.approver(tool_instance.name, kwargs)
+        if asyncio.iscoroutine(verdict):
+            verdict = await verdict
+        return bool(verdict)
+
+    async def execute(self, tool_name: str, **kwargs: Any) -> Any:
+        """Execute tool safely, surfacing errors rather than crashing the harness."""
+        tool_instance = self.get(tool_name)
+        if not tool_instance:
+            return (
+                f"Error: tool '{tool_name}' does not exist. "
+                f"Available tools: {', '.join(self._tools) or '(none)'}"
+            )
+        if not await self._approved(tool_instance, kwargs):
+            return DENIED_MESSAGE
+        try:
+            return await tool_instance.execute(**kwargs)
+        except Exception as exc:
+            return f"Error executing {tool_name}: {type(exc).__name__}: {exc}"

flowai/tools/web.py

@@ -0,0 +1,94 @@
+"""Web tools: a real search over DuckDuckGo's HTML endpoint, and a page fetcher.
+
+Neither tool invents results. If the network call fails, the agent is told it
+failed, which is far more useful to it than a plausible-looking fabrication.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from urllib.parse import parse_qs, unquote, urlparse
+
+import httpx
+
+from flowai.tools.decorator import tool
+
+SEARCH_URL = "https://html.duckduckgo.com/html/"
+USER_AGENT = "Mozilla/5.0 (compatible; FlowAI/0.1; +https://github.com/Ajayramaswamy2005/FlowAI)"
+
+_RESULT_RE = re.compile(
+    r'<a[^>]+class="result__a"[^>]+href="(?P<href>[^"]+)"[^>]*>(?P<title>.*?)</a>',
+    re.DOTALL,
+)
+_SNIPPET_RE = re.compile(r'<a[^>]+class="result__snippet"[^>]*>(?P<snippet>.*?)</a>', re.DOTALL)
+_TAG_RE = re.compile(r"<[^>]+>")
+_SCRIPT_RE = re.compile(r"<(script|style)\b.*?</\1>", re.DOTALL | re.IGNORECASE)
+
+
+def _strip_tags(markup: str) -> str:
+    return html.unescape(_TAG_RE.sub("", markup)).strip()
+
+
+def _clean_link(href: str) -> str:
+    """DuckDuckGo wraps results in a redirect; unwrap it back to the real URL."""
+    if href.startswith("//"):
+        href = "https:" + href
+    parsed = urlparse(href)
+    if "duckduckgo.com" in parsed.netloc and parsed.path.startswith("/l/"):
+        target = parse_qs(parsed.query).get("uddg")
+        if target:
+            return unquote(target[0])
+    return href
+
+
+@tool("search_web", description="Search the web with DuckDuckGo and return the top results.")
+async def search_web(query: str, max_results: int = 5) -> str:
+    """Run a web search and return titles, URLs and snippets."""
+    try:
+        async with httpx.AsyncClient(timeout=20.0, follow_redirects=True) as client:
+            response = await client.post(
+                SEARCH_URL,
+                data={"q": query},
+                headers={"User-Agent": USER_AGENT},
+            )
+            response.raise_for_status()
+            body = response.text
+    except httpx.HTTPError as exc:
+        return f"Web search failed ({type(exc).__name__}: {exc}). No results were retrieved."
+
+    titles = _RESULT_RE.findall(body)
+    snippets = _SNIPPET_RE.findall(body)
+
+    if not titles:
+        return f"No results found for '{query}'."
+
+    lines = []
+    for index, (href, title) in enumerate(titles[:max_results]):
+        snippet = _strip_tags(snippets[index]) if index < len(snippets) else ""
+        lines.append(f"{index + 1}. {_strip_tags(title)}\n   {_clean_link(href)}\n   {snippet}".rstrip())
+    return "\n".join(lines)
+
+
+@tool("fetch_url", description="Fetch a web page and return its visible text.")
+async def fetch_url(url: str, max_chars: int = 8000) -> str:
+    """Download a URL and strip it down to readable text."""
+    if not url.startswith(("http://", "https://")):
+        return "Error: url must start with http:// or https://."
+
+    try:
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            response = await client.get(url, headers={"User-Agent": USER_AGENT})
+            response.raise_for_status()
+    except httpx.HTTPError as exc:
+        return f"Fetch failed ({type(exc).__name__}: {exc})."
+
+    content_type = response.headers.get("content-type", "")
+    if "html" not in content_type and "text" not in content_type:
+        return f"Error: {url} returned {content_type or 'an unknown content type'}, which is not readable text."
+
+    text = _strip_tags(_SCRIPT_RE.sub(" ", response.text))
+    text = re.sub(r"\n{3,}", "\n\n", re.sub(r"[ \t]{2,}", " ", text))
+    if len(text) > max_chars:
+        text = text[:max_chars] + f"\n... (truncated at {max_chars} characters)"
+    return text or f"{url} returned no readable text."

flowai/workflow/__init__.py

@@ -0,0 +1,15 @@
+"""FlowAI Workflow Engine & State Management."""
+
+from flowai.workflow.checkpoint import BaseCheckpointer, FileCheckpointer, InMemoryCheckpointer
+from flowai.workflow.engine import END, START, Workflow
+from flowai.workflow.state import AgentState
+
+__all__ = [
+    "AgentState",
+    "BaseCheckpointer",
+    "InMemoryCheckpointer",
+    "FileCheckpointer",
+    "Workflow",
+    "START",
+    "END",
+]

flowai/workflow/checkpoint.py

@@ -0,0 +1,73 @@
+"""State checkpointing and resumable execution persistence."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from flowai.workflow.state import AgentState
+
+
+class BaseCheckpointer(ABC):
+    """Abstract interface for storing state checkpoints."""
+
+    @abstractmethod
+    async def save(self, state: AgentState) -> str:
+        """Persist state and return checkpoint ID."""
+        ...
+
+    @abstractmethod
+    async def load(self, checkpoint_id: str) -> AgentState | None:
+        """Retrieve state from checkpoint."""
+        ...
+
+    @abstractmethod
+    async def list_checkpoints(self, session_id: str) -> list[str]:
+        """List checkpoint IDs for a given session."""
+        ...
+
+
+class InMemoryCheckpointer(BaseCheckpointer):
+    """Ephemeral in-memory checkpoint store."""
+
+    def __init__(self):
+        self._checkpoints: dict[str, dict[str, Any]] = {}
+        self._session_index: dict[str, list[str]] = {}
+
+    async def save(self, state: AgentState) -> str:
+        checkpoint_id = f"{state.session_id}_step_{state.step}"
+        self._checkpoints[checkpoint_id] = state.model_dump()
+        self._session_index.setdefault(state.session_id, []).append(checkpoint_id)
+        return checkpoint_id
+
+    async def load(self, checkpoint_id: str) -> AgentState | None:
+        data = self._checkpoints.get(checkpoint_id)
+        return AgentState(**data) if data else None
+
+    async def list_checkpoints(self, session_id: str) -> list[str]:
+        return self._session_index.get(session_id, [])
+
+
+class FileCheckpointer(BaseCheckpointer):
+    """Filesystem JSON checkpointer for local resumable workflows."""
+
+    def __init__(self, directory: str = ".flowai/checkpoints"):
+        self.directory = Path(directory)
+        self.directory.mkdir(parents=True, exist_ok=True)
+
+    async def save(self, state: AgentState) -> str:
+        checkpoint_id = f"{state.session_id}_step_{state.step}"
+        path = self.directory / f"{checkpoint_id}.json"
+        path.write_text(state.model_dump_json(indent=2), encoding="utf-8")
+        return checkpoint_id
+
+    async def load(self, checkpoint_id: str) -> AgentState | None:
+        path = self.directory / f"{checkpoint_id}.json"
+        if not path.exists():
+            return None
+        return AgentState.model_validate_json(path.read_text(encoding="utf-8"))
+
+    async def list_checkpoints(self, session_id: str) -> list[str]:
+        files = self.directory.glob(f"{session_id}_step_*.json")
+        return sorted([f.stem for f in files])

flowai/workflow/engine.py

@@ -0,0 +1,144 @@
+"""Async Workflow Engine with DAG waves, branching, loops, and parallel execution."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from flowai.agents.base import BaseAgent
+from flowai.observability.events import EventBus
+from flowai.workflow.checkpoint import BaseCheckpointer
+from flowai.workflow.state import AgentState
+
+NodeFn = Callable[[AgentState], AgentState | Coroutine[Any, Any, AgentState]]
+RouterFn = Callable[[AgentState], str | Coroutine[Any, Any, str]]
+
+START = "START"
+END = "END"
+
+
+class Workflow:
+    """Async Graph Workflow Engine supporting branching, loops, and parallel nodes."""
+
+    def __init__(
+        self,
+        name: str = "Workflow",
+        checkpointer: BaseCheckpointer | None = None,
+        event_bus: EventBus | None = None,
+        max_steps: int = 50,
+    ):
+        self.name = name
+        self.nodes: dict[str, NodeFn] = {}
+        self.edges: dict[str, list[str]] = {}
+        self.routers: dict[str, RouterFn] = {}
+        self.checkpointer = checkpointer
+        self.event_bus = event_bus or EventBus()
+        self.max_steps = max_steps
+
+    def add_node(self, name: str, fn_or_agent: NodeFn | BaseAgent) -> Workflow:
+        """Register a node function or agent."""
+        if isinstance(fn_or_agent, BaseAgent):
+            agent = fn_or_agent
+
+            async def agent_node(state: AgentState) -> AgentState:
+                prompt = state.get("task", "") or (state.messages[-1].content if state.messages else "")
+                reply = await agent.run(prompt)
+                return state.set(f"{name}_output", reply).append_message({"role": "assistant", "content": reply})
+
+            self.nodes[name] = agent_node
+        else:
+            self.nodes[name] = fn_or_agent
+        self.edges.setdefault(name, [])
+        return self
+
+    def add_agent(self, agent: BaseAgent, name: str | None = None) -> Workflow:
+        """Convenience method to register an agent as a workflow node."""
+        node_name = name or agent.name
+        return self.add_node(node_name, agent)
+
+    def add_edge(self, from_node: str, to_node: str) -> Workflow:
+        """Add a directed edge from one node to another."""
+        self.edges.setdefault(from_node, []).append(to_node)
+        return self
+
+    def add_conditional_edge(self, from_node: str, router: RouterFn) -> Workflow:
+        """Add a dynamic routing function to branch or loop based on state."""
+        self.routers[from_node] = router
+        return self
+
+    async def execute_parallel(self, node_names: list[str], state: AgentState) -> AgentState:
+        """Run multiple ready nodes in parallel and merge disjoint state updates."""
+        tasks = []
+        for name in node_names:
+            fn = self.nodes[name]
+            if asyncio.iscoroutinefunction(fn):
+                tasks.append(fn(state))
+            else:
+                tasks.append(asyncio.to_thread(fn, state))
+
+        results: list[AgentState] = await asyncio.gather(*tasks)
+        merged = state
+        for res in results:
+            merged = merged.update_values(res.values)
+            for m in res.messages[len(state.messages):]:
+                merged = merged.append_message(m)
+        return merged
+
+    async def run(self, initial_input: str | dict[str, Any] | AgentState, entry_point: str = "START") -> AgentState:
+        """Execute the workflow starting from entry_point until END or max_steps."""
+        if isinstance(initial_input, AgentState):
+            state = initial_input
+        elif isinstance(initial_input, str):
+            state = AgentState(values={"task": initial_input}).append_message({"role": "user", "content": initial_input})
+        else:
+            state = AgentState(values=initial_input)
+
+        current_node = entry_point
+        # If START is not an explicit node, jump to first edge from START or first registered node
+        if current_node == START and START not in self.nodes:
+            if START in self.edges and self.edges[START]:
+                current_node = self.edges[START][0]
+            elif self.nodes:
+                current_node = list(self.nodes.keys())[0]
+            else:
+                return state
+
+        step_count = 0
+        while current_node != END and step_count < self.max_steps:
+            step_count += 1
+            await self.event_bus.publish("node_start", {"node": current_node, "step": step_count})
+
+            if self.checkpointer:
+                await self.checkpointer.save(state)
+
+            fn = self.nodes.get(current_node)
+            if fn:
+                if asyncio.iscoroutinefunction(fn):
+                    state = await fn(state)
+                else:
+                    state = await asyncio.to_thread(fn, state)
+
+            await self.event_bus.publish("node_end", {"node": current_node, "step": step_count})
+
+            # Check dynamic router
+            if current_node in self.routers:
+                router = self.routers[current_node]
+                next_node = await router(state) if asyncio.iscoroutinefunction(router) else router(state)
+                current_node = next_node
+            # Check static edges
+            elif self.edges.get(current_node):
+                targets = self.edges[current_node]
+                if len(targets) > 1:
+                    # Parallel branch execution
+                    state = await self.execute_parallel(targets, state)
+                    current_node = END
+                else:
+                    current_node = targets[0]
+            else:
+                current_node = END
+
+        if self.checkpointer:
+            await self.checkpointer.save(state)
+
+        return state

flowai/workflow/state.py

@@ -0,0 +1,43 @@
+"""State Management - Pydantic-based State containers and history."""
+
+from __future__ import annotations
+
+import copy
+import uuid
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from flowai.providers.base import Message
+
+
+class AgentState(BaseModel):
+    """Immutable state container for LangGraph-style workflows."""
+    session_id: str = Field(default_factory=lambda: f"ses_{uuid.uuid4().hex[:8]}")
+    step: int = 0
+    messages: list[Message] = Field(default_factory=list)
+    values: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.values.get(key, default)
+
+    def set(self, key: str, value: Any) -> AgentState:
+        """Return a new copy of state with updated key-value."""
+        new_values = copy.deepcopy(self.values)
+        new_values[key] = value
+        return self.model_copy(update={"values": new_values, "step": self.step + 1})
+
+    def update_values(self, updates: dict[str, Any]) -> AgentState:
+        """Merge a dictionary into state values."""
+        new_values = copy.deepcopy(self.values)
+        new_values.update(updates)
+        return self.model_copy(update={"values": new_values, "step": self.step + 1})
+
+    def append_message(self, message: Message | dict[str, Any]) -> AgentState:
+        new_msgs = list(self.messages)
+        if isinstance(message, dict):
+            new_msgs.append(Message(**message))
+        else:
+            new_msgs.append(message)
+        return self.model_copy(update={"messages": new_msgs})

flowai_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: flowai-cli
+Version: 0.2.0
+Summary: FlowAI: an open-source, extensible Python agent harness with a terminal-first CLI.
+Project-URL: Homepage, https://github.com/Ajayramaswamy2005/FlowAI
+Project-URL: Source, https://github.com/Ajayramaswamy2005/FlowAI
+Project-URL: Issues, https://github.com/Ajayramaswamy2005/FlowAI/issues
+Author: Ajay Rama Swamy Katragaada
+License: MIT
+License-File: LICENSE
+Keywords: agent,cli,fastapi,llm,mcp,nvidia,ollama,pydantic,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: all
+Requires-Dist: chromadb>=0.5.0; extra == 'all'
+Requires-Dist: fastapi>=0.111.0; extra == 'all'
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.25.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'all'
+Requires-Dist: qdrant-client>=1.9.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'all'
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.5.0; extra == 'chroma'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.111.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.25.0; extra == 'observability'
+Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'observability'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.9.0; extra == 'qdrant'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# FlowAI
+
+FlowAI is an AI agent you run in your terminal, in the same spirit as Claude
+Code or OpenCode. Bring your own key from Anthropic, OpenAI, NVIDIA, Google
+Gemini or OpenRouter, or run fully local with Ollama. The agent can read, search
+and edit the files in your project, run shell commands (after asking you), and
+search the web.
+
+It is also a Python library: the same agents, tools, workflows and memory the
+CLI uses are yours to build on.
+
+## Install
+
+```bash
+pip install flowai-cli        # once it is published to PyPI
+pipx install flowai-cli       # same, in its own isolated environment
+
+# from a checkout of this repository:
+pip install .
+```
+
+Python 3.10 or newer. The package is `flowai-cli` (the name `flowai` is taken on PyPI);
+the command it installs is `flowai`, and the import is `import flowai`.
+
+## First run
+
+```bash
+flowai
+```
+
+The first time, FlowAI asks for a provider and an API key and saves them to
+`~/.flowai/config.json`. After that, `flowai` opens a session in the current
+directory:
+
+```
+------------------------------------------------------------
+  FlowAI 0.2.0   anthropic / claude-sonnet-5-5
+  workspace: /home/you/my-project
+  session:   ses_3f9a1c2e
+  /help for commands, /exit to quit
+------------------------------------------------------------
+
+> why does the test in tests/test_api.py fail?
+
+  [tool] grep_files(pattern=def test_, path=tests)
+  [done] tests/test_api.py:12: def test_create_user(): (+4 more lines)
+  [tool] read_file(path=tests/test_api.py)
+  ...
+```
+
+Set up non-interactively instead (for scripts or CI):
+
+```bash
+flowai configure --provider anthropic --key "$ANTHROPIC_API_KEY"
+```
+
+Or skip configuration entirely: if `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+`NVIDIA_API_KEY`, `GEMINI_API_KEY` or `OPENROUTER_API_KEY` is set, FlowAI uses
+it.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `flowai` | Interactive session in the current directory |
+| `flowai "add type hints to utils.py"` | Run one task and exit |
+| `flowai chat --resume` (or `-c`) | Continue the most recent session |
+| `flowai run -q "..."` | One task, print only the final answer (good for scripts) |
+| `echo "..." \| flowai run` | Read the prompt from stdin |
+| `flowai configure` | Choose provider, model and API key |
+| `flowai init [dir]` | Create a `flowai.yaml` and a starter `main.py` |
+| `flowai inspect` | Show config status, saved sessions, checkpoints |
+| `flowai tools` | List the built-in tools |
+| `flowai serve` | HTTP API with streaming (`pip install 'flowai-cli[server]'`) |
+
+Options for `chat` and `run`: `--provider`, `--model`, `-w/--workspace DIR`,
+`--yolo` (do not ask before shell/python tools run), `--no-tools`,
+`--max-iterations N`.
+
+Inside a session: `/help`, `/model <name>`, `/provider <name> [model]`,
+`/tools`, `/cost`, `/new`, `/reset`, `/yolo`, `/exit`.
+
+## What the agent can do
+
+| Tool | Notes |
+|---|---|
+| `read_file`, `list_dir`, `glob_files`, `grep_files` | Read-only; never asks |
+| `write_file`, `edit_file` | Changes files inside the workspace only |
+| `bash` | Asks first. Runs in the workspace, 120 s timeout |
+| `python_repl` | Asks first. Runs code in a fresh namespace |
+| `search_web`, `fetch_url` | DuckDuckGo search and page fetch |
+
+**Safety.** Every file path is resolved against the workspace (the directory
+you started in, or `-w`) and refused if it points outside. Shell, Python and
+MCP tools show you exactly what they will run and wait for `y`, `n` or `a`
+(always, for that tool, this session). With no terminal attached, those tools
+are refused rather than run. `--yolo` or `approval: "auto"` in `flowai.yaml`
+turns the prompt off; use it only in a sandbox.
+
+## Configuration
+
+Settings are layered, later wins:
+
+1. `~/.flowai/config.json`, written by `flowai configure`
+2. `flowai.yaml` (or `.yml`, `.toml`, `.json`) in the current directory or any
+   parent, so it works from a subdirectory of your project
+3. Environment: `FLOWAI_PROVIDER`, `FLOWAI_MODEL`, and the provider key variables
+
+See [flowai.yaml](flowai.yaml) for every option, including `mcp_servers` for
+borrowing tools from Model Context Protocol servers (`pip install 'flowai-cli[mcp]'`).
+
+## Using it as a library
+
+```python
+import asyncio
+from flowai import Agent, tool
+
+@tool
+def compound_interest(principal: float, rate: float, years: int) -> float:
+    """Balance after compounding yearly."""
+    return round(principal * (1 + rate) ** years, 2)
+
+agent = Agent(
+    name="Advisor",
+    provider="anthropic",          # nvidia, ollama, openai, gemini, openrouter
+    model="claude-sonnet-5-5",
+    tools=[compound_interest],
+)
+
+print(asyncio.run(agent.run("What will $5,000 be after 10 years at 8%?")))
+```
+
+`agent.stream(prompt)` yields tokens as they arrive and runs tool calls along
+the way. Tools you register in your own code run without an approval prompt
+(you wrote them); give a `ToolRegistry` an `approver` callback to change that.
+
+Beyond a single agent the library has:
+
+- **Specialised agents**: `PlannerAgent`, `CriticAgent`, `ToolAgent`, `SupervisorAgent`
+- **Patterns**: `ReflectionPattern`, `PlanAndExecutePattern`, `DebatePattern`, `Swarm`
+- **Workflows**: a graph engine with conditional edges, loops, parallel
+  branches and checkpointing (`Workflow`, `FileCheckpointer`)
+- **Memory**: `InMemory`, `QdrantMemory` (`flowai-cli[qdrant]`), `ChromaMemory` (`flowai-cli[chroma]`)
+- **Observability**: per-span token counts and estimated cost (`agent.tracer`),
+  an event bus, and an OpenTelemetry exporter (`flowai-cli[observability]`)
+- **Plugins**: third-party providers via the `flowai.plugins` entry point
+
+Runnable examples are in [examples/](examples/).
+
+## Developing FlowAI
+
+```bash
+pip install -e '.[dev]'
+pytest
+ruff check flowai tests
+```
+
+The tests are offline: providers are faked at the HTTP layer, so no key is needed.
+
+## Releasing to PyPI
+
+1. Bump `version` in `pyproject.toml` and `__version__` in `flowai/__init__.py`.
+2. Push a tag `flowai-vX.Y.Z`. The `flowai-release` workflow builds this
+   directory and publishes it with PyPI Trusted Publishing; configure the
+   `flowai-cli` project on PyPI to trust this repository and workflow first.
+
+
+
+## License
+
+MIT