loyal_companion/docs/WEB_QUICKSTART.md

# Web Platform Quick Start

## Prerequisites

- PostgreSQL database running
- Python 3.10+
- Environment configured (`.env` file)

---

## Installation

### 1. Install Web Dependencies

```bash
pip install fastapi uvicorn
```

### 2. Configure Environment

Add to your `.env` file:

```env
# Required
DATABASE_URL=postgresql://user:pass@localhost:5432/loyal_companion

# Web Platform
WEB_ENABLED=true
WEB_HOST=127.0.0.1
WEB_PORT=8080

# Optional
WEB_CORS_ORIGINS=["http://localhost:3000", "http://localhost:8080"]
WEB_RATE_LIMIT=60
```

---

## Running the Web Server

### Development Mode

```bash
python3 run_web.py
```

Server will start at: **http://127.0.0.1:8080**

### Production Mode

```bash
uvicorn loyal_companion.web:app \
  --host 0.0.0.0 \
  --port 8080 \
  --workers 4
```

---

## Using the Web UI

1. **Open browser:** Navigate to `http://localhost:8080`

2. **Enter email:** Type any email address (e.g., `you@example.com`)
   - For Phase 3, any valid email format works
   - No actual email is sent
   - Token is generated as `web:your@example.com`

3. **Start chatting:** Type a message and press Enter
   - Shift+Enter for new line
   - Conversation is saved automatically
   - Refresh page to load history

---

## API Usage

### Get Authentication Token

```bash
curl -X POST http://localhost:8080/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'
```

Response:
```json
{
  "message": "Token generated successfully...",
  "token": "web:test@example.com"
}
```

### Send Chat Message

```bash
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer web:test@example.com" \
  -d '{
    "session_id": "my_session",
    "message": "Hello, how are you?"
  }'
```

Response:
```json
{
  "response": "Hey there. I'm here. How are you doing?",
  "mood": {
    "label": "neutral",
    "valence": 0.0,
    "arousal": 0.0,
    "intensity": 0.3
  },
  "relationship": {
    "level": "stranger",
    "score": 5,
    "interactions_count": 1
  },
  "extracted_facts": []
}
```

### Get Conversation History

```bash
curl http://localhost:8080/api/sessions/my_session/history \
  -H "Authorization: Bearer web:test@example.com"
```

### Health Check

```bash
curl http://localhost:8080/api/health
```

---

## API Documentation

FastAPI automatically generates interactive API docs:

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

---

## Troubleshooting

### Server won't start

**Error:** `DATABASE_URL not configured`
- Make sure `.env` file exists with `DATABASE_URL`
- Check database is running: `psql $DATABASE_URL -c "SELECT 1"`

**Error:** `Address already in use`
- Port 8080 is already taken
- Change port: `WEB_PORT=8081`
- Or kill existing process: `lsof -ti:8080 | xargs kill`

### Can't access from other devices

**Problem:** Server only accessible on localhost

**Solution:** Change host to `0.0.0.0`:
```env
WEB_HOST=0.0.0.0
```

Then access via: `http://<your-ip>:8080`

### CORS errors in browser

**Problem:** Frontend at different origin can't access API

**Solution:** Add origin to CORS whitelist:
```env
WEB_CORS_ORIGINS=["http://localhost:3000", "http://your-frontend.com"]
```

### Rate limit errors

**Problem:** Getting 429 errors

**Solution:** Increase rate limit:
```env
WEB_RATE_LIMIT=120  # Requests per minute
```

---

## Architecture

```
Browser → FastAPI → ConversationGateway → Living AI → Database
```

**Intimacy Level:** HIGH (always)
- Deeper reflection
- Proactive follow-ups
- Fact extraction enabled
- Emotional naming encouraged

---

## Development Tips

### Auto-reload on code changes

```bash
python3 run_web.py  # Already has reload=True
```

### Check logs

```bash
# Console logs show all requests
# Look for:
# → POST /api/chat
# ← POST /api/chat [200] (1.23s)
```

### Test with different users

Use different email addresses:
```bash
# User 1
curl ... -H "Authorization: Bearer web:alice@example.com"

# User 2
curl ... -H "Authorization: Bearer web:bob@example.com"
```

Each gets separate conversations and relationships.

---

## Next Steps

- Deploy to production server
- Add HTTPS/TLS
- Implement proper JWT authentication
- Add WebSocket for real-time updates
- Build richer UI (markdown, images)
- Add account linking with Discord

---

**The Web platform is ready!** 🌐

Visit http://localhost:8080 and start chatting.