flowai-cli 0.2.0__tar.gz

flowai_cli-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.flowai/
+.env

flowai_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajay Rama Swamy Katragaada
+
+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.

flowai_cli-0.2.0/PKG-INFO

@@ -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

flowai_cli-0.2.0/README.md

@@ -0,0 +1,171 @@
+# 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

flowai_cli-0.2.0/examples/01_quickstart.py

@@ -0,0 +1,36 @@
+"""Example 01: Quickstart with FlowAI."""
+
+import asyncio
+
+from flowai import Agent, tool
+from flowai.memory import ConversationMemory
+
+
+@tool
+def calculate_growth(initial: float, rate: float, periods: int) -> float:
+    """Calculate compound interest growth."""
+    return round(initial * ((1 + rate) ** periods), 2)
+
+
+async def main():
+    # Initialize an agent with in-memory conversation memory
+    memory = ConversationMemory()
+    agent = Agent(
+        name="FinanceAgent",
+        provider="openai",  # or "nvidia", "ollama", "anthropic", "gemini"
+        model="gpt-4o-mini",
+        tools=[calculate_growth],
+        memory=memory,
+    )
+
+    print("=== FlowAI Quickstart Agent ===")
+    response = await agent.run("If I invest $10,000 at 7% for 5 years, what will it be worth?")
+    print(f"Agent Reply:\n{response}\n")
+
+    # Conversation history is preserved
+    print("=== Preserved Conversation History ===")
+    print(memory.format_history())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

flowai_cli-0.2.0/examples/02_nvidia_deepseek.py

@@ -0,0 +1,40 @@
+"""Example 02: NVIDIA API Catalog with DeepSeek-R1 / DeepSeek-V4."""
+
+import asyncio
+
+from flowai import Agent, tool
+
+
+@tool
+def check_server_health(host: str) -> dict:
+    """Check system resource status and latency."""
+    return {"host": host, "status": "healthy", "cpu_percent": 24.5, "latency_ms": 12.4}
+
+
+async def main():
+    # Make sure NVIDIA_API_KEY is set in your environment
+    agent = Agent(
+        name="NvidiaDeepSeekAgent",
+        provider="nvidia",
+        model="deepseek-ai/deepseek-r1",
+        system_prompt="You are a DevOps autonomous triage engineer.",
+        tools=[check_server_health],
+    )
+
+    print("=== Invoking DeepSeek on NVIDIA API Catalog ===")
+    prompt = "Check the health of 'prod-cluster-us-east-1' and summarize your findings."
+
+    # Non-streaming invocation
+    result = await agent.run(prompt)
+    print("\n--- Agent Conclusion ---")
+    print(result)
+
+    # Token streaming invocation
+    print("\n--- Streaming Response ---")
+    async for chunk in agent.stream("Recommend 2 optimization actions."):
+        print(chunk.text_delta, end="", flush=True)
+    print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

flowai_cli-0.2.0/examples/03_workflow_graph.py

@@ -0,0 +1,56 @@
+"""Example 03: Multi-agent Workflow DAG with State Passing and Checkpoints."""
+
+import asyncio
+
+from flowai import Agent, Workflow
+from flowai.workflow.checkpoint import InMemoryCheckpointer
+
+
+async def main():
+    # 1. Instantiate specialized agents
+    researcher = Agent(
+        name="Researcher",
+        model="gpt-4o-mini",
+        system_prompt="You are a Technical Researcher. Provide facts, architecture patterns, and benchmarks.",
+    )
+    coder = Agent(
+        name="Coder",
+        model="gpt-4o-mini",
+        system_prompt="You are a Principal Software Engineer. Write clean, idiomatic Python code based on research.",
+    )
+    reviewer = Agent(
+        name="Reviewer",
+        model="gpt-4o-mini",
+        system_prompt="You are a Code Reviewer. Inspect code for bugs, edge cases, and performance bottlenecks.",
+    )
+
+    # 2. Construct DAG Workflow with Checkpointing
+    checkpointer = InMemoryCheckpointer()
+    wf = Workflow(name="CodeGenerationPipeline", checkpointer=checkpointer)
+
+    wf.add_agent(researcher, name="research_node")
+    wf.add_agent(coder, name="coding_node")
+    wf.add_agent(reviewer, name="review_node")
+
+    # Connect nodes in a linear sequential pipeline
+    wf.add_edge("research_node", "coding_node")
+    wf.add_edge("coding_node", "review_node")
+
+    # 3. Execute workflow
+    task = "Design and implement a thread-safe token bucket rate limiter in Python."
+    print(f"Starting Workflow for task: '{task}' ...\n")
+    final_state = await wf.run(task, entry_point="research_node")
+
+    print("=== Final Pipeline State Output ===")
+    print(f"Total Steps Executed: {final_state.step}")
+    print(f"Researcher Output:\n{final_state.get('research_node_output')[:300]}...\n")
+    print(f"Coder Output:\n{final_state.get('coding_node_output')[:300]}...\n")
+    print(f"Reviewer Output:\n{final_state.get('review_node_output')}\n")
+
+    # Verify checkpoints
+    checkpoints = await checkpointer.list_checkpoints(final_state.session_id)
+    print(f"Checkpoints persisted: {checkpoints}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

flowai_cli-0.2.0/examples/04_fastmcp_agent.py

@@ -0,0 +1,37 @@
+"""Example 04: FastMCP / Model Context Protocol Integration."""
+
+import asyncio
+
+from flowai import Agent
+from flowai.mcp import MCPClient
+
+
+async def main():
+    print("=== FlowAI MCP Integration Example ===")
+
+    # Initialize client to an MCP server (e.g. SQLite, GitHub, or custom FastMCP server)
+    mcp_client = MCPClient(
+        command="npx",
+        args=["-y", "@modelcontextprotocol/server-everything"],
+    )
+
+    print("Connecting to MCP server and discovering exposed tools...")
+    tools = await mcp_client.connect_and_discover_tools()
+    print(f"Discovered {len(tools)} MCP tools:")
+    for t in tools:
+        print(f" - {t.name}: {t.description}")
+
+    # Plug discovered MCP tools directly into a FlowAI agent
+    agent = Agent(
+        name="MCPWorker",
+        provider="nvidia",
+        model="deepseek-ai/deepseek-r1",
+        tools=tools,
+    )
+
+    reply = await agent.run("List the tools you have and pick one to demonstrate.")
+    print(f"\n{agent.name}: {reply}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

flowai_cli-0.2.0/examples/05_debate_and_swarm.py

@@ -0,0 +1,68 @@
+"""Example 05: Multi-agent Debate and Swarm Patterns."""
+
+import asyncio
+
+from flowai import Agent, DebatePattern, Swarm
+from flowai.providers.base import BaseProvider, ProviderResponse
+
+
+class ScriptedProvider(BaseProvider):
+    """Deterministic provider for simulation."""
+
+    def __init__(self, script: dict[str, str]):
+        super().__init__(model="scripted")
+        self.script = script
+
+    async def generate(self, messages, tools=None, **kwargs):
+        last_msg = messages[-1].content
+        for k, reply in self.script.items():
+            if k in last_msg:
+                return ProviderResponse(content=reply)
+        return ProviderResponse(content="Default response.")
+
+    async def stream(self, messages, tools=None, **kwargs):
+        yield
+
+    async def embeddings(self, texts, model=None, **kwargs):
+        return []
+
+
+async def test_debate():
+    print("=== Multi-Agent Debate Pattern ===")
+    provider_pro = ScriptedProvider({"IN FAVOR": "Remote work increases productivity and mental wellbeing."})
+    provider_con = ScriptedProvider({"AGAINST": "In-office work fosters spontaneous collaboration and mentorship."})
+    provider_judge = ScriptedProvider({"impartial judge": "Both presented strong points; hybrid mode is optimal."})
+
+    debater_a = Agent("ProRemote", provider=provider_pro)
+    debater_b = Agent("ProOffice", provider=provider_con)
+    judge = Agent("Judge", provider=provider_judge)
+
+    debate = DebatePattern(debater_a, debater_b, judge, rounds=1)
+    result = await debate.execute("Should companies mandate 5 days in-office?")
+    print("Debate Transcript:")
+    for entry in result["transcript"]:
+        print(f" - {entry}")
+    print(f"\nVerdict:\n{result['verdict']}\n")
+
+
+async def test_swarm():
+    print("=== Multi-Agent Swarm Dynamic Handoff ===")
+    triage_script = {
+        "Python": "HANDOFF_TO: PythonExpert Please write the Python implementation.",
+        "SQL": "HANDOFF_TO: SQLExpert Please optimize the SQL query.",
+    }
+    triage = Agent("TriageAgent", provider=ScriptedProvider(triage_script))
+    py_agent = Agent("PythonExpert", provider=ScriptedProvider({"write": "def solve(): return 42"}))
+
+    swarm = Swarm(agents=[triage, py_agent], initial_agent=triage)
+    result = await swarm.execute("I need a Python function to compute answer to life.")
+    print(f"Swarm Result:\n{result}")
+
+
+async def main():
+    await test_debate()
+    await test_swarm()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())