Metadata-Version: 2.4
Name: picoagents
Version: 0.3.1
Summary: A minimal multi-agent framework for educational purposes
Project-URL: Homepage, https://github.com/victordibia/designing-multiagent-systems
Project-URL: Documentation, https://github.com/victordibia/designing-multiagent-systems#readme
Project-URL: Repository, https://github.com/victordibia/designing-multiagent-systems
Author-email: Victor Dibia <victordibia@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,educational,llm,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: openai==1.107.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.70.0; extra == 'all'
Requires-Dist: arxiv>=2.0.0; extra == 'all'
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'all'
Requires-Dist: chromadb>=0.4.0; extra == 'all'
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: html2text>=2020.1.16; extra == 'all'
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: matplotlib; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: pillow>=10.0.0; extra == 'all'
Requires-Dist: playwright>=1.40.0; extra == 'all'
Requires-Dist: python-dotenv; extra == 'all'
Requires-Dist: python-multipart>=0.0.6; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'all'
Requires-Dist: yfinance; extra == 'all'
Requires-Dist: youtube-transcript-api>=0.6.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.70.0; extra == 'anthropic'
Provides-Extra: computer-use
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'computer-use'
Requires-Dist: pillow>=10.0.0; extra == 'computer-use'
Requires-Dist: playwright>=1.40.0; extra == 'computer-use'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: poethepoet; extra == 'dev'
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: matplotlib; extra == 'examples'
Requires-Dist: python-dotenv; extra == 'examples'
Requires-Dist: yfinance; extra == 'examples'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: otel
Requires-Dist: opentelemetry-api~=1.38.0; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http~=1.38.0; extra == 'otel'
Requires-Dist: opentelemetry-sdk~=1.38.0; extra == 'otel'
Provides-Extra: rag
Requires-Dist: chromadb>=0.4.0; extra == 'rag'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'rag'
Provides-Extra: research
Requires-Dist: arxiv>=2.0.0; extra == 'research'
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'research'
Requires-Dist: html2text>=2020.1.16; extra == 'research'
Requires-Dist: httpx>=0.24.0; extra == 'research'
Requires-Dist: youtube-transcript-api>=0.6.0; extra == 'research'
Provides-Extra: web
Requires-Dist: fastapi>=0.100.0; extra == 'web'
Requires-Dist: python-multipart>=0.0.6; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'web'
Description-Content-Type: text/markdown

# PicoAgents

![PicoAgents Web UI](https://raw.githubusercontent.com/victordibia/designing-multiagent-systems/main/docs/images/picoagents_screenshot.png)

**An educational multi-agent framework built to teach you how multi-agent systems work from first principles.**

Companion code for [**"Designing Multi-Agent Systems"**](https://buy.multiagentbook.com) by [Victor Dibia](https://victordibia.com). Every concept in the book is implemented here with clarity and best practices—so you can learn by reading the code and understanding exactly how it works.

> **Built for learning**: This framework prioritizes code clarity and pedagogical value over performance optimization.

## Installation

```bash
pip install picoagents
```

**Requirements:**

- Python 3.10+
- OpenAI API key (set `OPENAI_API_KEY` environment variable)

## Quick Start

```python
from picoagents import Agent, OpenAIChatCompletionClient

def get_weather(location: str) -> str:
    """Get current weather for a given location."""
    return f"The weather in {location} is sunny, 75°F"

# Create an agent
agent = Agent(
    name="assistant",
    instructions="You are helpful. Use tools when appropriate.",
    model_client=OpenAIChatCompletionClient(model="gpt-4.1-mini"),
    tools=[get_weather]
)

# Use the agent
response = await agent.run("What's the weather in Paris?")
print(response.messages[-1].content)
```

## What's Included

PicoAgents implements complete, working examples of:

- **Agents** - Reasoning loops, tool calling, memory, middleware, streaming
- **Workflows** - Type-safe DAG-based execution with parallel and conditional patterns
- **Orchestration** - Round-robin, AI-driven, and plan-based multi-agent coordination
- **Tools** - 15+ built-in tools (file ops, code execution, web search, planning)
- **Evaluation** - LLM-as-judge patterns, reference-based validation, metrics
- **Web UI** - Auto-discovery, streaming chat, session management

## Project Structure

```
picoagents/
├── src/picoagents/
│   ├── agents/            # Agent implementations (Ch 4-5)
│   ├── workflow/          # Workflow orchestration (Ch 5)
│   ├── orchestration/     # Autonomous coordination (Ch 6)
│   ├── tools/             # Tool system and built-in tools
│   ├── eval/              # Evaluation framework (Ch 8)
│   ├── webui/             # Web interface with auto-discovery
│   ├── llm/               # LLM clients (OpenAI, Azure)
│   ├── memory/            # Memory implementations
│   └── termination/       # Termination conditions
└── tests/                 # Comprehensive test suite
```

## Web UI

Launch the web interface with auto-discovery of agents and workflows:

```bash
picoagents ui
```

Features streaming responses, real-time debug events, and session management.

## Examples

See the [main repository](https://github.com/victordibia/designing-multiagent-systems) for 50+ runnable examples organized by book chapter:

- [`examples/agents/`](https://github.com/victordibia/designing-multiagent-systems/tree/main/examples/agents) - Basic agents, tools, memory, computer use (Ch 4-5)
- [`examples/workflows/`](https://github.com/victordibia/designing-multiagent-systems/tree/main/examples/workflows) - Workflow patterns and case studies (Ch 5)
- [`examples/orchestration/`](https://github.com/victordibia/designing-multiagent-systems/tree/main/examples/orchestration) - Multi-agent coordination (Ch 6)
- [`examples/evaluation/`](https://github.com/victordibia/designing-multiagent-systems/tree/main/examples/evaluation) - Evaluation patterns (Ch 8)

## Get the Book

<p align="center">
  <a href="https://buy.multiagentbook.com">
    <img src="https://raw.githubusercontent.com/victordibia/designing-multiagent-systems/main/docs/images/bookcover.png" alt="Designing Multi-Agent Systems Book Cover" width="100%">
  </a>
</p>

**[Designing Multi-Agent Systems: Principles, Patterns, and Implementation for AI Agents](https://buy.multiagentbook.com)**

This framework implements every concept from the book. The book provides:

- **Why and when** to use each pattern
- **Trade-off analysis** for design decisions
- **Real-world case studies** with complete implementations
- **Evaluation strategies** for measuring system performance

**[→ Buy Digital Edition](https://buy.multiagentbook.com)** | **[→ GitHub Repository](https://github.com/victordibia/designing-multiagent-systems)**

## Development

```bash
# Clone repository
git clone https://github.com/victordibia/designing-multiagent-systems.git
cd designing-multiagent-systems/picoagents

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/

# Type checking
python -m mypy src/
python -m pyright src/

# Code formatting
python -m black src/ tests/
python -m isort src/ tests/
```

## Author

**Victor Dibia** - [Website](https://victordibia.com) | [LinkedIn](https://www.linkedin.com/in/dibiavictor/) | [GitHub](https://github.com/victordibia)

## Citation

```bibtex
@book{dibia2025multiagent,
  title={Designing Multi-Agent Systems: Principles, Patterns, and Implementation for AI Agents},
  author={Dibia, Victor},
  year={2025},
  url={https://buy.multiagentbook.com}
}
```

## License

MIT License - see LICENSE file for details.

---

**Learn more**: [Book Website](https://buy.multiagentbook.com) | [GitHub](https://github.com/victordibia/designing-multiagent-systems) | [Documentation](https://github.com/victordibia/designing-multiagent-systems#readme)
