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)

# 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

# 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

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

Expected response:

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

2. List Capabilities

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

3. Get Specific Capability

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

4. Search Capabilities

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

# 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

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

# Security scan
bandit -r src/

Database Migrations

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

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

Next Steps

1. Read the Documentation

   • API Specification
   • Architecture
   • Security Framework

2. Explore Examples

   • Text Classification
   • Fraud Detection
   • Integration Example

3. Deploy to Production

   • Review Deployment Guide
   • Configure monitoring and logging
   • Set up CI/CD pipeline

Troubleshooting

Port Already in Use

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

Database Connection Error

# Check PostgreSQL is running
docker-compose ps

# Check database logs
docker-compose logs db

Redis Connection Error

# 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 for details