# Agent Blackboard

A multi-agent coordination system for software engineering tasks using the Blackboard Pattern with MCP integration.

## Overview

Agent Blackboard implements a sophisticated multi-agent architecture where specialized AI agents collaborate on complex software engineering tasks through a shared knowledge repository (blackboard). Based on the classic Blackboard Pattern, this system enables:

- **Structured Knowledge Sharing**: Agents communicate through a well-defined ontology
- **Specialized Expertise**: Each agent focuses on specific domains (documentation, code review, testing, etc.)
- **Coordinated Execution**: Tasks are decomposed and distributed to appropriate agents
- **Contextual Intelligence**: Agents access relevant knowledge through embedding-based search

## Architecture

The system consists of three main components:

1. **Blackboard**: MCP-based shared knowledge repository
2. **Agents**: Specialized problem-solvers with specific capabilities
3. **Coordinator**: Orchestrates agent execution based on task requirements

## Features

- 🧠 **MCP Integration**: Persistent knowledge storage using Model Context Protocol
- 🤖 **Extensible Agent System**: Easy to add new specialized agents
- 💬 **A2A Protocol**: Direct agent-to-agent communication via the blackboard
- 📚 **Embedding-based Knowledge**: Contextual guidance using semantic search
- 📊 **Monitoring & Observability**: Track agent performance and system health
- 🔧 **Tool Framework**: Agents can use various tools (file ops, code analysis, etc.)
- 🎯 **DDD Workflow**: Complete subdomain decomposition with automated RFC generation ⭐ NEW

## Quick Start

```python
import asyncio
from agent_blackboard import Blackboard, Coordinator
from agent_blackboard.agents import DocumentationAgent

async def main():
    # Initialize blackboard
    blackboard = Blackboard()
    await blackboard.initialize()

    # Create coordinator
    coordinator = Coordinator(blackboard)

    # Register documentation agent
    doc_agent = DocumentationAgent(
        agent_id="doc_agent_1",
        blackboard=blackboard
    )
    coordinator.register_agent(doc_agent)

    # Execute documentation task
    task = {
        "type": "generate_documentation",
        "scope": "api",
        "source_files": ["src/agent_blackboard/core/"],
        "output_format": "markdown"
    }

    result = await coordinator.execute_task(task)
    print(f"Documentation generated: {result['output_path']}")

asyncio.run(main())
```

### Try the Complete DDD Workflow ⭐

Experience the full power of multi-agent collaboration:

```bash
# Run complete DDD subdomain decomposition
python examples/run_ddd_workflow.py

# Try different sample subdomains
python examples/run_ddd_workflow.py healthcare_scheduling
python examples/run_ddd_workflow.py fintech_lending
```

This workflow performs:
- ✅ Strategic DDD analysis (domain vision, bounded contexts, context mapping)
- ✅ Tactical DDD implementation (aggregates, domain events, repositories)
- ✅ Service documentation generation
- ✅ Comprehensive RFC creation with implementation roadmap

See [DDD_WORKFLOW_COMPLETE.md](DDD_WORKFLOW_COMPLETE.md) for details.

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/agent-blackboard.git
cd agent-blackboard

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .
```

## Configuration

### Quick Setup (3 steps)

1. **Get your Anthropic API key** at https://console.anthropic.com
2. **Create `.env` file** in project root:
   ```bash
   echo 'ANTHROPIC_API_KEY=sk-ant-your-actual-key-here' > .env
   ```
3. **Test configuration**:
   ```bash
   python test_setup.py
   ```

**See [QUICK_SETUP.md](QUICK_SETUP.md) for detailed setup instructions.**

### Full Configuration (Optional)

Create a `.env` file with all settings:

```bash
# Required
ANTHROPIC_API_KEY=sk-ant-...

# Optional
MCP_MEMORY_SERVER_PATH=./mcp_servers/memory
EMBEDDING_MODEL=all-MiniLM-L6-v2
LOG_LEVEL=INFO
BLACKBOARD_PERSISTENCE=sqlite
BLACKBOARD_DB_PATH=./data/blackboard.db
```

**See [docs/configuration.md](docs/configuration.md) for complete configuration guide.**

## 📚 Documentation

**[📖 Complete Documentation Index](docs/DOCUMENTATION_INDEX.md)**

### Quick Links
- **[🚀 Getting Started](docs/getting-started.md)** - Installation, tutorials, and first steps
- **[📘 API Reference](docs/api-reference.md)** - Complete API documentation
- **[🧪 Testing Guide](docs/testing.md)** - How to test and contribute
- **[⚙️ Configuration](docs/configuration.md)** - Setup and configuration
- **[💡 Examples](docs/examples.md)** - Working code examples
- **[🤝 Contributing](CONTRIBUTING.md)** - How to contribute

## Available Agents

The project includes 9 specialized agents:

### Documentation Agent
Generates comprehensive documentation from source code:
- README files from project structure
- API documentation from code
- Architecture diagrams (Mermaid)
- User guides from requirements
- Inline code comments

### API Designer Agent
Designs RESTful APIs with OpenAPI specifications:
- OpenAPI 3.1 spec generation
- Schema design and validation
- API best practices enforcement
- Postman collection export

### Backend Architect Agent
Designs scalable backend systems and microservices:
- Microservices architecture with DDD boundaries
- API Gateway patterns and configuration
- Event-driven architecture design
- Resilience patterns (circuit breakers, retries, bulkheads)
- Caching strategies and performance optimization
- Security architecture (OAuth2, JWT, RBAC)
- Observability design (tracing, logging, metrics)
- Data access patterns and repository design
- Architectural Decision Records (ADRs)

### Java Pro Agent ⭐
Expert Java 21+ developer with modern JVM features:
- Spring Boot 3.x microservice generation
- Java 21 virtual threads implementation
- REST API controllers with validation
- JPA entities and Spring Data repositories
- Spring Security with OAuth2/JWT
- Comprehensive test generation (JUnit 5, Testcontainers)
- JVM performance optimization
- GraalVM Native Image compilation
- Resilience4j patterns (Circuit Breaker, Retry)
- Java code review and best practices

### Golang Pro Agent ⭐ NEW
Expert Go 1.21+ developer with modern patterns and cloud-native expertise:
- Go microservice generation with clean architecture
- Advanced concurrency patterns (goroutines, channels, worker pools)
- REST APIs with Chi/Gin/Echo frameworks
- gRPC services with Protocol Buffers
- Data layer design with sqlx/GORM
- Comprehensive testing (unit, integration, benchmarks, testcontainers)
- Performance optimization (profiling, GC tuning, benchmarking)
- Middleware implementation (auth, logging, metrics, tracing)
- Kubernetes deployment and cloud-native patterns
- Go code review for idioms and best practices

### Architect Reviewer Agent
Reviews architecture and code quality:
- Architecture pattern validation (Clean Architecture, DDD, Microservices)
- SOLID principles checking
- Dependency analysis
- Security and performance reviews
- ADR (Architecture Decision Records) generation

### Observability Engineer Agent
Implements comprehensive observability:
- Monitoring setup (Prometheus/Grafana)
- Distributed tracing (OpenTelemetry)
- Dashboard design
- SLI/SLO management
- Alert rule creation
- Log aggregation

### Domain-Driven Design Strategist Agent
Strategic DDD implementation:
- Domain vision definition
- Bounded context design
- Context mapping
- Event storming facilitation
- Ubiquitous language establishment
- Strategic roadmap creation

### Domain-Driven Design Tactician Agent
Tactical DDD implementation:
- Aggregate design
- Domain model refinement
- Domain event design
- Repository pattern implementation
- Tactical pattern application
- Domain testing strategies

**[See all agents →](docs/agents/README.md)**

## Project Structure

```
agent-blackboard/
├── src/agent_blackboard/
│   ├── core/              # Blackboard, ontology, coordinator
│   ├── agents/            # Specialized agents
│   ├── tools/             # Agent tools
│   ├── monitoring/        # Metrics and logging
│   └── utils/             # Helper functions
├── examples/              # Usage examples
├── tests/                 # Test suite
└── docs/                  # Documentation
```

## Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/ tests/

# Type checking
mypy src/

# Linting
ruff check src/
```

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

## License

MIT License - see LICENSE file for details.

## Acknowledgments

Based on the Blackboard Pattern and inspired by modern multi-agent AI architectures.