Metadata-Version: 2.4
Name: flowagent-framework
Version: 0.1.0
Summary: AI Agent Orchestration Framework
Project-URL: Homepage, https://github.com/kahlelhawary-art/FlowAgent
Project-URL: Repository, https://github.com/kahlelhawary-art/FlowAgent
Project-URL: Issues, https://github.com/kahlelhawary-art/FlowAgent/issues
Author: FlowAgent Contributors
License: MIT
License-File: LICENSE
Keywords: agents,ai,automation,llm,orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.28.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.30.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: uvicorn[standard]>=0.29.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff~=0.15.0; extra == 'dev'
Description-Content-Type: text/markdown

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

<div align="center">

**Production-ready AI Agent Orchestration Framework**

[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
[![CI](https://github.com/kahlelhawary-art/FlowAgent/actions/workflows/ci.yml/badge.svg)](https://github.com/kahlelhawary-art/FlowAgent/actions/workflows/ci.yml)
[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](docker-compose.yml)
[![Go Worker](https://img.shields.io/badge/Go%20Worker-1.22-00ADD8?style=flat-square&logo=go&logoColor=white)](worker/)

[Quick Start](#-quick-start) • [Architecture](#️-architecture) • [Docs](docs/) • [Contributing](#-contributing)

</div>

---

## 🔥 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

```bash
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:

```bash
$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

| Concept | Description |
|---------|-------------|
| **Agent** | An autonomous reasoning unit. Sends prompts to an LLM, handles tool calls in a loop, and returns a structured `AgentResult`. |
| **Workflow** | A named, ordered collection of `WorkflowStep` objects that form a DAG of agent tasks. |
| **Pipeline** | A fluent builder (`Pipeline("name").add_step(...).parallel(...).build()`) for constructing `Workflow` objects without touching YAML. |
| **Tool** | Any class inheriting `BaseTool`. Implements `name`, `description`, `parameters` (JSON Schema), and `async execute(**kwargs)`. |
| **Memory** | `ConversationMemory` stores the chat history; `SemanticMemory` (ChromaDB) powers RAG retrieval. |
| **RAG** | `RAGEngine` ingests documents (text, file, or raw string), chunks them, and retrieves relevant context for a query. |

---

## 📦 Built-in Tools

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `web_search` | DuckDuckGo search — no API key required | `query: str`, `max_results: int` |
| `file_ops` | Sandboxed file read / write / list with path-traversal guards | `operation: str`, `path: str`, `content?: str` |
| `api_caller` | Generic async HTTP client (GET, POST, PUT, DELETE) via `httpx` | `url: str`, `method: str`, `headers?: dict`, `body?: dict` |
| `code_executor` | Runs Python snippets in isolated subprocesses with timeout | `code: str`, `timeout?: int` |

---

## 🔄 Multi-Agent Workflows

### Python API

```python
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

```python
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

```yaml
# 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
```

```bash
flowagent workflow run workflows/research.yaml
```

---

## 🧠 RAG System

```python
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

```bash
flowagent [OPTIONS] COMMAND [ARGS]...
```

| Command | Description |
|---------|-------------|
| `flowagent init [PATH]` | Scaffold a new project with `config.yaml` and `agents/` directory |
| `flowagent run AGENT_NAME -p PROMPT` | Run a named agent with a prompt |
| `flowagent run AGENT_NAME -p PROMPT --model anthropic` | Run with Anthropic Claude |
| `flowagent run AGENT_NAME -p PROMPT --stream` | Stream output token-by-token |
| `flowagent agents list` | List all agents in the project |
| `flowagent agents create NAME --model gpt-4o` | Create a new agent YAML |
| `flowagent workflow run WORKFLOW_FILE` | Execute a YAML workflow |
| `flowagent serve [--port 8000] [--reload]` | Start the FastAPI REST server |
| `flowagent status` | Show project health and agent counts |
| `flowagent --version` | Print version |

---

## 📊 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

```bash
# 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:

| Service | Port | Description |
|---------|------|-------------|
| `api` | 8000 | Python FastAPI — agent & run management |
| `worker` | 8080 | Go worker — async task execution |
| `dashboard` | 3000 | React monitoring UI |
| `redis` | 6379 | Task queue & pub/sub backbone |

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`

```bash
# 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`

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

### `tool.py`

```python
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

```python
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

```bash
# 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](CONTRIBUTING.md) for guidelines on opening issues, submitting pull requests, and the development workflow.

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

---

## 📄 License

MIT — see [LICENSE](LICENSE).

---

<div align="center">
Built with care by <a href="https://github.com/flowagent">FlowAgent Contributors</a>
</div>
