QUICKSTART.md

# 🚀 BDR Agent Factory - Quick Start Guide

## Prerequisites

- Python 3.11+
- Docker & Docker Compose (optional)
- PostgreSQL 16+ (if not using Docker)
- Redis 7+ (if not using Docker)

## Installation

### Option 1: Docker (Recommended)

```bash
# Clone the repository
git clone https://huggingface.co/spaces/BDR-AI/BDR-Agent-Factory
cd BDR-Agent-Factory

# Start all services
docker-compose up -d

# Check logs
docker-compose logs -f api
```

The API will be available at http://localhost:8000

### Option 2: Local Development

```bash
# Clone the repository
git clone https://huggingface.co/spaces/BDR-AI/BDR-Agent-Factory
cd BDR-Agent-Factory

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

# Install dependencies
pip install -e .[ml,dev]

# Copy environment file
cp .env.example .env
# Edit .env with your configuration

# Start PostgreSQL and Redis (if not using Docker)
# Then run the application
uvicorn bdr_agent_factory.main:app --reload
```

## Quick Test

### 1. Health Check

```bash
curl http://localhost:8000/api/v1/health
```

Expected response:
```json
{
  "status": "healthy",
  "timestamp": "2026-01-03T00:00:00",
  "service": "BDR Agent Factory"
}
```

### 2. List Capabilities

```bash
curl http://localhost:8000/api/v1/capabilities
```

### 3. Get Specific Capability

```bash
curl http://localhost:8000/api/v1/capabilities/cap_text_classification
```

### 4. Search Capabilities

```bash
curl http://localhost:8000/api/v1/capabilities/search/fraud
```

## API Documentation

Once the server is running, visit:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

## Project Structure

```
BDR-Agent-Factory/
├── src/
│   └── bdr_agent_factory/
│       ├── api/              # API endpoints
│       ├── capabilities/     # AI capability implementations
│       ├── core/            # Core functionality
│       ├── models/          # Data models
│       ├── services/        # Business logic
│       └── utils/           # Utilities
├── docs/                    # Documentation
├── examples/                # Example implementations
├── tests/                   # Test suite
├── AI_CAPABILITY_DICTIONARY.yaml
├── CAPABILITY_SYSTEM_MAP.yaml
├── pyproject.toml
├── Dockerfile
└── docker-compose.yml
```

## Development Workflow

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=bdr_agent_factory --cov-report=html

# Run specific test file
pytest tests/test_registry.py
```

### Code Quality

```bash
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

# Security scan
bandit -r src/
```

### Database Migrations

```bash
# Create migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1
```

## Next Steps

1. **Read the Documentation**
   - [API Specification](docs/API_SPECIFICATION.md)
   - [Architecture](docs/ARCHITECTURE.md)
   - [Security Framework](docs/SECURITY_FRAMEWORK.md)

2. **Explore Examples**
   - [Text Classification](examples/text_classification_example.py)
   - [Fraud Detection](examples/fraud_detection_example.py)
   - [Integration Example](examples/integration_example.py)

3. **Deploy to Production**
   - Review [Deployment Guide](docs/VERSION_CONTROL_STRATEGY.md)
   - Configure monitoring and logging
   - Set up CI/CD pipeline

## Troubleshooting

### Port Already in Use

```bash
# Change port in docker-compose.yml or .env
API_PORT=8001
```

### Database Connection Error

```bash
# Check PostgreSQL is running
docker-compose ps

# Check database logs
docker-compose logs db
```

### Redis Connection Error

```bash
# Check Redis is running
docker-compose ps

# Test Redis connection
redis-cli ping
```

## Support

- **Documentation**: See `/docs` directory
- **Issues**: Open an issue on HuggingFace
- **Discussions**: Join the discussion board

## License

MIT License - See [LICENSE](LICENSE) for details