# Broadie

A powerful multi-agent framework developed by the Broad Institute for building intelligent, collaborative AI systems with persistence, API integration, and agent-to-agent communication.

## Overview

Broadie enables you to create sophisticated AI agent systems that can work together, remember conversations, integrate with external services, and communicate with other agents. Whether you're building a simple chatbot or a complex multi-agent workflow, Broadie provides the infrastructure you need.

## Key Features

- **Two Usage Modes**: JSON configuration for quick setup or programmatic Python API for advanced customization
- **Agent Collaboration**: Main agents coordinate with specialized sub-agents
- **Persistent Memory**: Agents remember conversations and learn from interactions
- **Tool Integration**: Built-in tools for file operations, Google Drive, Slack, and more
- **API Server**: REST and WebSocket endpoints for web integration
- **Agent Communication**: Secure peer-to-peer agent discovery and function calls
- **Multiple AI Models**: Support for Google Gemini, Vertex AI, and more

## Installation

```bash
pip install broadie
```

## Quick Start

### Option 1: JSON Configuration (Simple Setup)

Perfect for getting started quickly or creating agents without custom logic.

1. **Create an agent configuration** (`my_agent.json`):

```json
{
  "name": "helpful_assistant",
  "description": "A helpful AI assistant",
  "instruction": "You are a helpful AI assistant that can answer questions and help with tasks.",
  "model": {
    "provider": "google",
    "name": "gemini-2.0-flash"
  }
}
```

2. **Run your agent**:

```bash
broadie run my_agent.json
```

### Option 2: Programmatic Python API (Advanced)

Use this approach when you need custom tools, complex logic, or want to extend agent capabilities.

```python
from broadie import Agent, SubAgent, tool

# Define custom tools that your agents can use
@tool(name="analyze_data", description="Analyze data and return insights")
def analyze_data(data: str) -> str:
    # Your custom analysis logic here
    return f"Analysis complete: {data} shows positive trends"

@tool(name="generate_report", description="Generate a formatted report")
def generate_report(findings: str) -> str:
    return f"# Report\n\n{findings}\n\n*Generated by Broadie*"

# Create a specialized sub-agent
class AnalystAgent(SubAgent):
    def build_config(self):
        return {
            "name": "data_analyst",
            "description": "Specializes in data analysis",
            "instruction": "You are a data analysis expert. Use your tools to analyze data and provide insights."
        }

# Create the main coordination agent
class ResearchCoordinator(Agent):
    def build_config(self):
        return {
            "name": "research_coordinator", 
            "description": "Coordinates research tasks",
            "instruction": "You coordinate research tasks, delegating analysis to specialists and compiling results.",
            "sub_agents": [AnalystAgent()]
        }

# Use your agent
async def main():
    agent = ResearchCoordinator()
    response = await agent.process_message("Analyze our Q4 sales data and generate a report")
    print(response)
```

## When to Use Each Approach

### JSON Configuration
- **Best for**: Quick prototypes, simple agents, configuration-driven workflows
- **Limitations**: Cannot add custom tools or complex logic
- **Use cases**: Customer support bots, FAQ assistants, content generators

### Python API  
- **Best for**: Production systems, custom integrations, complex workflows
- **Advantages**: Full customization, custom tools, advanced logic, integration with existing systems
- **Use cases**: Data analysis pipelines, API integrations, complex business workflows

## Configuration

### Environment Setup

Create a `.env` file with your API keys and settings:

```bash
# Required: AI Model Access
GOOGLE_API_KEY=your_google_api_key_here

# Optional: Agent-to-Agent Communication
A2A_ENABLED=true
A2A_AGENT_ID=my_agent_001
A2A_AGENT_NAME=my_helpful_agent

# Optional: Database (defaults to SQLite)
DB_DRIVER=sqlite
DB_NAME=broadie.db

# Optional: Slack Integration
SLACK_BOT_TOKEN=xoxb-your-slack-token
SLACK_CHANNEL=#general

# Optional: Google Drive Integration  
GOOGLE_DRIVE_CREDENTIALS_PATH=/path/to/credentials.json
```

## Built-in Tools

Broadie agents automatically have access to powerful built-in tools:

### File Operations
- Read, write, and edit files
- List directories and search content

### Google Drive Integration (when configured)
- Search documents and spreadsheets
- Read and write Google Docs
- Create and update Google Sheets

### Slack Integration (when configured)
- Send messages to channels
- Search message history
- Upload files and create threads

### Task Management
- Create and manage todo lists
- Track progress across conversations

## CLI Commands

```bash
# Initialize a new project with templates
broadie init my_project

# Run an agent from JSON config
broadie run agent.json

# Run an agent from Python code
broadie run module.path:MyAgent

# Start API server for web integration
broadie serve agent.json

# Create agent configurations
broadie create agent customer_support
broadie create sub-agent data_analyzer

# List available project templates
broadie templates
```

## API Integration

Start a web server to integrate agents with your applications:

```bash
broadie serve my_agent.json
```

This provides:
- **Web UI**: Visit `http://localhost:8000/ui` to chat with your agent in the browser
- **REST API**: `POST /agents/{id}/invoke` for function calls
- **WebSocket**: `/ws` for real-time chat
- **Health Check**: `GET /health` for monitoring

## Agent-to-Agent Communication

Agents can discover and communicate with each other for complex workflows:

```python
# Agent A can invoke functions on Agent B
result = await coordinator_agent.invoke_peer_agent(
    "analyst_agent_id", 
    "analyze_sales_data",
    {"data": sales_data, "period": "Q4"}
)
```

## Project Templates

Get started faster with built-in templates:

- **simple**: Single agent for basic tasks
- **integration**: Agent with API integration capabilities  
- **generic**: Multi-agent system template
- **support**: Customer support system with specialized agents

```bash
broadie init --template support my_support_system
```

## Example Use Cases

### Customer Support System
```bash
broadie init --template support customer_help
cd customer_help
# Configure your API keys in .env
broadie serve main.json
```

### Data Analysis Pipeline
```python
# Create agents for data ingestion, analysis, and reporting
# Each agent specializes in one aspect of the pipeline
# Main agent coordinates the workflow
```

### Content Generation Workflow
```python
# Research agent gathers information
# Writer agent creates content  
# Editor agent reviews and refines
# Coordinator manages the entire process
```

## Support and Documentation

- **Issues**: [GitHub Issues](https://github.com/broadinstitute/broadie/issues)
- **Documentation**: [docs.broadie.ai](https://docs.broadie.ai)
- **Community**: [GitHub Discussions](https://github.com/broadinstitute/broadie/discussions)

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Developed by the Broad Institute** - Empowering researchers and developers with intelligent agent systems.