[DmitryBMsk/llm-council-plus] How to Run LLM Council Plus
ChatGPT
API Leak/ChatGPT
9,104 characters
# How to Run LLM Council Plus
Quick start guide to get LLM Council Plus running on your machine.
---
## Prerequisites
### Required:
- **Python 3.10+** ([Download](https://python.org))
- **Node.js 18+** ([Download](https://nodejs.org))
- **uv** - Python package manager ([Install](https://docs.astral.sh/uv/))
### Optional (for database):
- **PostgreSQL 12+** (if using PostgreSQL storage)
- **MySQL 8+** (if using MySQL storage)
---
## Quick Start (5 minutes)
### 1. Get OpenRouter API Key
1. Go to [https://openrouter.ai](https://openrouter.ai)
2. Sign up for a free account
3. Generate API key
4. Add credits ($5 recommended for testing)
### 2. Clone & Setup
```bash
# Clone repository
git clone <your-repo-url>
cd llm-council-plus
# Install backend dependencies
uv sync
# Install frontend dependencies
cd frontend
npm install
cd ..
```
### 3. Configure Environment
```bash
# Copy example environment file
cp .env.example .env
# Edit .env and add your OpenRouter API key
nano .env # or use any text editor
```
**Required in `.env`:**
```bash
OPENROUTER_API_KEY=sk-or-v1-your-key-here
```
### 4. Run the Application
**Option A: Two Terminals (Recommended)**
Terminal 1 - Backend:
```bash
uv run python -m backend.main
```
Terminal 2 - Frontend:
```bash
cd frontend
npm run dev
```
**Option B: Background Processes**
```bash
# Start backend in background
uv run python -m backend.main &
# Start frontend
cd frontend
npm run dev
```
### 5. Open Application
Open your browser to: **http://localhost:5173**
---
## Configuration Options
### Storage Backend
**JSON (Default - Zero Setup):**
```bash
DATABASE_TYPE=json
```
**PostgreSQL:**
```bash
DATABASE_TYPE=postgresql
POSTGRESQL_URL=postgresql+psycopg2://user:password@localhost:5432/llmcouncil
```
**MySQL:**
```bash
DATABASE_TYPE=mysql
MYSQL_URL=mysql+pymysql://user:password@localhost:3306/llmcouncil
```
### Feature Flags
**Feature 4: Tools & Memory**
```bash
# All free tools enabled by default
# (Calculator, Wikipedia, ArXiv, DuckDuckGo, Yahoo Finance)
# Optional: Paid tools
ENABLE_TAVILY=false
TAVILY_API_KEY=
# Memory system (free local embeddings)
ENABLE_MEMORY=true
# Optional: Better embeddings
ENABLE_OPENAI_EMBEDDINGS=false
OPENAI_API_KEY=
# Advanced: LangGraph workflows
ENABLE_LANGGRAPH=false
```
---
## Detailed Setup
### Database Setup (Optional)
If using PostgreSQL or MySQL instead of JSON:
**PostgreSQL:**
```bash
# Install PostgreSQL
brew install postgresql # macOS
# or apt-get install postgresql # Linux
# Start PostgreSQL
brew services start postgresql
# Create database
createdb llmcouncil
# Update .env
DATABASE_TYPE=postgresql
POSTGRESQL_URL=postgresql+psycopg2://your_user:your_password@localhost:5432/llmcouncil
```
**MySQL:**
```bash
# Install MySQL
brew install mysql # macOS
# or apt-get install mysql-server # Linux
# Start MySQL
brew services start mysql
# Create database
mysql -u root -p
CREATE DATABASE llmcouncil;
exit;
# Update .env
DATABASE_TYPE=mysql
MYSQL_URL=mysql+pymysql://root:your_password@localhost:3306/llmcouncil
```
**Auto Initialization:**
- Tables are created automatically on first run
- No manual schema setup needed
---
## Development Mode
### Backend Development
```bash
# Run with auto-reload
uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port 8001
```
### Frontend Development
```bash
cd frontend
npm run dev
# Vite auto-reloads on file changes
```
### View Logs
```bash
# Backend logs
uv run python -m backend.main 2>&1 | tee backend.log
# Check logs
tail -f backend.log
```
---
## Testing
### Test Backend API
```bash
# Health check
curl http://localhost:8001/
# List conversations
curl http://localhost:8001/api/conversations
# Create conversation
curl -X POST http://localhost:8001/api/conversations \
-H "Content-Type: application/json" \
-d '{}'
```
### Test Frontend
1. Open http://localhost:5173
2. Click "+ New Conversation"
3. Type a question
4. Watch 3-stage council process
5. See final answer
### Test Features
**Test Delete:**
1. Hover over conversation → click ⋮
2. Click "Delete"
3. Confirm
**Test Edit Title:**
1. Hover over conversation → click ⋮
2. Click "Edit title"
3. Type new title → press Enter
**Test Tools:**
- Ask: "What's the price of AAPL stock?"
- Ask: "Calculate 12345 * 67890"
- Ask: "Search for latest AI news"
---
## Troubleshooting
### Port Already in Use
```bash
# Kill process on port 8001 (backend)
lsof -ti:8001 | xargs kill -9
# Kill process on port 5173 (frontend)
lsof -ti:5173 | xargs kill -9
```
### Backend Won't Start
```bash
# Check Python version
python --version # Must be 3.10+
# Reinstall dependencies
rm -rf .venv
uv sync
```
### Frontend Won't Start
```bash
# Check Node version
node --version # Must be 18+
# Reinstall dependencies
cd frontend
rm -rf node_modules package-lock.json
npm install
```
### Database Connection Error
```bash
# Check database is running
psql -l # PostgreSQL
mysql -u root -p # MySQL
# Verify connection string in .env
# Format: protocol://user:password@host:port/database
```
### API Key Issues
```bash
# Verify API key in .env
cat .env | grep OPENROUTER_API_KEY
# Test API key manually
curl https://openrouter.ai/api/v1/models \
-H "Authorization: Bearer YOUR_KEY_HERE"
```
### Memory/Tools Not Working
```bash
# Check dependencies installed
uv pip list | grep -E "langchain|chromadb|sentence-transformers"
# Reinstall if missing
uv sync
```
---
## Production Deployment
### Environment Setup
```bash
# Use production API keys
OPENROUTER_API_KEY=your-production-key
# Use database (not JSON)
DATABASE_TYPE=postgresql
POSTGRESQL_URL=your-production-db-url
# Security
SECRET_KEY=your-secret-key # Add if implementing auth
```
### Build Frontend
```bash
cd frontend
npm run build
# Serves from dist/ folder
```
### Run Production Backend
```bash
# Use production ASGI server
pip install gunicorn
gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8001
```
### Serve Frontend
```bash
# Option 1: Nginx
# Configure nginx to serve frontend/dist/
# Option 2: Node static server
npm install -g serve
serve -s frontend/dist -l 5173
```
---
## Docker Deployment (Optional)
### Backend Dockerfile
```dockerfile
FROM python:3.10
WORKDIR /app
COPY . .
RUN pip install uv && uv sync
CMD ["uv", "run", "python", "-m", "backend.main"]
EXPOSE 8001
```
### Frontend Dockerfile
```dockerfile
FROM node:18
WORKDIR /app
COPY frontend/package*.json ./
RUN npm install
COPY frontend/ ./
RUN npm run build
CMD ["npm", "run", "preview"]
EXPOSE 5173
```
### Docker Compose
```yaml
version: '3.8'
services:
backend:
build: .
ports:
- "8001:8001"
env_file:
- .env
depends_on:
- db
frontend:
build:
context: .
dockerfile: Dockerfile.frontend
ports:
- "5173:5173"
db:
image: postgres:15
environment:
POSTGRES_DB: llmcouncil
POSTGRES_PASSWORD: your_password
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:
```
Run:
```bash
docker-compose up -d
```
---
## Performance Tips
### Backend:
- Use PostgreSQL/MySQL instead of JSON for better performance
- Enable database connection pooling
- Use Redis for caching (future feature)
- Set `ENABLE_MEMORY=false` if not needed
### Frontend:
- Build for production: `npm run build`
- Enable gzip compression
- Use CDN for static assets
- Implement lazy loading
---
## Monitoring
### Check System Status
```bash
# Backend health
curl http://localhost:8001/
# Database connections
# PostgreSQL: SELECT * FROM pg_stat_activity;
# MySQL: SHOW PROCESSLIST;
```
### View Storage Info
```bash
# JSON mode
ls -lh data/conversations/
# Database mode
# Check via psql/mysql CLI
```
### Monitor API Usage
- Check OpenRouter dashboard for usage
- Monitor token consumption
- Track TOON savings
---
## Support
### Common Commands Reference
```bash
# Start backend
uv run python -m backend.main
# Start frontend
cd frontend && npm run dev
# View logs
tail -f backend.log
# Reset database (PostgreSQL)
dropdb llmcouncil && createdb llmcouncil
# Clear conversations (JSON mode)
rm -rf data/conversations/*
# Update dependencies
uv sync && cd frontend && npm install
```
### Get Help
- Check documentation in `contributions/` folder
- Review `.env.example` for configuration options
- Open issue on GitHub
---
## Quick Commands Summary
```bash
# 🚀 QUICK START (Copy-paste these 5 commands)
uv sync # Install backend
cd frontend && npm install && cd .. # Install frontend
cp .env.example .env # Create config
# Edit .env and add OPENROUTER_API_KEY
uv run python -m backend.main & # Start backend
cd frontend && npm run dev # Start frontend (opens browser)
```
**Access:** http://localhost:5173
---
## System Requirements
**Minimum:**
- 2 CPU cores
- 4GB RAM
- 2GB disk space
**Recommended:**
- 4+ CPU cores
- 8GB+ RAM
- 10GB disk space (for database)
**Platform:**
- macOS, Linux, Windows (WSL2)
- Docker (optional)