Metadata-Version: 2.4
Name: agentic-fleet
Version: 0.6.0
Summary: Multi-agent orchestration system built with Microsoft Agent Framework's Magentic Fleet pattern
Project-URL: Homepage, https://github.com/Qredence/agentic-fleet
Project-URL: Documentation, https://github.com/Qredence/agentic-fleet/docs
Project-URL: Repository, https://github.com/Qredence/agentic-fleet
Project-URL: Issues, https://github.com/Qredence/agentic-fleet/issues
Author-email: Qredence <contact@qredence.ai>
License: MIT License
        
        Copyright (c) 2025 Qredence
        
        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.
License-File: LICENSE
Keywords: agents,ai,magentic
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4,>=3.12
Requires-Dist: agent-framework
Requires-Dist: agent-framework-a2a
Requires-Dist: agent-framework-azure-ai
Requires-Dist: agent-framework-core
Requires-Dist: agent-framework-devui
Requires-Dist: agent-framework-mem0
Requires-Dist: aiofiles<26.0,>=25.1.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiomqtt>=1.0.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: azure-ai-agents<2.0,>=1.2.0b5
Requires-Dist: azure-ai-evaluation<2.0,>=1.12.0
Requires-Dist: azure-cosmos<5.0,>=4.8.0
Requires-Dist: azure-identity<2.0,>=1.25.1
Requires-Dist: black>=25.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: databases[asyncpg]<1.0,>=0.7.0
Requires-Dist: dill>=0.3.8
Requires-Dist: dspy>=3.0.3
Requires-Dist: fastapi<1.0,>=0.120.1
Requires-Dist: flake8>=7.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: ipykernel<8.0,>=7.0.1
Requires-Dist: locust>=2.15.0
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: mcp>=1.21.0
Requires-Dist: mem0ai==1.0.0
Requires-Dist: mypy>=1.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=2.5.1
Requires-Dist: pandas>=1.5.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: plotly>=5.10.0
Requires-Dist: prometheus-client>=0.16.0
Requires-Dist: prompt-toolkit<4.0,>=3.0.47
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic-settings<3.0,>=2.3.2
Requires-Dist: pydantic<3.0,>=2.12.3
Requires-Dist: pytest-asyncio>=0.21.0
Requires-Dist: pytest-cov>=4.1.0
Requires-Dist: pytest<10.0,>=9.0.1
Requires-Dist: python-dotenv<2.0,>=1.2.1
Requires-Dist: pytz>=2024.1
Requires-Dist: pyyaml<7.0,>=6.0.3
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=14.2.0
Requires-Dist: ruff>=0.0.200
Requires-Dist: scipy>=1.9.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: setuptools>=80.9.0
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: statsd>=3.3.0
Requires-Dist: tavily-python>=0.7.12
Requires-Dist: textual>=6.5.0
Requires-Dist: tiktoken<1.0,>=0.12.0
Requires-Dist: typer<0.21.0,>=0.20.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: websockets>=10.4
Provides-Extra: all
Requires-Dist: agent-framework-devui; extra == 'all'
Requires-Dist: agent-framework-mem0; extra == 'all'
Requires-Dist: azure-ai-agents<2.0,>=1.2.0b5; extra == 'all'
Requires-Dist: azure-ai-evaluation<2.0,>=1.12.0; extra == 'all'
Requires-Dist: azure-identity<2.0,>=1.25.1; extra == 'all'
Requires-Dist: mem0ai==1.0.0; extra == 'all'
Requires-Dist: prompt-toolkit<4.0,>=3.0.47; extra == 'all'
Requires-Dist: rich>=14.2.0; extra == 'all'
Provides-Extra: azure
Requires-Dist: azure-ai-agents<2.0,>=1.2.0b5; extra == 'azure'
Requires-Dist: azure-identity<2.0,>=1.25.1; extra == 'azure'
Provides-Extra: evaluation
Requires-Dist: azure-ai-evaluation<2.0,>=1.12.0; extra == 'evaluation'
Provides-Extra: memory
Requires-Dist: agent-framework-mem0; extra == 'memory'
Requires-Dist: mem0ai==1.0.0; extra == 'memory'
Provides-Extra: ui
Requires-Dist: agent-framework-devui; extra == 'ui'
Requires-Dist: prompt-toolkit<4.0,>=3.0.47; extra == 'ui'
Requires-Dist: rich>=14.2.0; extra == 'ui'
Description-Content-Type: text/markdown

![AgenticFleet Architecture](assets/banner.png)

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/agentic-fleet?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/agentic-fleet)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/qredence/agentic-fleet)

> **⚠️ Active Development Notice**
> APIs, signatures, and execution semantics can change between minor versions. Pin a version tag for production usage.

---

# AgenticFleet – DSPy‑Enhanced Multi‑Agent Orchestration

AgenticFleet is a hybrid **DSPy + Microsoft agent-framework** runtime that delivers a self‑optimizing fleet of specialized AI agents. DSPy handles task analysis, routing, progress & quality assessment; agent-framework provides robust orchestration primitives, event streaming, and tool execution. Together they enable delegated, sequential, parallel, and handoff‑driven workflows with iterative refinement loops.

---

## Table of Contents

- [AgenticFleet – DSPy‑Enhanced Multi‑Agent Orchestration](#agenticfleet--dspyenhanced-multiagent-orchestration)
  - [Table of Contents](#table-of-contents)
  - [Key Features](#key-features)
  - [Architecture Overview](#architecture-overview)
  - [Directory Layout](#directory-layout)
  - [Installation](#installation)
    - [Python (uv recommended)](#python-uv-recommended)
    - [Standard pip](#standard-pip)
    - [Optional Frontend](#optional-frontend)
    - [Playwright (Browser Tool)](#playwright-browser-tool)
  - [Configuration \& Environment](#configuration--environment)
  - [Quick Start](#quick-start)
    - [TUI / CLI](#tui--cli)
    - [Python API](#python-api)
    - [Streaming](#streaming)
  - [Execution Modes](#execution-modes)
  - [Agents](#agents)
  - [DSPy Optimization](#dspy-optimization)
  - [Observability \& History](#observability--history)
  - [Evaluation \& Self-Improvement](#evaluation--self-improvement)
  - [Testing \& Quality](#testing--quality)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
  - [License](#license)
  - [Acknowledgments](#acknowledgments)
  - [Related Documentation](#related-documentation)

---

## Key Features

- **Adaptive Routing** – DSPy supervisor analyzes tasks and decides agent roster + execution mode (delegated / sequential / parallel).
- **Quality Loops** – Automatic Judge / Reviewer refinement when quality score drops below configurable threshold.
- **Tool‑Aware Decisions** – Signatures include tool context; Supervisor recommends tool usage (code interpreter, search, browser, etc.).
- **Streaming Events** – Emits OpenAI Responses‑compatible events for real‑time TUI / web UI updates.
- **Self‑Improvement** – GEPA + BootstrapFewShot compilation refines routing from curated examples & execution history.
- **YAML‑Driven** – Central `workflow_config.yaml` governs models, thresholds, agents, tracing, evaluation toggles.
- **Rich Ergonomics** – Typer CLI (`console.py`), `dspy-fleet` command, optional Vite frontend, history analytics scripts.
- **Safe Fallbacks** – Graceful degradation when DSPy unavailable (heuristic routing & quality scoring).
- **Extensible Toolkit** – Add agents, tools, signatures, evaluation metrics with minimal boilerplate.

---

## Architecture Overview

Four‑phase pipeline:

```
Task → [1] DSPy Analysis → [2] DSPy Routing → [3] Agent Execution → [4] Quality / Judge Assessment → (Optional Refinement)
```

| Phase     | Responsibility                            | Source                                                  |
| --------- | ----------------------------------------- | ------------------------------------------------------- |
| Analysis  | Extract goals, complexity, constraints    | `dspy_modules/supervisor.py` (`analyze_task`)           |
| Routing   | Pick agents + execution mode, tools       | `dspy_modules/supervisor.py` (`route_task`)             |
| Execution | Orchestrate agents & tools; stream events | `workflows/supervisor_workflow.py`                      |
| Quality   | Score output, recommend improvements      | `dspy_modules/supervisor.py` (`assess_quality` + Judge) |

Refinement triggers when score < threshold (default 8 or judge threshold ≥ 7). Handoffs coordinate multi‑agent chains via `HandoffManager`.

Consult: `docs/developers/architecture.md` & `docs/guides/quick-reference.md`.

---

## Directory Layout

| Path                              | Purpose                                                    |
| --------------------------------- | ---------------------------------------------------------- |
| `config/workflow_config.yaml`     | Models, agents, thresholds, tracing, evaluation flags      |
| `src/agentic_fleet/dspy_modules/` | DSPy Signatures & Supervisor implementation                |
| `src/agentic_fleet/workflows/`    | `SupervisorWorkflow`, handoff & exceptions                 |
| `src/agentic_fleet/agents/`       | Specialist configurations & factory                        |
| `src/agentic_fleet/tools/`        | Tool adapters: Tavily, Browser, Hosted Interpreter, MCP    |
| `src/agentic_fleet/utils/`        | Compiler cache, GEPA optimizer, history, tracing, registry |
| `src/agentic_fleet/evaluation/`   | Metrics & evaluator engine                                 |
| `src/agentic_fleet/console.py`    | Rich / Typer CLI (dspy-fleet)                              |
| `examples/`                       | Minimal workflow samples                                   |
| `scripts/`                        | Analysis, self-improvement, dataset generation             |
| `logs/`                           | Execution history, compilation artifacts                   |
| `frontend/`                       | Optional Vite + React streaming UI                         |

---

## Installation

### Python (uv recommended)

```bash
git clone https://github.com/Qredence/agentic-fleet.git
cd agentic-fleet
uv pip install -r requirements.txt
uv pip install -e .
```

### Standard pip

```bash
pip install -r requirements.txt
pip install -e .
```

### Optional Frontend

```bash
make frontend-install          # installs Node dependencies
make dev                       # runs backend + frontend dev servers
```

### Playwright (Browser Tool)

```bash
playwright install chromium
```

---

## Configuration & Environment

Create `.env` (or copy `.env.example`):

```bash
OPENAI_API_KEY=sk-...          # Required for all model calls
TAVILY_API_KEY=tvly-...        # Enables web search for Researcher agent
DSPY_COMPILE=true              # Toggle DSPy compilation (true/false)
OPENAI_BASE_URL=https://...    # Optional custom endpoint
LANGFUSE_PUBLIC_KEY=...        # Optional observability
LANGFUSE_SECRET_KEY=...
```

Key YAML knobs (`workflow_config.yaml`):

- `dspy.model` – Supervisor model (e.g. gpt-5-mini)
- `dspy.optimization.metric_threshold` – Minimum routing accuracy
- `workflow.supervisor.max_rounds` – Conversation turn limit
- `workflow.supervisor.enable_streaming` – Event streaming toggle
- `agents.*` – Per-agent model + temperature + tools
- `evaluation.*` – Batch evaluation settings

---

## Quick Start

### TUI / CLI

```bash
dspy-fleet                          # Launch interactive console

uv run python console.py run -m "Research 2024 AI funding trends" --verbose
uv run python console.py analyze --dataset data/evaluation_tasks.jsonl
```

### Python API

```python
import asyncio
from agentic_fleet.workflows import create_supervisor_workflow

async def main():
		workflow = await create_supervisor_workflow(compile_dspy=True)
		result = await workflow.run("Summarize transformer architecture evolution")
		print(result["result"])  # final output
		print(result["quality"]) # quality assessment details

asyncio.run(main())
```

### Streaming

```python
async for event in workflow.run_stream("Compare AWS vs Azure AI offerings"):
		# Handle MagenticAgentMessageEvent / WorkflowOutputEvent
		print(event)
```

---

## Execution Modes

| Mode           | Description                                        | Use Case                            |
| -------------- | -------------------------------------------------- | ----------------------------------- |
| Delegated      | Single agent manages entire task                   | Focused research, simple writeups   |
| Sequential     | Output of one feeds next                           | Research → Analyze → Write report   |
| Parallel       | Multiple agents concurrently; synthesis afterwards | Multi‑source comparisons            |
| Handoff Chains | Explicit role transitions with artifacts           | Complex coding + verification flows |

Supervisor chooses based on task structure + examples; can be overridden via configuration or future explicit flags.

---

## Agents

Core specialists: Researcher, Analyst, Writer, Reviewer, Judge (quality). Extended handoff specialists: Planner, Executor, Coder, Verifier, Generator.

See **[AGENTS.md](AGENTS.md)** for detailed roles, tool usage, configuration examples, and selection guidelines.

---

## DSPy Optimization

Training examples live in `src/agentic_fleet/data/supervisor_examples.json`:

```json
{
  "task": "Research the latest AI advances",
  "team": "Researcher: web search\nAnalyst: code + data",
  "assigned_to": "Researcher,Analyst",
  "mode": "sequential"
}
```

Compilation (BootstrapFewShot + GEPA) occurs on first run (if `DSPY_COMPILE=true`). Cache stored under `logs/compiled_supervisor.pkl`. Refresh via:

```bash
uv run python manage_cache.py --clear
```

---

## Observability & History

- **History**: Structured events appended to `logs/execution_history.jsonl`.
- **Tracing**: Enable OpenTelemetry in YAML; export to AI Toolkit / OTLP endpoint.
- **Logging**: Adjustable log level via env (`AGENTIC_FLEET_LOG_LEVEL=DEBUG`).
- **Analysis**: `scripts/analyze_history.py --all` surfaces aggregate metrics.

---

## Evaluation & Self-Improvement

Run batch evaluations against curated tasks:

```bash
uv run python console.py analyze --dataset data/evaluation_tasks.jsonl
```

Generate evaluation datasets from history:

```bash
uv run python scripts/create_history_evaluation.py
```

Self‑improve routing by folding high‑quality history examples back into DSPy training:

```bash
uv run python scripts/self_improve.py --max 50
```

---

## Testing & Quality

```bash
make check                 # lint (Ruff), format (Black), type‑check (mypy)
make test                  # run pytest suite
PYTHONPATH=. uv run pytest tests/workflows/test_supervisor_workflow.py::test_supervisor_workflow -q
```

Key test domains: routing accuracy, tool registry integration, judge refinement, lazy compilation, tracing hooks.

---

## Troubleshooting

| Symptom               | Cause                    | Fix                                           |
| --------------------- | ------------------------ | --------------------------------------------- |
| Missing web citations | `TAVILY_API_KEY` unset   | Export key or set in `.env`                   |
| Slow first run        | DSPy compilation         | Enable cache; reduce `max_bootstrapped_demos` |
| No streaming output   | `enable_streaming=false` | Toggle in YAML                                |
| Low quality score     | Insufficient examples    | Add training examples; rerun compilation      |
| Tool warning          | Name mismatch            | Verify tool name & registry entry             |

Detailed guides: `docs/users/troubleshooting.md`, `docs/guides/dspy-optimizer.md`.

---

## Contributing

1. Fork / branch (`breaking-refactor` for large changes)
2. Add or update tests (prefer focused unit tests over broad integration when possible)
3. Run `make check` and ensure no style / type errors
4. Update docs (README, AGENTS.md, or relevant guide) for user‑visible changes
5. Submit PR with clear rationale & architectural notes (link to `docs/developers/architecture.md` sections if modifying internals)

Please see: `docs/developers/contributing.md`.

---

## License

MIT License – see [LICENSE](LICENSE).

---

## Acknowledgments

- **Microsoft agent-framework** – Orchestration, events & tool interfaces
- **DSPy (Stanford NLP)** – Prompt optimization & structured signatures
- **Tavily** – Reliable, citation‑rich web search
- **OpenAI Responses** – Event paradigm enabling unified CLI/TUI/frontend streaming

---

## Related Documentation

- Getting Started: `docs/users/getting-started.md`
- Configuration: `docs/users/configuration.md`
- Architecture Deep Dive: `docs/developers/architecture.md`
- Quick Reference: `docs/guides/quick-reference.md`
- DSPy Optimization: `docs/guides/dspy-optimizer.md`
- Evaluation: `docs/guides/evaluation.md`
- Tracing: `docs/guides/tracing.md`
- Self Improvement: `docs/users/self-improvement.md`
- Troubleshooting: `docs/users/troubleshooting.md`

---

Happy hacking! 🚀
