Jason Woltje
dad4b68f66
Add AI-powered issue metadata parser using Anthropic Sonnet model. - Parse issue markdown to extract: estimated_context, difficulty, assigned_agent, blocks, blocked_by - Implement in-memory caching to avoid duplicate API calls - Graceful fallback to defaults on parse failures - Add comprehensive test suite (9 test cases) - 95% test coverage (exceeds 85% requirement) - Add ANTHROPIC_API_KEY to config - Update documentation and add .env.example Fixes #158 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
155 lines
3.8 KiB
Markdown
155 lines
3.8 KiB
Markdown
# Mosaic Coordinator
|
|
|
|
FastAPI webhook receiver for Gitea issue events, enabling autonomous task coordination for AI agents.
|
|
|
|
## Overview
|
|
|
|
The coordinator receives webhook events from Gitea when issues are assigned, unassigned, or closed. It verifies webhook authenticity via HMAC SHA256 signature and routes events to appropriate handlers.
|
|
|
|
## Features
|
|
|
|
- HMAC SHA256 signature verification
|
|
- Event routing (assigned, unassigned, closed)
|
|
- AI-powered issue metadata parsing (using Anthropic Sonnet)
|
|
- Context estimation and agent assignment
|
|
- Dependency tracking (blocks/blocked_by)
|
|
- Comprehensive logging
|
|
- Health check endpoint
|
|
- Docker containerized
|
|
- 95%+ test coverage
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.11+
|
|
- pip or uv package manager
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run with coverage
|
|
pytest --cov=src --cov-report=html
|
|
|
|
# Type checking
|
|
mypy src/
|
|
|
|
# Linting
|
|
ruff check src/
|
|
```
|
|
|
|
### Running locally
|
|
|
|
```bash
|
|
# Copy environment template
|
|
cp .env.example .env
|
|
|
|
# Edit .env with your values
|
|
# GITEA_WEBHOOK_SECRET, GITEA_URL, ANTHROPIC_API_KEY
|
|
|
|
# Run server
|
|
uvicorn src.main:app --reload --port 8000
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### POST /webhook/gitea
|
|
|
|
Receives Gitea webhook events.
|
|
|
|
**Headers:**
|
|
|
|
- `X-Gitea-Signature`: HMAC SHA256 signature of request body
|
|
|
|
**Response:**
|
|
|
|
- `200 OK`: Event processed successfully
|
|
- `401 Unauthorized`: Invalid or missing signature
|
|
- `422 Unprocessable Entity`: Invalid payload
|
|
|
|
### GET /health
|
|
|
|
Health check endpoint.
|
|
|
|
**Response:**
|
|
|
|
- `200 OK`: Service is healthy
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Required | Default |
|
|
| ---------------------- | ------------------------------------------- | -------- | ------- |
|
|
| `GITEA_WEBHOOK_SECRET` | Secret for HMAC signature verification | Yes | - |
|
|
| `GITEA_URL` | Gitea instance URL | Yes | - |
|
|
| `ANTHROPIC_API_KEY` | Anthropic API key for issue parsing | Yes | - |
|
|
| `LOG_LEVEL` | Logging level (debug, info, warning, error) | No | info |
|
|
| `HOST` | Server host | No | 0.0.0.0 |
|
|
| `PORT` | Server port | No | 8000 |
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
# Build
|
|
docker build -t mosaic-coordinator .
|
|
|
|
# Run
|
|
docker run -p 8000:8000 \
|
|
-e GITEA_WEBHOOK_SECRET="your-secret" \
|
|
-e GITEA_URL="https://git.mosaicstack.dev" \
|
|
-e ANTHROPIC_API_KEY="your-anthropic-key" \
|
|
mosaic-coordinator
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
pytest
|
|
|
|
# Run with coverage (requires 85%+)
|
|
pytest --cov=src --cov-report=term-missing
|
|
|
|
# Run specific test file
|
|
pytest tests/test_security.py
|
|
|
|
# Run with verbose output
|
|
pytest -v
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
apps/coordinator/
|
|
├── src/
|
|
│ ├── main.py # FastAPI application
|
|
│ ├── webhook.py # Webhook endpoint handlers
|
|
│ ├── parser.py # Issue metadata parser (Anthropic)
|
|
│ ├── models.py # Data models
|
|
│ ├── security.py # HMAC signature verification
|
|
│ ├── config.py # Configuration management
|
|
│ └── context_monitor.py # Context usage monitoring
|
|
├── tests/
|
|
│ ├── test_security.py
|
|
│ ├── test_webhook.py
|
|
│ ├── test_parser.py
|
|
│ ├── test_context_monitor.py
|
|
│ └── conftest.py # Pytest fixtures
|
|
├── pyproject.toml # Project metadata & dependencies
|
|
├── .env.example # Environment variable template
|
|
├── Dockerfile
|
|
└── README.md
|
|
```
|
|
|
|
## Related Issues
|
|
|
|
- #156 - Create coordinator bot user
|
|
- #157 - Set up webhook receiver endpoint
|
|
- #158 - Implement issue parser
|
|
- #140 - Coordinator architecture
|