Metadata-Version: 2.4
Name: agentic-fleet
Version: 0.5.0
Summary: A multi-agent orchestration system built with Microsoft Agent Framework
Project-URL: Homepage, https://github.com/Qredence/AgenticFleet
Project-URL: Documentation, https://github.com/Qredence/AgenticFleet/docs
Project-URL: Repository, https://github.com/Qredence/AgenticFleet
Project-URL: Issues, https://github.com/Qredence/AgenticFleet/issues
Author-email: Qredence <contact@qredence.ai>
License: MIT
Keywords: agents,ai,microsoft-agent-framework,multi-agent,orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=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: agent-framework-redis
Requires-Dist: azure-ai-agents>=1.2.0b5
Requires-Dist: azure-identity>=1.25.1
Requires-Dist: mem0ai==1.0.0b0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.32.5
Provides-Extra: azure
Requires-Dist: azure-ai-agents>=1.2.0b5; extra == 'azure'
Description-Content-Type: text/markdown

# AgenticFleet

[![CI](https://github.com/Qredence/AgenticFleet/workflows/CI/badge.svg)](https://github.com/Qredence/AgenticFleet/actions/workflows/ci.yml)
[![Release](https://github.com/Qredence/AgenticFleet/workflows/Release/badge.svg)](https://github.com/Qredence/AgenticFleet/actions/workflows/release.yml)
[![CodeQL](https://github.com/Qredence/AgenticFleet/workflows/CodeQL%20Security%20Analysis/badge.svg)](https://github.com/Qredence/AgenticFleet/actions/workflows/codeql.yml)
[![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)](https://opensource.org/licenses/MIT)

**Version:** 0.5.0
**Package:** `agentic-fleet` (PyPI) | `agenticfleet` (import)

A sophisticated multi-agent system powered by Microsoft Agent Framework that coordinates specialized AI agents to solve complex tasks through dynamic delegation and collaboration.

## 🎯 Overview

AgenticFleet implements a custom orchestration pattern where an orchestrator agent intelligently delegates tasks to specialized agents:

- **🎯 Orchestrator Agent**: Plans and coordinates task distribution
- **🔍 Researcher Agent**: Gathers information through web searches
- **💻 Coder Agent**: Writes and executes Python code
- **📊 Analyst Agent**: Analyzes data and suggests visualizations

## ✨ Features

- ✅ **Modern Package Structure**: PyPA-recommended `src/` layout for import safety
- ✅ **Dynamic Task Decomposition**: Automatic breakdown of complex tasks
- ✅ **Multi-Agent Coordination**: Seamless collaboration between specialized agents
- ✅ **Event-Driven Architecture**: Real-time monitoring and observability
- ✅ **Structured Responses**: Type-safe tool outputs with Pydantic models
- ✅ **Configurable Execution**: Safety controls and execution limits
- ✅ **Individual Agent Configs**: Dedicated configuration per agent
- ✅ **Persistent Memory**: `mem0` integration for long-term memory
- ✅ **Console Script**: Easy CLI access via `agentic-fleet` command

## 🏗️ Architecture

```text
┌─────────────────────────────────────────┐
│         User Interface (CLI)            │
│     Console: agentic-fleet              │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│      Custom Workflow Orchestrator       │
│   (Coordination & State Management)     │
└──────────────┬──────────────────────────┘
               │
    ┌──────────┴──────────┐
    │                     │
    ▼                     ▼
┌─────────────┐    ┌──────────────┐
│Orchestrator │◄───┤ Specialized  │
│   Agent     │    │    Agents    │
└─────┬───────┘    └──────┬───────┘
      │                   │
      │  ┌────────────────┼────────┐
      │  │                │        │
      ▼  ▼                ▼        ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│Researcher│  │  Coder   │  │ Analyst  │
│(Web)     │  │(Code)    │  │(Data)    │
└──────────┘  └──────────┘  └──────────┘
      ▲
      │
┌─────┴───────┐
│ Mem0 Context│
│  Provider   │
└─────────────┘
```

### Package Structure (src/ Layout)

```text
src/agenticfleet/           # Main package (import: agenticfleet)
├── __init__.py            # Package entry, version, exports
├── __main__.py            # Module entry (python -m agenticfleet)
├── agents/                # All agent factories + tools
│   ├── orchestrator/      # Orchestrator agent
│   │   ├── agent.py       # Factory: create_orchestrator_agent()
│   │   ├── config.yaml    # Agent-specific configuration
│   │   └── tools/         # Agent tools (if any)
│   ├── researcher/        # Researcher agent with web search
│   │   ├── agent.py       # Factory: create_researcher_agent()
│   │   ├── config.yaml
│   │   └── tools/
│   │       └── web_search_tools.py
│   ├── coder/             # Coder agent with code execution
│   │   ├── agent.py       # Factory: create_coder_agent()
│   │   ├── config.yaml
│   │   └── tools/
│   │       └── code_interpreter.py
│   └── analyst/           # Analyst agent with data analysis
│       ├── agent.py       # Factory: create_analyst_agent()
│       ├── config.yaml
│       └── tools/
│           └── data_analysis_tools.py
├── workflows/             # Multi-agent orchestration
│   └── multi_agent.py     # MultiAgentWorkflow class
├── config/                # Configuration management
│   ├── settings.py        # Settings class (loads env vars)
│   └── workflow.yaml      # Workflow-level config
├── context/               # Long-term memory providers
│   └── mem0_provider.py   # Mem0 integration
├── core/                  # Core utilities
│   ├── exceptions.py      # Custom exceptions
│   ├── logging.py         # Logging configuration
│   └── types.py           # Type definitions, enums
└── cli/                   # CLI interface
    └── repl.py            # Interactive REPL

tests/                     # All tests
├── test_config.py         # Configuration validation
├── test_mem0_context_provider.py  # Memory tests
└── test_hello.py          # Sanity check

docs/                      # Documentation
├── AGENTS.md              # Agent development guidelines
├── MEM0_INTEGRATION.md    # Memory integration docs
├── MIGRATION_COMPLETE.md  # Migration report
├── TEMPERATURE_FIX.md     # API compliance fixes
├── COMMANDS.md            # Command reference
└── ...
```

## 📋 Prerequisites

- **Python**: 3.12 or higher
- **Azure AI Project**: An Azure AI project with a deployed model.
- **Azure AI Search**: An Azure AI Search service.
- **uv**: Modern Python package manager (recommended)

## 🚀 Quick Start

### 1. Clone and Navigate

```bash
git clone https://github.com/Qredence/AgenticFleet.git
cd AgenticFleet
```

### 2. Set Up Environment

```bash
# Copy environment template
cp .env.example .env

# Edit .env and add your keys and endpoints
# Required:
#   - OPENAI_API_KEY
#   - AZURE_AI_PROJECT_ENDPOINT
#   - AZURE_AI_SEARCH_ENDPOINT
#   - AZURE_AI_SEARCH_KEY
#   - AZURE_OPENAI_CHAT_COMPLETION_DEPLOYED_MODEL_NAME
#   - AZURE_OPENAI_EMBEDDING_DEPLOYED_MODEL_NAME
```

### 3. Install Dependencies (uv-first approach)

**Using uv (recommended):**

```bash
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies (creates .venv automatically)
uv sync

# Optional: activate shell (not required when using `uv run`)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows
```

#### Using pip (not recommended)

See `docs/COMMANDS.md` for pip-based installation.

### 4. Validate Configuration

```bash
# Run configuration tests (should pass 6/6)
uv run pytest tests/test_config.py -v
```

### 5. Run the Application

#### Method 1: Console script (easiest)

```bash
uv run agentic-fleet
```

#### Method 2: Module execution

```bash
uv run python -m agenticfleet
```

#### Method 3: Direct REPL file (legacy)

```bash
uv run python src/agenticfleet/cli/repl.py
```

### 5. Developer Workflow

#### Using Makefile (recommended)

```bash
make help          # Show all available commands
make install       # First-time setup
make test-config   # Validate configuration (6/6 tests)
make run           # Launch application
make check         # Run all quality checks (lint + type-check)
make format        # Auto-format code
```

**Using uv directly:**

```bash
# Format code
uv run black .

# Lint code
uv run ruff check .
uv run ruff check --fix .    # Auto-fix issues

# Type checking
uv run mypy src/agenticfleet

# Run tests
uv run pytest                # All tests
uv run pytest -v             # Verbose
uv run pytest tests/test_config.py  # Specific file

# All-in-one validation
uv sync && uv run black . && uv run ruff check . && uv run mypy src/agenticfleet && uv run pytest
```

**Pre-commit hooks** (automated checks on git commit):

```bash
make pre-commit-install
# or: uv run pre-commit install
```

## 💡 Usage Examples

### Basic Import

```python
# Import package version
from agenticfleet import __version__
print(f"AgenticFleet v{__version__}")

# Import workflow
from agenticfleet.workflows import workflow

# Run a task
result = await workflow.run("Research Python best practices")
```

### Creating Individual Agents

```python
from agenticfleet.agents import (
    create_orchestrator_agent,
    create_researcher_agent,
    create_coder_agent,
    create_analyst_agent,
)

# Create agents
orchestrator = create_orchestrator_agent()
researcher = create_researcher_agent()
coder = create_coder_agent()
analyst = create_analyst_agent()

# Use individual agent
result = await researcher.run("Search for Python ML libraries")
```

### Using Configuration

```python
from agenticfleet.config import settings

# Access settings
api_key = settings.openai_api_key
model = settings.openai_model

# Load agent-specific config
agent_cfg = settings.load_agent_config("orchestrator")
print(agent_cfg["agent"]["name"])  # "orchestrator"
```

### Custom Workflow

```python
from agenticfleet.workflows import MultiAgentWorkflow

# Create workflow instance
workflow = MultiAgentWorkflow()

# Run task with automatic agent coordination
result = await workflow.run(
    "Analyze sales data and create visualizations"
)
print(result)
```

## ⚙️ Configuration

### Environment Variables (.env)

```bash
# OpenAI API Key
OPENAI_API_KEY=sk-your-key-here

# Azure AI Project Endpoint
AZURE_AI_PROJECT_ENDPOINT=your-azure-ai-project-endpoint

# Azure AI Search Configuration
AZURE_AI_SEARCH_ENDPOINT=your-azure-ai-search-endpoint
AZURE_AI_SEARCH_KEY=your-azure-ai-search-key

# Azure OpenAI Deployed Model Names
AZURE_OPENAI_CHAT_COMPLETION_DEPLOYED_MODEL_NAME=your-chat-completion-model-name
AZURE_OPENAI_EMBEDDING_DEPLOYED_MODEL_NAME=your-embedding-model-name

# Log Level (e.g., INFO, DEBUG)
LOG_LEVEL=INFO
```

## 📖 Documentation

All documentation is located in the `docs/` folder:

### Core Documentation

- **[Quick Reference](docs/QUICK_REFERENCE.md)** - Getting started guide and common commands
- **[Commands Reference](docs/COMMANDS.md)** - Complete command reference for all operations
- **[Agent Guidelines](docs/AGENTS.md)** - Development rules and agent conventions
- **[Implementation Summary](docs/IMPLEMENTATION_SUMMARY.md)** - Technical architecture details

### Migration & Updates

- **[Migration Complete](docs/MIGRATION_COMPLETE.md)** - Full src/ layout migration report
- **[Migration Summary](docs/MIGRATION_SRC_LAYOUT.md)** - Quick migration overview
- **[Temperature Fix](docs/TEMPERATURE_FIX.md)** - API compliance fixes
- **[OpenAI API Migration](docs/MIGRATION_TO_RESPONSES_API.md)** - Responses API updates

### Features & Integration

- **[Mem0 Integration](docs/MEM0_INTEGRATION.md)** - Persistent memory with mem0
- **[Progress Tracker](docs/ProgressTracker.md)** - Project milestones and status
- **[Bug Fixes](docs/FIXES.md)** - Issue resolutions and patches
- **[Phase 1 PRD](docs/af-phase-1.md)** - Original product requirements

### Additional Resources

- **[Cleanup Checklist](docs/CLEANUP_CHECKLIST.md)** - Post-migration validation
- **[Test Summary](docs/TEST_SUMMARY.md)** - Test coverage and results

## 🛠️ Development Tools

- **uv**: Fast Python package manager with lockfile support
- **Ruff**: Lightning-fast linter and formatter
- **Black**: Opinionated code formatter
- **mypy**: Static type checker
- **pytest**: Testing framework
- **pre-commit**: Git hooks for automated quality checks
- **GitHub Actions**: CI/CD with automated testing and linting
- **Makefile**: Convenient command shortcuts

## 🔄 CI/CD

The project includes automated CI/CD via GitHub Actions (`.github/workflows/ci.yml`):

- ✅ Lint with Ruff
- ✅ Format check with Black
- ✅ Type check with mypy
- ✅ Configuration validation (6 tests)
- ✅ Full test suite execution (28 tests)
- ✅ Security scanning (optional)
- ✅ Matrix testing (Python 3.12 & 3.13)
- ✅ Automated dependency caching
- ✅ Pre-commit.ci integration for automatic fixes

## 🚢 Installation (Future PyPI)

Once published to PyPI, users can install AgenticFleet:

```bash
# Using pip
pip install agentic-fleet

# Using uv (recommended)
uv pip install agentic-fleet
```

Then import and use:

```python
from agenticfleet import __version__, MultiAgentWorkflow

print(f"AgenticFleet v{__version__}")

workflow = MultiAgentWorkflow()
result = await workflow.run("Your task here")
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the coding standards
4. Run tests: `uv run pytest`
5. Run quality checks: `make check` or `uv run black . && uv run ruff check . && uv run mypy src/agenticfleet`
6. Commit your changes (`git commit -m 'feat: add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- **Microsoft Agent Framework** - Core agent orchestration framework
- **OpenAI** - Language model APIs
- **mem0** - Persistent memory management
- **uv** - Fast Python package manager
- **Ruff** - Lightning-fast linter and formatter

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/Qredence/AgenticFleet/issues)
- **Documentation**: [docs/](docs/)
- **Email**: <contact@qredence.ai>

---

### Built with ❤️ by Qredence
