flowagent-framework 0.1.0

███████╗██╗      ██████╗ ██╗    ██╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗
██╔════╝██║     ██╔═══██╗██║    ██║██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
█████╗  ██║     ██║   ██║██║ █╗ ██║███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║
██╔══╝  ██║     ██║   ██║██║███╗██║██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║
██║     ███████╗╚██████╔╝╚███╔███╔╝██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║
╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝

🔥 Why FlowAgent?

• Production-Ready — Async-first design, graceful error handling, cost tracking, and health checks baked in from day one
• Multi-Agent Orchestration — Define pipelines declaratively; the Orchestrator automatically parallelises independent steps using Kahn's topological sort
• Built-in RAG — A fully-featured Retrieval-Augmented Generation engine with semantic chunking, overlap control, and ChromaDB storage — no boilerplate
• Plugin System — Drop a plugin.yaml + Python module into any directory and it's live; zero-config dynamic tool loading at runtime

⚡ Quick Start

pip install flowagent-framework

flowagent init my-project
cd my-project

# Create your first agent
flowagent agents create researcher --model gpt-4o

# Run it
flowagent run researcher --prompt "Research AI trends 2025"

Installed as flowagent-framework, imported and run as flowagent. The shorter name on PyPI belongs to an unrelated project, and PyPI blocks names that differ from an existing one only by a separator.

Set your API key before running:

$env:OPENAI_API_KEY = "sk-..."   # PowerShell
# or
export OPENAI_API_KEY="sk-..."   # bash/zsh

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        FlowAgent                            │
│                                                             │
│  ┌──────────┐    ┌──────────────┐    ┌───────────────────┐  │
│  │   CLI    │    │  REST API    │    │    Dashboard      │  │
│  │ (Click)  │    │  (FastAPI)   │    │  (React + Vite)   │  │
│  └────┬─────┘    └──────┬───────┘    └─────────┬─────────┘  │
│       │                 │                      │            │
│  ─────┴─────────────────┴──────────────────────┴─────────   │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                   Core Engine                        │   │
│  │                                                      │   │
│  │  ┌─────────────┐       ┌──────────────────────────┐  │   │
│  │  │ Orchestrator│──────▶│  Pipeline / Workflow     │  │   │
│  │  └──────┬──────┘       └──────────────────────────┘  │   │
│  │         │                                            │   │
│  │  ┌──────▼──────┐  ┌───────────┐  ┌───────────────┐  │   │
│  │  │   Agent     │  │ RAGEngine │  │    Memory     │  │   │
│  │  │  (run loop) │  │ (ChromaDB)│  │ (Conversation)│  │   │
│  │  └──────┬──────┘  └───────────┘  └───────────────┘  │   │
│  │         │                                            │   │
│  │  ┌──────▼──────────────────────────────────────┐    │   │
│  │  │           Tool Registry                     │    │   │
│  │  │  web_search │ file_ops │ api_caller │ code   │    │   │
│  │  │             + Plugin System (dynamic)       │    │   │
│  │  └─────────────────────────────────────────────┘    │   │
│  │                         │                           │   │
│  │  ┌──────────────────────▼──────────────────────┐    │   │
│  │  │              LLM Adapters                   │    │   │
│  │  │        OpenAI (gpt-4o)  │  Anthropic        │    │   │
│  │  └─────────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         Go Worker  (port 8080)                      │   │
│  │  TaskQueue → WorkerPool → Executor → Metrics        │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

🤖 Core Concepts

📦 Built-in Tools

🔄 Multi-Agent Workflows

Python API

import asyncio
from flowagent.core.agent import Agent, AgentConfig
from flowagent.core.orchestrator import Orchestrator
from flowagent.core.pipeline import Pipeline
from flowagent.llm.openai import OpenAILLM

# Build agents
researcher = Agent(
    config=AgentConfig(name="researcher", model="gpt-4o", tools=["web_search"]),
    llm=OpenAILLM(model="gpt-4o"),
)
writer = Agent(
    config=AgentConfig(name="writer", model="gpt-4o"),
    llm=OpenAILLM(model="gpt-4o"),
)

# Declare the pipeline
workflow = (
    Pipeline("research-and-write")
    .add_step("researcher", "Research: {topic}")
    .add_step("writer", "Write a detailed article about: {researcher}")
    .build()
)

# Run
orchestrator = Orchestrator({"researcher": researcher, "writer": writer})
result = asyncio.run(
    orchestrator.run_workflow(workflow, {"topic": "AI in 2025"})
)

print(result.outputs["writer"].output)
print(f"Total tokens: {result.total_tokens} | Cost: ${result.total_cost:.4f}")

Parallel Steps

workflow = (
    Pipeline("multi-research")
    .add_step("planner", "Create a research outline for: {topic}", depends_on=[])
    .parallel(
        ("researcher_a", "Research technical aspects: {planner}"),
        ("researcher_b", "Research business aspects: {planner}"),
    )
    .add_step("synthesizer", "Synthesize these reports:\nA: {researcher_a}\nB: {researcher_b}")
    .build()
)

YAML Workflow

# workflows/research.yaml
name: research-pipeline
description: Research and summarize a topic

initial_context:
  topic: "Large Language Models"

steps:
  - agent_name: researcher
    prompt_template: "Research the topic: {topic}"
    output_key: research_output

  - agent_name: writer
    prompt_template: "Write an article based on: {research_output}"
    depends_on: [research_output]
    output_key: final_article

flowagent workflow run workflows/research.yaml

🧠 RAG System

import asyncio
from flowagent.core.rag import RAGEngine, Document
from flowagent.core.memory import ChromaMemory  # SemanticMemory implementation

async def main():
    memory = ChromaMemory(collection_name="my-docs")
    rag = RAGEngine(memory=memory, chunk_size=500, overlap=50)

    # Ingest documents
    await rag.ingest([
        Document(content="FlowAgent supports multi-agent orchestration...", metadata={"source": "docs"}),
    ])
    await rag.ingest_file("knowledge_base.md")   # .txt, .md, .json, .csv supported
    await rag.ingest_text("Additional context text here.")

    # Query
    result = await rag.query("What does FlowAgent support?", n_results=5)
    print(result.context)

    # Get a fully-formatted LLM prompt
    prompt = await rag.query_with_prompt("Explain the orchestration model.")
    print(prompt)

asyncio.run(main())

🖥️ CLI Reference

flowagent [OPTIONS] COMMAND [ARGS]...

📊 Dashboard

A React + TypeScript monitoring dashboard (built with Vite) provides real-time visibility into:

• Active agent runs and their status
• Token usage and cost per run
• Worker pool metrics (queue depth, throughput)
• Agent registry management

Screenshot coming soon — run docker compose up and open http://localhost:3000

🐳 Docker

# Start all services: API, Go Worker, Dashboard, Redis
docker compose up

# Individual services
docker compose up api          # FastAPI on :8000
docker compose up worker       # Go worker on :8080
docker compose up dashboard    # React UI on :3000

Services:

Health checks are built-in; the worker and dashboard wait for the API to become healthy before starting.

🏭 Go Worker

The Go worker handles high-concurrency async task execution outside the Python GIL:

• TaskQueue — buffered channel queue (default capacity: 1000)
• WorkerPool — configurable goroutine pool (default: 4 workers)
• Executor Registry — extendable task type handlers
• Metrics — Prometheus-compatible counters (tasks enqueued, processed, failed, latency)
• Graceful Shutdown — drains in-flight tasks on SIGINT/SIGTERM

# Standalone (outside Docker)
cd worker
go build -o flowagent-worker .
./flowagent-worker --port 8080 --workers 8 --api-url http://localhost:8000

🔌 Plugin System

Drop a plugin directory anywhere and load it at runtime — no code changes required.

Plugin Structure

plugins/
└── my_tool/
    ├── plugin.yaml      # metadata
    └── tool.py          # implementation

plugin.yaml

name: my_tool
version: "1.0.0"
description: "My custom tool that does something useful"
entry_point: tool.py

tool.py

from flowagent.tools.base import BaseTool, ToolResult

class MyTool(BaseTool):
    @property
    def name(self) -> str:
        return "my_tool"

    @property
    def description(self) -> str:
        return "My custom tool description"

    @property
    def parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "input": {"type": "string", "description": "Tool input"}
            },
            "required": ["input"],
        }

    async def execute(self, **kwargs) -> ToolResult:
        result = f"Processed: {kwargs['input']}"
        return ToolResult(success=True, output=result)

def create_tool() -> BaseTool:
    return MyTool()

Loading Plugins

from flowagent.plugins.loader import PluginLoader
from flowagent.tools.registry import ToolRegistry

registry = ToolRegistry()
loader = PluginLoader()

tools = loader.load_all("./plugins")
for tool in tools:
    registry.register(tool)

🧪 Testing

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ -v --cov=flowagent --cov-report=term-missing

# Lint
ruff check flowagent/

The test suite uses pytest-asyncio for async tests and pytest-mock for LLM mocking.

📁 Project Structure

FlowAgent/
├── flowagent/                  # Main Python package
│   ├── api/                    # FastAPI REST API
│   │   └── routes/             # agents.py, runs.py
│   ├── cli/                    # Click CLI + Rich display
│   ├── core/                   # Agent, Orchestrator, Pipeline, RAGEngine, Memory
│   ├── llm/                    # OpenAI & Anthropic adapters
│   ├── plugins/                # PluginLoader — dynamic tool discovery
│   ├── tools/                  # BaseTool + 4 built-in tools + registry
│   └── utils/                  # Logger, config helpers
├── worker/                     # High-performance Go async worker
│   └── internal/               # task, worker pool, executor, metrics, server
├── dashboard/                  # React + TypeScript + Vite monitoring UI
├── tests/                      # Pytest test suite
├── docs/                       # Architecture, API reference, guides
├── Dockerfile                  # Multi-stage Python image
├── docker-compose.yml          # All services: api, worker, dashboard, redis
└── pyproject.toml              # Build metadata & dependencies

🗺️ Roadmap

• Streaming UI in Dashboard — live token streaming from agent runs
• Additional LLM providers — Gemini, Mistral, local Ollama support
• Kubernetes deployment — Helm chart + horizontal pod autoscaling
• Plugin Marketplace — discover and install community plugins with flowagent plugin install
• Visual Workflow Builder — drag-and-drop pipeline editor in the web UI

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on opening issues, submitting pull requests, and the development workflow.

git clone https://github.com/flowagent/flowagent
cd flowagent
pip install -e ".[dev]"
pytest tests/ -v

📄 License

MIT — see LICENSE.