Metadata-Version: 2.4
Name: agentbyte
Version: 0.1.0
Summary: A toolkit for designing multiagent systems
Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
Requires-Python: >=3.12
Requires-Dist: azure-identity>=1.25.1
Requires-Dist: openai>=1.107.1
Requires-Dist: picoagents>=0.2.3
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: tenacity>=9.1.4
Description-Content-Type: text/markdown

# Agentbyte: Enterprise-Ready Multiagent Systems Toolkit

**Agentbyte** is an **enterprise-ready** Python toolkit for designing scalable, production-grade multiagent systems. This project serves a dual purpose:

1. **Learning Journey:** Master advanced AI engineering concepts by studying [picoagents](https://github.com/openai/picoagents) architecture, patterns, and design decisions
2. **Knowledge Application:** Build Agentbyte step-by-step based on personal knowledge and preferences, deepening expertise in multiagent systems
3. **Enterprise Library:** Create a production-ready library with multi-framework and multi-LLM support
4. **Cross-Framework Compatibility:** Enable seamless composition of agents from Agentbyte, [Microsoft Agent Framework](https://github.com/microsoft/agent-framework), and [Pydantic AI](https://ai.pydantic.dev/)

The development approach is iterative and intentional: understand a pattern from picoagents → implement it in Agentbyte with custom enhancements → validate with examples → move to next pattern. This methodology builds both library quality and deep AI engineering expertise.

## Core Stack

- **Python 3.13+**
- [picoagents](https://github.com/openai/picoagents) >= 0.2.3 (reference framework for learning agent orchestration patterns)
- [pydantic](https://docs.pydantic.dev/) for data validation and settings management
- **LLM Providers:**
  - OpenAI API (GPT-4, GPT-5 series models)
  - AWS Bedrock (future integration)
- **Frameworks:**
  - Microsoft Agent Framework (integration in progress)
  - Pydantic AI (integration in progress)

## Architecture

### Directory Structure

```
src/agentbyte/           # Main package
├── agent/              # Agent base classes and abstractions
│   └── base.py         # BaseAgent ABC - extend this for custom agents
├── settings/           # Environment and configuration management
│   └── core.py         # Settings classes (AppSettings, PostgresSettings, AgentbyteBaseSettings)
└── __init__.py         # Package exports

examples/               # Working examples and use patterns
├── pico-agent-test.py  # Simple agent with tool usage
└── round-robin.py      # Multi-agent orchestration with termination conditions

notebooks/              # Development/exploration notebooks
└── pico-init-agent-test.ipynb  # Interactive testing environment

external_lib/           # External reference implementations
└── designing-multiagent-systems/  # picoagents reference (git submodule)
```

### Key Components

#### 1. **Settings System** (`src/agentbyte/settings/core.py`)

**Purpose:** Centralized environment variable management with Pydantic

**Key Classes:**
- `AgentbyteBaseSettings`: Base class for all agentbyte configuration
  - Provides `.from_env_file(Path)` classmethod for notebook/custom environments
  - Automatically prefixes environment variables (e.g., `APP_`, `POSTGRES_`)
- `AppSettings`: Application-level config (log_level, environment)
- `PostgresSettings`: Database connection with `.url` property for connection strings

**Pattern:** All settings classes use Pydantic's `SettingsConfigDict` with `env_prefix` to organize environment variables by domain. Settings can be loaded from custom paths—essential for notebooks that don't run from project root.

```python
# In notebooks or custom paths:
settings = PostgresSettings.from_env_file(Path("../../../.env"))
```

#### 2. **Agent Base** (`src/agentbyte/agent/base.py`)

**Purpose:** Abstract base for custom agent implementations

**Current State:** Minimal ABC definition—this is where domain-specific agent logic should be added. Agents build on picoagents' `Agent` class.

**Integration Pattern:** Agents use `OpenAIChatCompletionClient` for LLM connectivity and can compose multiple agents through picoagents' orchestrators (RoundRobinOrchestrator, etc.).

### External Dependency: picoagents (Reference Framework)

**picoagents** serves as the reference implementation for understanding agent orchestration patterns. Key concepts to study and potentially abstract:
- **Agents:** Named, instruction-driven with optional tools and model clients
- **Orchestrators:** RoundRobinOrchestrator for multi-agent conversations
- **Termination Conditions:** MaxMessageTermination, TextMentionTermination for conversation flow control
- **Tools:** Functions exposed to agents via function introspection

**Learning Goal:** Extract generalizable patterns from picoagents that can be reused across Autogen/Pydantic AI frameworks. See [external_lib/designing-multiagent-systems/picoagents](external_lib/designing-multiagent-systems/picoagents) for full reference source and [examples/round-robin.py](examples/round-robin.py) for application patterns.

## Learning-Driven Development Approach

The development methodology is structured to build both knowledge and production-grade code:

### Study Phase (Per Pattern)

1. **Analyze picoagents source** - Deep dive into a specific pattern (e.g., Agent class, RoundRobinOrchestrator)
2. **Understand design decisions** - Why this pattern? What problems does it solve?
3. **Identify abstractions** - What's framework-specific vs. generalizable?
4. **Research alternatives** - How do Microsoft Agent Framework or Pydantic AI handle similar problems?

### Implementation Phase

1. **Design for Agentbyte** - Create abstractions aligned with personal preferences and requirements
2. **Reference picoagents** but don't copy - Implement with own understanding and improvements
3. **Document rationale** - Why this design? What trade-offs were considered?
4. **Build incrementally** - One pattern at a time, test thoroughly before moving on

### Validation Phase

1. **Create working examples** - Demonstrate the pattern in practical scenarios
2. **Test cross-framework compatibility** - Can this work with Pydantic AI or MS Agent Framework concepts?
3. **Iterate based on learnings** - Refine implementation as understanding deepens

### Knowledge Capture

- **File documentation** - Each module should explain architectural decisions
- **Example-driven learning** - examples/ folder shows how to use patterns correctly
- **Notebook exploration** - notebooks/ folder for interactive learning and experimentation

## Development Workflows

### Environment Setup

```bash
# Project uses UV for dependency management (uv.lock present)
# Python 3.13+ required (see .python-version)
# Copy .env template for API keys: OPENAI_API_KEY required, optional: POSTGRES_*, HF_TOKEN, etc.

# Clone with submodules:
git clone --recursive git@github.com:yourusername/agentbyte.git
cd agentbyte

# Or if already cloned:
git submodule update --init --recursive
```

### Testing & Validation

```bash
# Test dependencies available (pytest, pytest-cov)
# Run: pytest tests/ -v --cov=src/agentbyte
# (tests/ directory not yet created—add test files here)
```

### Development in Notebooks

The project uses Jupyter notebooks for interactive development:
- **Kernel:** ipykernel configured for Python 3.13+
- **Pattern:** Import agentbyte modules, load settings with `.from_env_file()`, test agent interactions
- **Example:** [notebooks/pico-init-agent-test.ipynb](notebooks/pico-init-agent-test.ipynb) demonstrates agent initialization and response handling

### Running Examples

```bash
# Simple agent example (requires OPENAI_API_KEY in .env):
# Supports: gpt-4o, gpt-4-turbo, gpt-4, gpt-5 (as available)
python examples/pico-agent-test.py

# Multi-agent orchestration:
python examples/round-robin.py
```

## Project-Specific Patterns

### 1. **Settings Management Convention**

- **Use `AgentbyteBaseSettings` as base class** for all new settings
- **Prefix environment variables by domain:** `APP_`, `POSTGRES_`, `OPENAI_*`, etc.
- **In notebooks:** Always use `.from_env_file(Path(...))` to load from project root's .env

### 2. **Agent Tool Definition**

Tools are plain Python functions:

```python
def get_weather(location: str) -> str:
    """Tool docstring becomes description in agent."""
    return f"Weather in {location}: ..."

# Agents auto-discover tools via function introspection
agent = Agent(..., tools=[get_weather])
```

### 3. **Multiagent Patterns**

Use picoagents' orchestrators and termination conditions:
- **RoundRobinOrchestrator:** Sequential agent turns for collaborative workflows
- **Termination:** Combine with `MaxMessageTermination | TextMentionTermination` (pipe operator) for robust conversation ending

### 4. **Module Organization**

- Core abstractions go in `src/agentbyte/`
- Tools belong in `src/tools/` (currently empty—create submodules here as needed)
- Examples should demonstrate reusable patterns, not hard-coded workflows

## Critical Integration Points

1. **LLM Provider Abstraction:** 
   - **OpenAI:** `OpenAIChatCompletionClient` with GPT-4/GPT-5 series (`gpt-4o`, `gpt-4-turbo`, `gpt-4`, `gpt-5`)
   - **AWS Bedrock:** Planned integration for Claude, Llama, and other Bedrock-hosted models
   - **Provider Pattern:** All LLM clients implement a common interface for seamless switching and fallback strategies

2. **Environment & Configuration Management:** 
   - All credentials and settings loaded at runtime via Pydantic settings classes
   - Never commit secrets; use .env in .gitignore
   - Support for multiple provider configurations in a single deployment

3. **Picoagents Reference Architecture:** Study [external_lib/designing-multiagent-systems/picoagents/src/picoagents](external_lib/designing-multiagent-systems/picoagents/src/picoagents) for:
   - Agent base classes: `agents/_base.py`, `agents/_agent.py`
   - Orchestrators: `orchestration/` (RoundRobinOrchestrator, etc.)
   - Termination strategies: `termination/` (MaxMessageTermination, TextMentionTermination, etc.)
   - Tool handling: `tools/_base.py`, `tools/_decorator.py`

4. **Multi-Framework & Multi-LLM Composition:** 
   - Agents from Agentbyte, Pydantic AI, and Microsoft Agent Framework work together in unified workflows
   - Adapters normalize execution, tool invocation, and message handling across frameworks and LLM providers
   - Enables sophisticated deployments mixing specialized agents with optimal provider selection per task

## Framework & Provider Compatibility Roadmap

### Current Phase: Foundation & OpenAI Integration

- Build core abstractions based on picoagents patterns
- Implement agentbyte abstractions for agent orchestration
- Full OpenAI GPT-4 and GPT-5 series model support
- Create reproducible examples and enterprise patterns
- Establish settings and configuration management for production deployments

### Phase 2: Microsoft Agent Framework Integration

- Study [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) agent model and orchestration patterns
- Create adapter layers for seamless interoperability
- Design shared abstractions for enterprise agent lifecycle management
- Enable mixed Agentbyte + Microsoft Agent Framework deployments
- Reference: [https://github.com/microsoft/agent-framework](https://github.com/microsoft/agent-framework)

### Phase 3: Pydantic AI Compatibility

- Integrate [Pydantic AI](https://ai.pydantic.dev/) for validation-heavy agent tasks
- Build adapters for transparent Pydantic AI agent composition
- Create examples showing specialized agent selection patterns
- Enable mixed Agentbyte + Pydantic AI deployments
- Reference: [https://ai.pydantic.dev/](https://ai.pydantic.dev/)

### Phase 4: AWS Bedrock LLM Support

- Implement Bedrock client adapter for Claude, Llama, and other Bedrock models
- Build multi-LLM provider abstraction layer
- Create cost-optimization patterns (e.g., use cheaper models for simple tasks)
- Support cross-region and failover strategies
- Enable enterprises to avoid OpenAI lock-in

### Cross-Framework & Multi-LLM Composition Patterns

- **Design Goal:** Enterprise deployments mixing frameworks and LLM providers transparently
- **Approach:** 
  - Adapter interfaces normalize agent execution, tool invocation, and messaging
  - Provider abstraction enables seamless LLM switching without code changes
  - Orchestrators manage intelligent agent and provider selection
- **Enterprise Use Cases:**
  - Use Pydantic AI for strict validation tasks + Agentbyte for orchestration
  - Route tasks to specialized agents (e.g., Microsoft Agent Framework for Azure-native scenarios)
  - Switch LLM providers based on cost, latency, or capability requirements
  - Implement fallback chains: GPT-4 → Bedrock Claude → GPT-4-turbo
- **Implementation Pattern:** Adapters and orchestrators handle all framework/provider differences transparently

## What NOT to Do

- Don't copy code directly from picoagents—study it, understand it, then implement with your own understanding and enhancements
- Don't hard-code API keys or configuration—always use settings classes (enterprise requirement)
- Don't import from tools/ directly yet (module is empty)—tools should be organized within specific domains
- Don't override BaseAgent without understanding the multiagent orchestration requirements first
- Don't skip the learning phase to rush implementation—understanding patterns deeply is the goal
- Avoid notebook-only code; move reusable patterns into src/agentbyte/ (this is the actual library)
- Don't ignore cross-framework compatibility during design—keep Microsoft Agent Framework and Pydantic AI patterns in mind

## Success Criteria

✓ **Deep Understanding:** Can explain the "why" behind each pattern and design decision
✓ **Documented Code:** Each component has clear rationale for its design approach
✓ **Working Examples:** Practical demonstrations of each pattern from Agentbyte
✓ **Cross-Framework Ready:** Abstractions are designed to integrate with MS Agent Framework and Pydantic AI
✓ **Enterprise Quality:** Settings, error handling, and configuration management suitable for production
✓ **Iterative Growth:** Library grows step-by-step with learning, not all at once

## Contributing

This project is structured for intentional, learning-focused development. When contributing:
1. Study the pattern from picoagents (or the reference framework)
2. Document your understanding in comments and docstrings
3. Create examples that demonstrate the pattern
4. Consider cross-framework compatibility in your design

## License

[Your License Here]

## References

- [picoagents](https://github.com/openai/picoagents) - Reference agent orchestration framework
- [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) - Enterprise agent orchestration
- [Pydantic AI](https://ai.pydantic.dev/) - Pydantic-based agent framework
- [OpenAI API](https://platform.openai.com/docs/) - LLM provider
- [AWS Bedrock](https://aws.amazon.com/bedrock/) - Managed LLM service
