docs/SETUP.md

Setup Guide

Prerequisites

• Python 3.10+
• Node.js 16+ (for frontend)
• Redis (optional, for production)
• PostgreSQL (optional, for production)

Local Development Setup

Using Scripts (Recommended)

Windows:

cd backend
scripts\setup.bat
scripts\run.bat

Linux/macOS:

cd backend
chmod +x scripts/setup.sh scripts/run.sh
./scripts/setup.sh
./scripts/run.sh

Manual Setup

Backend

1. Create virtual environment:

   python -m venv venv
   
   # Windows
   venv\Scripts\activate.bat
   
   # Linux/macOS
   source venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   pip install -r requirements-dev.txt
   

3. Setup environment:

   cp .env.example .env
   # Edit .env with your OpenAI API key and settings
   

4. Run backend:

   uvicorn backend.api.main:app --reload
   

   Backend will be available at: http://localhost:8000 API Documentation: http://localhost:8000/docs

Frontend

1. Install dependencies:

   cd frontend
   npm install
   

2. Start development server:

   npm run dev
   

   Frontend will be available at: http://localhost:3000

Using Docker

Docker Compose (All Services)

docker-compose up --build

This starts:

• Backend: http://localhost:8000
• Redis: localhost:6379
• PostgreSQL: localhost:5432

Single Container

docker build -t multi-agent .
docker run -p 8000:8000 -e OPENAI_API_KEY=your_key multi-agent

Configuration

Environment Variables

See .env.example for all available options:

• OPENAI_API_KEY - Required: Your OpenAI API key
• DATABASE_URL - Database connection string
• REDIS_HOST/PORT - Redis configuration
• LOG_LEVEL - Logging level (INFO, DEBUG, etc.)

Database

SQLite (Development Default)

Automatically created as multi_agent.db

PostgreSQL (Production)

# Update DATABASE_URL in .env
DATABASE_URL=postgresql://user:password@localhost:5432/multi_agent

Running Tests

# All tests
pytest

# With coverage
pytest --cov=backend tests/

# Specific test file
pytest tests/test_agents.py -v

Troubleshooting

Port Already in Use

# Find process using port 8000
lsof -i :8000

# Kill process (Linux/macOS)
kill -9 <PID>

# Or change port
uvicorn backend.api.main:app --port 8001

OpenAI API Key Not Working

• Ensure key is set in .env file
• Check key is valid at https://platform.openai.com/account/api-keys
• Verify key has available credits

Redis Connection Issues

• Ensure Redis is running: redis-cli ping
• Check REDIS_HOST and REDIS_PORT in .env
• For Docker: use service name redis instead of localhost

Next Steps

• Check API Documentation
• Review Deployment Guide
• See Architecture Overview