discord-fishbowl/INSTALL.md

# Discord Fishbowl Installation Guide

## Quick Start

Run the interactive setup script to get started:

```bash
python install.py
```

This script will:
- ✅ Check system requirements
- ✅ Create a Python virtual environment  
- ✅ Install all dependencies
- ✅ Guide you through configuration
- ✅ Set up the database
- ✅ Create startup scripts

## Prerequisites

### Required
- **Python 3.8+** - The core application
- **Git** - For version control and updates

### Optional (but recommended)
- **Node.js & npm** - For the admin web interface
- **PostgreSQL** - For production database (SQLite available for testing)
- **Redis** - For caching and real-time features
- **Qdrant** - For vector database and semantic search

## Manual Installation

If you prefer manual setup:

### 1. Create Virtual Environment
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate.bat  # Windows
```

### 2. Install Dependencies
```bash
pip install -r requirements.txt
```

### 3. Install Frontend (optional)
```bash
cd admin-frontend
npm install
npm run build
cd ..
```

### 4. Configuration
Create a `.env` file with your settings:
```env
DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=your_server_id
DISCORD_CHANNEL_ID=your_channel_id
DATABASE_URL=sqlite:///data/fishbowl.db
AI_PROVIDER=openai
AI_API_KEY=your_openai_key
# ... more settings
```

### 5. Initialize Database
```bash
python -m alembic upgrade head
```

### 6. Create Characters
```bash
python -m scripts.init_characters
```

## Configuration Guide

### Discord Setup
1. Go to https://discord.com/developers/applications
2. Create a new application
3. Go to "Bot" section and create a bot
4. Copy the bot token
5. Enable required permissions and invite to your server

### AI Provider Setup

#### OpenAI
- Get API key from https://platform.openai.com/api-keys
- Recommended models: `gpt-4`, `gpt-3.5-turbo`

#### Anthropic
- Get API key from https://console.anthropic.com/
- Recommended models: `claude-3-sonnet-20240229`, `claude-3-haiku-20240307`

### Database Setup

#### SQLite (Default)
- No setup required
- Good for testing and small deployments

#### PostgreSQL (Recommended)
```bash
# Install PostgreSQL
sudo apt install postgresql  # Ubuntu
brew install postgresql      # macOS

# Create database
createdb discord_fishbowl
```

#### Redis (Optional)
```bash
# Install Redis
sudo apt install redis-server  # Ubuntu
brew install redis            # macOS

# Start Redis
redis-server
```

#### Qdrant (Optional)
```bash
# Using Docker
docker run -p 6333:6333 qdrant/qdrant

# Or install locally
# See: https://qdrant.tech/documentation/quick-start/
```

## Running the Application

### Using Startup Scripts
```bash
./start.sh          # Start main application
./start-admin.sh    # Start admin interface
```

### Manual Start
```bash
# Main application
python -m src.main

# Admin interface
python -m src.admin.app
```

## Verification

### Check Application Status
```bash
# Check logs
tail -f logs/fishbowl.log

# Check database
python -c "from src.database.connection import test_connection; test_connection()"

# Check AI provider
python -c "from src.llm.client import test_client; test_client()"
```

### Access Admin Interface
- Open http://localhost:8000/admin
- Login with credentials from setup

### Discord Integration
- Invite bot to your server
- Verify bot appears online
- Check configured channel for activity

## Troubleshooting

### Common Issues

#### "Module not found" errors
```bash
# Ensure virtual environment is activated
source venv/bin/activate

# Ensure PYTHONPATH is set
export PYTHONPATH=$(pwd):$PYTHONPATH
```

#### Database connection errors
```bash
# Test database connection
python -c "from src.database.connection import get_db_session; print('DB OK')"

# Reset database
python -m alembic downgrade base
python -m alembic upgrade head
```

#### Bot not responding
- Verify bot token is correct
- Check bot has required permissions
- Ensure guild_id and channel_id are correct
- Check bot is online in Discord

#### Memory/Performance issues
- Reduce `CONVERSATION_FREQUENCY` 
- Lower `MAX_CONVERSATION_LENGTH`
- Use PostgreSQL instead of SQLite
- Enable Redis for caching

### Getting Help

1. Check the logs in `logs/` directory
2. Verify configuration in `.env` file
3. Test individual components
4. Check Discord permissions
5. Verify API keys and external services

## Advanced Configuration

### Character Customization
Edit `config/characters.yaml` to modify character personalities and behaviors.

### System Tuning
Adjust these settings in `.env`:
- `CONVERSATION_FREQUENCY` - How often characters talk
- `RESPONSE_DELAY_MIN/MAX` - Realistic response timing
- `MEMORY_RETENTION_DAYS` - How long memories persist
- `CREATIVITY_BOOST` - Enable more creative responses

### Production Deployment
- Use PostgreSQL database
- Enable Redis caching
- Set up Qdrant vector database
- Configure proper logging levels
- Set `ENVIRONMENT=production`
- Use process manager (systemd, supervisor)
- Set up monitoring and backups

## Security Notes

- Keep API keys secure and never commit them
- Use strong passwords for admin interface
- Run on internal networks when possible
- Monitor for unusual activity
- Regularly update dependencies
- Enable safety monitoring features