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

pip install fastapi uvicorn

2. Configure Environment

Add to your .env file:

# 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

python3 run_web.py

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

Production Mode

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

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

Response:

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

Send Chat Message

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:

{
  "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

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

Health Check

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:

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:

WEB_CORS_ORIGINS=["http://localhost:3000", "http://your-frontend.com"]

Rate limit errors

Problem: Getting 429 errors

Solution: Increase rate limit:

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

python3 run_web.py  # Already has reload=True

Check logs

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

Test with different users

Use different email addresses:

# 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.