Metadata-Version: 2.4
Name: agentic-fleet
Version: 0.6.9
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-a2a
Requires-Dist: agent-framework-azure-ai
Requires-Dist: agent-framework-azure-ai-search>=0.0.0a1
Requires-Dist: agent-framework-azurefunctions>=0.0.0a1
Requires-Dist: agent-framework-core
Requires-Dist: agent-framework-declarative>=1.0.0b251204
Requires-Dist: agent-framework-devui
Requires-Dist: agent-framework>=1.0.0b251204
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: anyio<5.0,>=4.11.0
Requires-Dist: asyncer<1.0,>=0.0.8
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: azure-monitor-opentelemetry-exporter>=1.0.0b45
Requires-Dist: azure-monitor-opentelemetry>=1.8.2
Requires-Dist: azure-search-documents>=11.6.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[standard]<1.0,>=0.120.1
Requires-Dist: gepa[dspy]<1.0,>=0.0.17
Requires-Dist: httpx>=0.24.0
Requires-Dist: ipykernel<8.0,>=7.0.1
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: mcp>=1.21.0
Requires-Dist: mlflow>=3.6.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=2.5.1
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.38.0
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: prometheus-fastapi-instrumentator>=6.1.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: python-dotenv<2.0,>=1.2.1
Requires-Dist: python-json-logger>=2.0.7
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: scipy>=1.9.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: setuptools>=80.9.0
Requires-Dist: sqlalchemy>=2.0.44
Requires-Dist: statsd>=3.3.0
Requires-Dist: tavily-python>=0.7.12
Requires-Dist: tenacity>=8.2.3
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: 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: azure-monitor-opentelemetry>=1.6.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: tracing
Requires-Dist: azure-monitor-opentelemetry>=1.6.0; extra == 'tracing'
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

<p align="center">
  <img src="assets/banner.png" alt="AgenticFleet" width="100%"/>
</p>

<p align="center">
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"/></a>
  <a href="https://pepy.tech/projects/agentic-fleet"><img src="https://static.pepy.tech/personalized-badge/agentic-fleet?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=BLUE&left_text=downloads" alt="PyPI Downloads"/></a>
  <a href="https://deepwiki.com/qredence/agentic-fleet"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"/></a>
  <a href="https://pypi.org/project/agentic-fleet/"><img src="https://img.shields.io/pypi/v/agentic-fleet?color=blue" alt="PyPI Version"/></a>
  <a href="https://pypi.org/project/agentic-fleet/"><img src="https://img.shields.io/pypi/pyversions/agentic-fleet" alt="Python Versions"/></a>
</p>

<h3 align="center">
  <b>Self-Optimizing Multi-Agent Orchestration</b>
</h3>

<p align="center">
  Intelligent task routing with <a href="https://github.com/stanfordnlp/dspy">DSPy</a> • Robust execution with <a href="https://github.com/microsoft/agent-framework">Microsoft Agent Framework</a>
</p>

---

## ✨ What is AgenticFleet?

AgenticFleet is a production-ready multi-agent orchestration system that **automatically routes tasks to specialized AI agents** and orchestrates their execution through a self-optimizing pipeline.

```
User Task → Analysis → Intelligent Routing → Agent Execution → Quality Check → Output
```

**Key Features:**

- 🧠 **DSPy-Powered Routing** – Typed signatures with Pydantic validation for reliable structured outputs
- 🔄 **5 Execution Modes** – Auto, Delegated, Sequential, Parallel, Handoff, and Discussion
- 🎯 **6 Specialized Agents** – Researcher, Analyst, Writer, Reviewer, Coder, Planner
- ⚡ **Smart Fast-Path** – Simple queries bypass multi-agent routing (<1s response)
- 📊 **Built-in Evaluation** – Azure AI Evaluation integration for quality metrics
- 🔍 **OpenTelemetry Tracing** – Full observability with Azure Monitor export

## 🚀 Quick Start

### Installation

```bash
# Clone and install
git clone https://github.com/Qredence/agentic-fleet.git && cd agentic-fleet
uv sync  # or: pip install agentic-fleet

# Configure environment
cp .env.example .env
# Set OPENAI_API_KEY (required)
# Set TAVILY_API_KEY (optional, enables web search)
```

### Run

```bash
# Interactive CLI
agentic-fleet

# Single task
agentic-fleet run -m "Research the latest advances in AI agents" --verbose

# Development server (backend + frontend)
agentic-fleet dev
```

## 📖 Usage

### CLI

```bash
agentic-fleet                              # Interactive console
agentic-fleet run -m "Your task"           # Execute a task
agentic-fleet run -m "Query" --mode handoff  # Specific execution mode
agentic-fleet list-agents                  # Show available agents
agentic-fleet dev                          # Start dev servers
```

### Python API

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

async def main():
    workflow = await create_supervisor_workflow()
    result = await workflow.run("Summarize the transformer architecture")
    print(result["result"])

asyncio.run(main())
```

### Web Interface

```bash
agentic-fleet dev  # Backend: http://localhost:8000, Frontend: http://localhost:5173
```

The web interface provides:

- Real-time streaming responses with workflow visualization
- Conversation history with persistence
- Agent activity display and orchestration insights

## 🤖 Agents & Execution Modes

### Specialized Agents

| Agent          | Expertise                                           |
| -------------- | --------------------------------------------------- |
| **Researcher** | Web search, information gathering, source synthesis |
| **Analyst**    | Data analysis, code review, technical evaluation    |
| **Writer**     | Content creation, documentation, summarization      |
| **Reviewer**   | Quality assurance, fact-checking, critique          |
| **Coder**      | Code generation, debugging, implementation          |
| **Planner**    | Task decomposition, strategy, coordination          |

### Execution Modes

| Mode           | Description                         | Best For             |
| -------------- | ----------------------------------- | -------------------- |
| **Auto**       | DSPy selects optimal mode (default) | Most tasks           |
| **Delegated**  | Single agent handles entire task    | Focused work         |
| **Sequential** | Agents work in pipeline             | Multi-step tasks     |
| **Parallel**   | Concurrent agent execution          | Independent subtasks |
| **Handoff**    | Direct agent-to-agent transfers     | Specialized chains   |
| **Discussion** | Multi-agent group chat              | Complex problems     |

## ⚙️ Configuration

### Environment Variables

```bash
# Required
OPENAI_API_KEY=sk-...

# Optional
TAVILY_API_KEY=tvly-...          # Web search capability
DSPY_COMPILE=true                # Enable DSPy optimization
ENABLE_OTEL=true                 # OpenTelemetry tracing
OTLP_ENDPOINT=http://...         # Tracing endpoint
```

### Workflow Configuration

All runtime settings are in `src/agentic_fleet/config/workflow_config.yaml`:

```yaml
dspy:
  optimization:
    use_typed_signatures: true # Pydantic-validated outputs
    enable_routing_cache: true # Cache routing decisions
    cache_ttl_seconds: 300 # Cache TTL

models:
  router: gpt-4o-mini # Fast routing decisions
  agents: gpt-4o # Agent execution

execution:
  max_iterations: 10
  quality_threshold: 0.8
```

## 🏗️ Architecture

```
src/agentic_fleet/
├── agents/           # Agent definitions & AgentFactory
├── workflows/        # Orchestration: supervisor, executors, strategies
├── dspy_modules/     # DSPy signatures, typed models, assertions
├── tools/            # Tavily, browser, MCP bridges, code interpreter
├── app/              # FastAPI backend + SSE streaming
├── cli/              # Typer CLI commands
├── config/           # workflow_config.yaml (source of truth)
└── utils/            # Helpers, caching, tracing

src/frontend/         # React/Vite UI
```

**Key Design Principles:**

1. **Config-Driven** – All models, agents, and thresholds in YAML
2. **Offline Compilation** – DSPy modules compiled offline, never at runtime
3. **Type Safety** – Pydantic models for all DSPy outputs
4. **Assertion-Driven** – DSPy assertions for routing validation

## 🧪 Development

```bash
make install           # Install dependencies
make dev               # Run backend + frontend
make test              # Run tests
make check             # Lint + type-check (run before committing)
make clear-cache       # Clear DSPy cache after module changes
```

## 📚 Documentation

| Guide                                                               | Description                     |
| ------------------------------------------------------------------- | ------------------------------- |
| [Getting Started](docs/users/getting-started.md)                    | Installation and first steps    |
| [Configuration](docs/users/configuration.md)                        | Environment and workflow config |
| [Frontend Guide](docs/users/frontend.md)                            | Web interface usage             |
| [Architecture](docs/developers/architecture.md)                     | System design and internals     |
| [DSPy Integration](docs/guides/dspy-agent-framework-integration.md) | DSPy + Agent Framework patterns |
| [Tracing](docs/guides/tracing.md)                                   | OpenTelemetry setup             |
| [Troubleshooting](docs/users/troubleshooting.md)                    | Common issues and solutions     |

## 🆕 What's New in v0.6.9

- **Typed DSPy Signatures** – Pydantic models for validated, type-safe outputs
- **DSPy Assertions** – Hard constraints and soft suggestions for routing validation
- **Routing Cache** – TTL-based caching for routing decisions
- **Task Type Detection** – Automatic classification (research/coding/analysis/writing)

See [CHANGELOG.md](CHANGELOG.md) for full release history.

## 🤝 Contributing

We welcome contributions! Here's how to get started:

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/agentic-fleet.git
cd agentic-fleet

# Install dev dependencies
uv sync

# Create a branch
git checkout -b feature/your-feature-name

# Make changes, then run checks
make check              # Lint + type-check
make test               # Run tests

# Submit a PR
```

**Guidelines:**

- Follow the existing code style (Ruff formatting, type hints)
- Add tests for new features
- Update documentation as needed
- Use [conventional commits](https://www.conventionalcommits.org/) (optional but appreciated)

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## 📄 License

This project is licensed under the **MIT License** – you're free to use, modify, and distribute this software for any purpose.

See the [LICENSE](LICENSE) file for the full text.

## 🙏 Acknowledgments

AgenticFleet stands on the shoulders of giants. Special thanks to:

| Project                                                                   | Contribution                                   |
| ------------------------------------------------------------------------- | ---------------------------------------------- |
| [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) | Multi-agent runtime and orchestration patterns |
| [DSPy](https://github.com/stanfordnlp/dspy)                               | Programmatic LLM pipelines and optimization    |
| [Tavily](https://tavily.com)                                              | AI-native search API for research agents       |
| [FastAPI](https://fastapi.tiangolo.com/)                                  | Modern async Python web framework              |
| [Pydantic](https://docs.pydantic.dev/)                                    | Data validation and settings management        |
| [OpenTelemetry](https://opentelemetry.io/)                                | Observability and distributed tracing          |

And to all our [contributors](https://github.com/Qredence/agentic-fleet/graphs/contributors) who help make AgenticFleet better! 💜

---

<p align="center">
  <a href="https://github.com/Qredence/agentic-fleet/issues/new?template=bug_report.md">🐛 Report Bug</a> •
  <a href="https://github.com/Qredence/agentic-fleet/issues/new?template=feature_request.md">✨ Request Feature</a> •
  <a href="https://github.com/Qredence/agentic-fleet/discussions">💬 Discussions</a>
</p>

<p align="center">
  <sub>Made with ❤️ by <a href="https://qredence.ai">Qredence</a></sub>
</p>
