Spaces:
Configuration error
Configuration error
Upload 16 files
Browse files- .dockerignore +53 -0
- .env.example +23 -0
- .gitignore +74 -0
- Dockerfile +38 -0
- Procfile +1 -0
- README.md +242 -7
- __init__.py +1 -0
- app.py +118 -0
- cascade_config.py +48 -0
- docker-compose.yml +58 -0
- image_gen.py +47 -0
- lore_generator.py +105 -0
- memory_manager.py +31 -0
- nlp_extractor.py +62 -0
- railway-config.json +13 -0
- requirements.txt +18 -0
.dockerignore
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Python
|
| 2 |
+
__pycache__/
|
| 3 |
+
*.py[cod]
|
| 4 |
+
*$py.class
|
| 5 |
+
*.so
|
| 6 |
+
.Python
|
| 7 |
+
venv/
|
| 8 |
+
env/
|
| 9 |
+
ENV/
|
| 10 |
+
.venv
|
| 11 |
+
|
| 12 |
+
# Environment
|
| 13 |
+
.env
|
| 14 |
+
.env.local
|
| 15 |
+
|
| 16 |
+
# IDE
|
| 17 |
+
.vscode/
|
| 18 |
+
.idea/
|
| 19 |
+
*.swp
|
| 20 |
+
*.swo
|
| 21 |
+
*~
|
| 22 |
+
|
| 23 |
+
# OS
|
| 24 |
+
.DS_Store
|
| 25 |
+
Thumbs.db
|
| 26 |
+
|
| 27 |
+
# Testing
|
| 28 |
+
.pytest_cache/
|
| 29 |
+
.coverage
|
| 30 |
+
htmlcov/
|
| 31 |
+
|
| 32 |
+
# Build
|
| 33 |
+
dist/
|
| 34 |
+
build/
|
| 35 |
+
*.egg-info/
|
| 36 |
+
|
| 37 |
+
# Logs
|
| 38 |
+
*.log
|
| 39 |
+
|
| 40 |
+
# Documentation
|
| 41 |
+
README.md
|
| 42 |
+
DESIGN.md
|
| 43 |
+
Documentation.txt
|
| 44 |
+
|
| 45 |
+
# Git
|
| 46 |
+
.git/
|
| 47 |
+
.gitignore
|
| 48 |
+
|
| 49 |
+
# Deployment configs (already in image)
|
| 50 |
+
docker-compose.yml
|
| 51 |
+
nginx.conf
|
| 52 |
+
deploy.sh
|
| 53 |
+
health_check.py
|
.env.example
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# -- Google AI (Fallback Engine) --------------------------------
|
| 2 |
+
# Get your key from: https://aistudio.google.com/app/apikey
|
| 3 |
+
GOOGLE_API_KEY=your_google_api_key_here
|
| 4 |
+
|
| 5 |
+
# -- Groq API (Primary LLM Engine) -------------------------------
|
| 6 |
+
# Get your key from: https://console.groq.com/keys
|
| 7 |
+
GROQ_API_KEY=your_groq_api_key_here
|
| 8 |
+
|
| 9 |
+
# -- Hugging Face (Optional - for local FLUX.1 models) -----------
|
| 10 |
+
# Get your token from: https://huggingface.co/settings/tokens
|
| 11 |
+
# Note: Current implementation uses Pollinations AI (no auth needed)
|
| 12 |
+
HF_TOKEN=your_huggingface_token_here
|
| 13 |
+
|
| 14 |
+
# -- Server Configuration ----------------------------------------
|
| 15 |
+
HOST=0.0.0.0
|
| 16 |
+
PORT=8000
|
| 17 |
+
|
| 18 |
+
# -- Optional: Production Settings -------------------------------
|
| 19 |
+
# ENVIRONMENT=production
|
| 20 |
+
# LOG_LEVEL=info
|
| 21 |
+
# WORKERS=4
|
| 22 |
+
# MAX_REQUESTS=1000
|
| 23 |
+
# TIMEOUT=60
|
.gitignore
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Environment variables
|
| 2 |
+
.env
|
| 3 |
+
|
| 4 |
+
# Python
|
| 5 |
+
__pycache__/
|
| 6 |
+
*.py[cod]
|
| 7 |
+
*$py.class
|
| 8 |
+
*.so
|
| 9 |
+
.Python
|
| 10 |
+
build/
|
| 11 |
+
develop-eggs/
|
| 12 |
+
dist/
|
| 13 |
+
downloads/
|
| 14 |
+
eggs/
|
| 15 |
+
.eggs/
|
| 16 |
+
lib/
|
| 17 |
+
lib64/
|
| 18 |
+
parts/
|
| 19 |
+
sdist/
|
| 20 |
+
var/
|
| 21 |
+
wheels/
|
| 22 |
+
*.egg-info/
|
| 23 |
+
.installed.cfg
|
| 24 |
+
*.egg
|
| 25 |
+
|
| 26 |
+
# Virtual environments
|
| 27 |
+
venv/
|
| 28 |
+
env/
|
| 29 |
+
ENV/
|
| 30 |
+
.venv
|
| 31 |
+
|
| 32 |
+
# IDE
|
| 33 |
+
.vscode/
|
| 34 |
+
.idea/
|
| 35 |
+
*.swp
|
| 36 |
+
*.swo
|
| 37 |
+
*~
|
| 38 |
+
|
| 39 |
+
# OS
|
| 40 |
+
.DS_Store
|
| 41 |
+
Thumbs.db
|
| 42 |
+
.DS_Store?
|
| 43 |
+
._*
|
| 44 |
+
.Spotlight-V100
|
| 45 |
+
.Trashes
|
| 46 |
+
ehthumbs.db
|
| 47 |
+
|
| 48 |
+
# Testing
|
| 49 |
+
.pytest_cache/
|
| 50 |
+
.coverage
|
| 51 |
+
.coverage.*
|
| 52 |
+
htmlcov/
|
| 53 |
+
.tox/
|
| 54 |
+
.hypothesis/
|
| 55 |
+
|
| 56 |
+
# Logs
|
| 57 |
+
*.log
|
| 58 |
+
logs/
|
| 59 |
+
|
| 60 |
+
# Database
|
| 61 |
+
*.db
|
| 62 |
+
*.sqlite3
|
| 63 |
+
|
| 64 |
+
# Backup files
|
| 65 |
+
*.bak
|
| 66 |
+
*.backup
|
| 67 |
+
|
| 68 |
+
# Temporary files
|
| 69 |
+
*.tmp
|
| 70 |
+
temp/
|
| 71 |
+
tmp/
|
| 72 |
+
|
| 73 |
+
# Data directory
|
| 74 |
+
data/
|
Dockerfile
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Living Lore Board Backend - Production Dockerfile
|
| 2 |
+
FROM python:3.11-slim
|
| 3 |
+
|
| 4 |
+
# Set working directory
|
| 5 |
+
WORKDIR /app
|
| 6 |
+
|
| 7 |
+
# Install system dependencies
|
| 8 |
+
RUN apt-get update && apt-get install -y \
|
| 9 |
+
build-essential \
|
| 10 |
+
curl \
|
| 11 |
+
&& rm -rf /var/lib/apt/lists/*
|
| 12 |
+
|
| 13 |
+
# Copy requirements first for better caching
|
| 14 |
+
COPY requirements.txt .
|
| 15 |
+
|
| 16 |
+
# Install Python dependencies
|
| 17 |
+
RUN pip install --no-cache-dir --upgrade pip && \
|
| 18 |
+
pip install --no-cache-dir -r requirements.txt
|
| 19 |
+
|
| 20 |
+
# Copy application code
|
| 21 |
+
COPY app.py .
|
| 22 |
+
COPY agents/ ./agents/
|
| 23 |
+
COPY ml_pipeline/ ./ml_pipeline/
|
| 24 |
+
|
| 25 |
+
# Create non-root user for security
|
| 26 |
+
RUN useradd -m -u 1000 appuser && \
|
| 27 |
+
chown -R appuser:appuser /app
|
| 28 |
+
USER appuser
|
| 29 |
+
|
| 30 |
+
# Expose port
|
| 31 |
+
EXPOSE 8000
|
| 32 |
+
|
| 33 |
+
# Health check
|
| 34 |
+
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
|
| 35 |
+
CMD curl -f http://localhost:8000/health || exit 1
|
| 36 |
+
|
| 37 |
+
# Run the application with uvicorn
|
| 38 |
+
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
|
Procfile
ADDED
|
@@ -0,0 +1 @@
|
|
|
|
|
|
|
| 1 |
+
web: uvicorn app:app --host 0.0.0.0 --port $PORT --workers 4
|
README.md
CHANGED
|
@@ -1,10 +1,245 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
---
|
| 2 |
-
|
| 3 |
-
|
| 4 |
-
|
| 5 |
-
|
| 6 |
-
|
| 7 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8 |
---
|
| 9 |
|
| 10 |
-
|
|
|
|
|
|
| 1 |
+
# Living Lore Board - Backend Deployment Guide
|
| 2 |
+
|
| 3 |
+
## 📦 Deployment Package Contents
|
| 4 |
+
|
| 5 |
+
This folder contains all files necessary to deploy the Living Lore Board backend to production.
|
| 6 |
+
|
| 7 |
+
### Files Included:
|
| 8 |
+
- `app.py` - Main FastAPI application entry point
|
| 9 |
+
- `requirements.txt` - Python dependencies
|
| 10 |
+
- `.env.example` - Environment variable template (copy to `.env` and fill in)
|
| 11 |
+
- `agents/` - LangChain agent modules (lore generation, memory management)
|
| 12 |
+
- `ml_pipeline/` - ML components (image generation, NLP extraction)
|
| 13 |
+
- `Dockerfile` - Container configuration for deployment
|
| 14 |
+
- `docker-compose.yml` - Multi-container orchestration (optional)
|
| 15 |
+
- `railway.json` - Railway.app deployment configuration
|
| 16 |
+
- `render.yaml` - Render.com deployment configuration
|
| 17 |
+
- `vercel.json` - Vercel deployment configuration
|
| 18 |
+
- `Procfile` - Heroku/generic PaaS configuration
|
| 19 |
+
- `gunicorn.conf.py` - Production WSGI server configuration
|
| 20 |
+
- `nginx.conf` - Nginx reverse proxy configuration (for VPS deployment)
|
| 21 |
+
- `deploy.sh` - Automated deployment script
|
| 22 |
+
- `health_check.py` - Health monitoring script
|
| 23 |
+
|
| 24 |
+
---
|
| 25 |
+
|
| 26 |
+
## 🚀 Deployment Options
|
| 27 |
+
|
| 28 |
+
### Option 1: Railway.app (Recommended - Easy & Free Tier)
|
| 29 |
+
|
| 30 |
+
1. Install Railway CLI:
|
| 31 |
+
```bash
|
| 32 |
+
npm install -g @railway/cli
|
| 33 |
+
```
|
| 34 |
+
|
| 35 |
+
2. Login and initialize:
|
| 36 |
+
```bash
|
| 37 |
+
railway login
|
| 38 |
+
railway init
|
| 39 |
+
```
|
| 40 |
+
|
| 41 |
+
3. Set environment variables:
|
| 42 |
+
```bash
|
| 43 |
+
railway variables set GROQ_API_KEY=your_key_here
|
| 44 |
+
railway variables set GOOGLE_API_KEY=your_key_here
|
| 45 |
+
railway variables set HF_TOKEN=your_token_here
|
| 46 |
+
railway variables set HOST=0.0.0.0
|
| 47 |
+
railway variables set PORT=8000
|
| 48 |
+
```
|
| 49 |
+
|
| 50 |
+
4. Deploy:
|
| 51 |
+
```bash
|
| 52 |
+
railway up
|
| 53 |
+
```
|
| 54 |
+
|
| 55 |
+
### Option 2: Render.com (Simple with Auto-Deploy)
|
| 56 |
+
|
| 57 |
+
1. Create a new Web Service on Render.com
|
| 58 |
+
2. Connect your GitHub repository
|
| 59 |
+
3. Set Build Command: `pip install -r requirements.txt`
|
| 60 |
+
4. Set Start Command: `uvicorn app:app --host 0.0.0.0 --port $PORT`
|
| 61 |
+
5. Add environment variables in the Render dashboard
|
| 62 |
+
6. Deploy automatically on git push
|
| 63 |
+
|
| 64 |
+
### Option 3: Docker (Any Cloud Provider)
|
| 65 |
+
|
| 66 |
+
1. Build the image:
|
| 67 |
+
```bash
|
| 68 |
+
docker build -t living-lore-backend .
|
| 69 |
+
```
|
| 70 |
+
|
| 71 |
+
2. Run the container:
|
| 72 |
+
```bash
|
| 73 |
+
docker run -p 8000:8000 --env-file .env living-lore-backend
|
| 74 |
+
```
|
| 75 |
+
|
| 76 |
+
3. Or use docker-compose:
|
| 77 |
+
```bash
|
| 78 |
+
docker-compose up -d
|
| 79 |
+
```
|
| 80 |
+
|
| 81 |
+
### Option 4: VPS (DigitalOcean, AWS EC2, etc.)
|
| 82 |
+
|
| 83 |
+
1. SSH into your server
|
| 84 |
+
2. Clone/upload this folder
|
| 85 |
+
3. Install dependencies:
|
| 86 |
+
```bash
|
| 87 |
+
python3 -m venv venv
|
| 88 |
+
source venv/bin/activate
|
| 89 |
+
pip install -r requirements.txt
|
| 90 |
+
```
|
| 91 |
+
|
| 92 |
+
4. Set up environment variables:
|
| 93 |
+
```bash
|
| 94 |
+
cp .env.example .env
|
| 95 |
+
nano .env # Edit with your keys
|
| 96 |
+
```
|
| 97 |
+
|
| 98 |
+
5. Run with systemd (production):
|
| 99 |
+
```bash
|
| 100 |
+
sudo cp living-lore-backend.service /etc/systemd/system/
|
| 101 |
+
sudo systemctl daemon-reload
|
| 102 |
+
sudo systemctl enable living-lore-backend
|
| 103 |
+
sudo systemctl start living-lore-backend
|
| 104 |
+
```
|
| 105 |
+
|
| 106 |
+
6. Configure Nginx as reverse proxy:
|
| 107 |
+
```bash
|
| 108 |
+
sudo cp nginx.conf /etc/nginx/sites-available/living-lore-backend
|
| 109 |
+
sudo ln -s /etc/nginx/sites-available/living-lore-backend /etc/nginx/sites-enabled/
|
| 110 |
+
sudo nginx -t
|
| 111 |
+
sudo systemctl restart nginx
|
| 112 |
+
```
|
| 113 |
+
|
| 114 |
+
### Option 5: Vercel (Serverless)
|
| 115 |
+
|
| 116 |
+
1. Install Vercel CLI:
|
| 117 |
+
```bash
|
| 118 |
+
npm install -g vercel
|
| 119 |
+
```
|
| 120 |
+
|
| 121 |
+
2. Deploy:
|
| 122 |
+
```bash
|
| 123 |
+
vercel
|
| 124 |
+
```
|
| 125 |
+
|
| 126 |
+
3. Add environment variables via Vercel dashboard
|
| 127 |
+
|
| 128 |
+
---
|
| 129 |
+
|
| 130 |
+
## 🔐 Environment Variables Required
|
| 131 |
+
|
| 132 |
+
Copy `.env.example` to `.env` and fill in these values:
|
| 133 |
+
|
| 134 |
+
```env
|
| 135 |
+
# Groq API (Primary LLM Engine)
|
| 136 |
+
GROQ_API_KEY=your_groq_api_key
|
| 137 |
+
|
| 138 |
+
# Google Gemini API (Fallback)
|
| 139 |
+
GOOGLE_API_KEY=your_google_api_key
|
| 140 |
+
|
| 141 |
+
# Hugging Face Token (for image generation models)
|
| 142 |
+
HF_TOKEN=your_huggingface_token
|
| 143 |
+
|
| 144 |
+
# Server Configuration
|
| 145 |
+
HOST=0.0.0.0
|
| 146 |
+
PORT=8000
|
| 147 |
+
```
|
| 148 |
+
|
| 149 |
+
### Getting API Keys:
|
| 150 |
+
|
| 151 |
+
1. **Groq API Key**: https://console.groq.com/keys
|
| 152 |
+
2. **Google Gemini API**: https://aistudio.google.com/app/apikey
|
| 153 |
+
3. **Hugging Face Token**: https://huggingface.co/settings/tokens
|
| 154 |
+
|
| 155 |
+
---
|
| 156 |
+
|
| 157 |
+
## 📋 Pre-Deployment Checklist
|
| 158 |
+
|
| 159 |
+
- [ ] All environment variables set
|
| 160 |
+
- [ ] Dependencies installed and tested locally
|
| 161 |
+
- [ ] API keys are valid and have quota
|
| 162 |
+
- [ ] CORS origins updated for production domain
|
| 163 |
+
- [ ] Health endpoint (`/health`) returns 200 OK
|
| 164 |
+
- [ ] Test all three endpoints:
|
| 165 |
+
- POST `/generate-lore`
|
| 166 |
+
- POST `/generate-avatar`
|
| 167 |
+
- POST `/extract-entities`
|
| 168 |
+
|
| 169 |
+
---
|
| 170 |
+
|
| 171 |
+
## 🔍 Health Monitoring
|
| 172 |
+
|
| 173 |
+
After deployment, monitor your service:
|
| 174 |
+
|
| 175 |
+
```bash
|
| 176 |
+
# Check health endpoint
|
| 177 |
+
curl https://your-domain.com/health
|
| 178 |
+
|
| 179 |
+
# Run health check script
|
| 180 |
+
python health_check.py https://your-domain.com
|
| 181 |
+
```
|
| 182 |
+
|
| 183 |
---
|
| 184 |
+
|
| 185 |
+
## 🐛 Troubleshooting
|
| 186 |
+
|
| 187 |
+
### Issue: Port already in use
|
| 188 |
+
**Solution**: Change PORT in .env or kill existing process
|
| 189 |
+
|
| 190 |
+
### Issue: Import errors
|
| 191 |
+
**Solution**: Ensure all dependencies in requirements.txt are installed
|
| 192 |
+
|
| 193 |
+
### Issue: API key errors
|
| 194 |
+
**Solution**: Verify keys are set correctly in environment variables
|
| 195 |
+
|
| 196 |
+
### Issue: CORS errors
|
| 197 |
+
**Solution**: Update `origins` list in `app.py` to include your frontend domain
|
| 198 |
+
|
| 199 |
+
### Issue: Image generation fails
|
| 200 |
+
**Solution**: Uses Pollinations AI (free, no auth), should work by default
|
| 201 |
+
|
| 202 |
+
---
|
| 203 |
+
|
| 204 |
+
## 📊 Performance Considerations
|
| 205 |
+
|
| 206 |
+
- **Memory**: Minimum 512MB RAM recommended
|
| 207 |
+
- **CPU**: 1 vCPU sufficient for light traffic
|
| 208 |
+
- **Storage**: ~500MB for dependencies
|
| 209 |
+
- **Network**: Image generation requires stable internet
|
| 210 |
+
|
| 211 |
+
---
|
| 212 |
+
|
| 213 |
+
## 🔒 Security Best Practices
|
| 214 |
+
|
| 215 |
+
1. Never commit `.env` file to version control
|
| 216 |
+
2. Use secrets management for production (AWS Secrets Manager, Railway Variables, etc.)
|
| 217 |
+
3. Enable HTTPS/SSL certificates (Let's Encrypt recommended)
|
| 218 |
+
4. Implement rate limiting for API endpoints
|
| 219 |
+
5. Set up monitoring and alerting
|
| 220 |
+
6. Regular dependency updates: `pip install --upgrade -r requirements.txt`
|
| 221 |
+
|
| 222 |
+
---
|
| 223 |
+
|
| 224 |
+
## 📈 Scaling Recommendations
|
| 225 |
+
|
| 226 |
+
For high traffic:
|
| 227 |
+
1. Use a production WSGI server (Gunicorn with workers)
|
| 228 |
+
2. Implement Redis caching for repeated lore generations
|
| 229 |
+
3. Consider CDN for generated images
|
| 230 |
+
4. Set up load balancing with multiple instances
|
| 231 |
+
5. Database integration for persistent memory (currently in-memory)
|
| 232 |
+
|
| 233 |
+
---
|
| 234 |
+
|
| 235 |
+
## 📞 Support
|
| 236 |
+
|
| 237 |
+
For issues or questions:
|
| 238 |
+
- Check logs: `railway logs` or `docker logs living-lore-backend`
|
| 239 |
+
- Review API documentation at `/docs` endpoint (FastAPI auto-generates Swagger UI)
|
| 240 |
+
- Test endpoints individually with Postman or curl
|
| 241 |
+
|
| 242 |
---
|
| 243 |
|
| 244 |
+
**Last Updated**: 2026-07-18
|
| 245 |
+
**Backend Version**: 0.1.0
|
__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
|
|
|
|
| 1 |
+
|
app.py
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
Living Lore Board – FastAPI entry point.
|
| 3 |
+
|
| 4 |
+
Routes:
|
| 5 |
+
POST /generate-lore → LangChain + Gemini lore generation
|
| 6 |
+
POST /generate-avatar → FLUX.1 text-to-image avatar
|
| 7 |
+
POST /extract-entities → BERT NER entity extraction
|
| 8 |
+
"""
|
| 9 |
+
from __future__ import annotations
|
| 10 |
+
|
| 11 |
+
import os
|
| 12 |
+
from dotenv import load_dotenv
|
| 13 |
+
|
| 14 |
+
load_dotenv()
|
| 15 |
+
|
| 16 |
+
from fastapi import FastAPI
|
| 17 |
+
from fastapi.middleware.cors import CORSMiddleware
|
| 18 |
+
from pydantic import BaseModel, Field, field_validator
|
| 19 |
+
|
| 20 |
+
from agents.lore_generator import generate_lore
|
| 21 |
+
from ml_pipeline.image_gen import generate_avatar
|
| 22 |
+
from ml_pipeline.nlp_extractor import extract_entities
|
| 23 |
+
|
| 24 |
+
app = FastAPI(title="Living Lore Board API", version="0.1.0")
|
| 25 |
+
|
| 26 |
+
# Allow the Vite dev server to call the API during development
|
| 27 |
+
origins = [
|
| 28 |
+
"http://localhost:8080",
|
| 29 |
+
"http://127.0.0.1:8080",
|
| 30 |
+
"http://localhost:5173",
|
| 31 |
+
"http://127.0.0.1:5173",
|
| 32 |
+
"http://localhost:3000",
|
| 33 |
+
]
|
| 34 |
+
|
| 35 |
+
app.add_middleware(
|
| 36 |
+
CORSMiddleware,
|
| 37 |
+
allow_origins=origins,
|
| 38 |
+
allow_credentials=True,
|
| 39 |
+
allow_methods=["*"],
|
| 40 |
+
allow_headers=["*"],
|
| 41 |
+
)
|
| 42 |
+
|
| 43 |
+
|
| 44 |
+
# ── Request / Response Models ──────────────────────────────
|
| 45 |
+
|
| 46 |
+
class NodeRef(BaseModel):
|
| 47 |
+
name: str
|
| 48 |
+
type: str
|
| 49 |
+
|
| 50 |
+
|
| 51 |
+
class LoreRequest(BaseModel):
|
| 52 |
+
nodes: list[NodeRef] = Field(..., description="List of 2 to 6 nodes to connect.")
|
| 53 |
+
|
| 54 |
+
@field_validator("nodes")
|
| 55 |
+
@classmethod
|
| 56 |
+
def validate_node_count(cls, v: list[NodeRef]) -> list[NodeRef]:
|
| 57 |
+
if len(v) < 2:
|
| 58 |
+
raise ValueError("You must select at least 2 nodes to generate lore.")
|
| 59 |
+
if len(v) > 6:
|
| 60 |
+
raise ValueError("You cannot connect more than 6 nodes at once.")
|
| 61 |
+
return v
|
| 62 |
+
|
| 63 |
+
|
| 64 |
+
class LoreResponse(BaseModel):
|
| 65 |
+
lore: str
|
| 66 |
+
|
| 67 |
+
|
| 68 |
+
class AvatarRequest(BaseModel):
|
| 69 |
+
name: str
|
| 70 |
+
type: str
|
| 71 |
+
description: str
|
| 72 |
+
|
| 73 |
+
|
| 74 |
+
class AvatarResponse(BaseModel):
|
| 75 |
+
image_url: str
|
| 76 |
+
|
| 77 |
+
|
| 78 |
+
class ExtractRequest(BaseModel):
|
| 79 |
+
text: str
|
| 80 |
+
|
| 81 |
+
|
| 82 |
+
class EntityItem(BaseModel):
|
| 83 |
+
name: str
|
| 84 |
+
type: str
|
| 85 |
+
|
| 86 |
+
|
| 87 |
+
class ExtractResponse(BaseModel):
|
| 88 |
+
entities: list[EntityItem]
|
| 89 |
+
|
| 90 |
+
|
| 91 |
+
# ── Routes ─────────────────────────────────────────────────
|
| 92 |
+
|
| 93 |
+
@app.post("/generate-lore", response_model=LoreResponse)
|
| 94 |
+
async def lore_endpoint(req: LoreRequest):
|
| 95 |
+
lore = await generate_lore(req.nodes)
|
| 96 |
+
return LoreResponse(lore=lore)
|
| 97 |
+
|
| 98 |
+
|
| 99 |
+
@app.post("/generate-avatar", response_model=AvatarResponse)
|
| 100 |
+
async def avatar_endpoint(req: AvatarRequest):
|
| 101 |
+
url = await generate_avatar(req.name, req.type, req.description)
|
| 102 |
+
return AvatarResponse(image_url=url)
|
| 103 |
+
|
| 104 |
+
|
| 105 |
+
@app.post("/extract-entities", response_model=ExtractResponse)
|
| 106 |
+
async def extract_endpoint(req: ExtractRequest):
|
| 107 |
+
entities = await extract_entities(req.text)
|
| 108 |
+
return ExtractResponse(entities=[EntityItem(**e) for e in entities])
|
| 109 |
+
|
| 110 |
+
|
| 111 |
+
@app.get("/health")
|
| 112 |
+
async def health():
|
| 113 |
+
return {"status": "ok"}
|
| 114 |
+
|
| 115 |
+
|
| 116 |
+
if __name__ == "__main__":
|
| 117 |
+
import uvicorn
|
| 118 |
+
uvicorn.run("app:app", host=os.getenv("HOST", "0.0.0.0"), port=int(os.getenv("PORT", 8000)), reload=True)
|
cascade_config.py
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
CascadeFlow Configuration – Agent Governance
|
| 3 |
+
|
| 4 |
+
Monitors per-session call count, estimated token cost, and latency budgets.
|
| 5 |
+
Raises RuntimeError if constraints are exceeded so the agent loop can surface
|
| 6 |
+
a graceful error rather than silently over-spending.
|
| 7 |
+
"""
|
| 8 |
+
from __future__ import annotations
|
| 9 |
+
|
| 10 |
+
import time
|
| 11 |
+
from dataclasses import dataclass, field
|
| 12 |
+
|
| 13 |
+
try:
|
| 14 |
+
from cascadeflow import CascadeMonitor
|
| 15 |
+
|
| 16 |
+
_monitor = CascadeMonitor(
|
| 17 |
+
max_calls_per_session=50,
|
| 18 |
+
max_latency_ms=8000,
|
| 19 |
+
cost_per_call_usd=0.0, # Gemini 1.5 Flash free-tier
|
| 20 |
+
)
|
| 21 |
+
|
| 22 |
+
def check_constraints() -> None:
|
| 23 |
+
"""Raise RuntimeError if any governance constraint is violated."""
|
| 24 |
+
_monitor.check()
|
| 25 |
+
|
| 26 |
+
def record_call() -> None:
|
| 27 |
+
"""Notify cascadeflow that one LLM call has completed."""
|
| 28 |
+
_monitor.record()
|
| 29 |
+
|
| 30 |
+
except ImportError:
|
| 31 |
+
# Graceful fallback: lightweight manual tracker
|
| 32 |
+
@dataclass
|
| 33 |
+
class _FallbackTracker:
|
| 34 |
+
max_calls: int = 50
|
| 35 |
+
calls: int = 0
|
| 36 |
+
_start: float = field(default_factory=time.monotonic)
|
| 37 |
+
|
| 38 |
+
_tracker = _FallbackTracker()
|
| 39 |
+
|
| 40 |
+
def check_constraints() -> None: # type: ignore[misc]
|
| 41 |
+
if _tracker.calls >= _tracker.max_calls:
|
| 42 |
+
raise RuntimeError(
|
| 43 |
+
f"Session limit reached: {_tracker.max_calls} calls. "
|
| 44 |
+
"Please start a new session."
|
| 45 |
+
)
|
| 46 |
+
|
| 47 |
+
def record_call() -> None: # type: ignore[misc]
|
| 48 |
+
_tracker.calls += 1
|
docker-compose.yml
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
version: '3.8'
|
| 2 |
+
|
| 3 |
+
services:
|
| 4 |
+
backend:
|
| 5 |
+
build: .
|
| 6 |
+
container_name: living-lore-backend
|
| 7 |
+
ports:
|
| 8 |
+
- "8000:8000"
|
| 9 |
+
env_file:
|
| 10 |
+
- .env
|
| 11 |
+
environment:
|
| 12 |
+
- HOST=0.0.0.0
|
| 13 |
+
- PORT=8000
|
| 14 |
+
restart: unless-stopped
|
| 15 |
+
healthcheck:
|
| 16 |
+
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
|
| 17 |
+
interval: 30s
|
| 18 |
+
timeout: 10s
|
| 19 |
+
retries: 3
|
| 20 |
+
start_period: 40s
|
| 21 |
+
volumes:
|
| 22 |
+
# Optional: mount for persistent data if needed
|
| 23 |
+
- ./data:/app/data
|
| 24 |
+
networks:
|
| 25 |
+
- living-lore-network
|
| 26 |
+
|
| 27 |
+
# Optional: Redis for caching (uncomment if needed)
|
| 28 |
+
# redis:
|
| 29 |
+
# image: redis:7-alpine
|
| 30 |
+
# container_name: living-lore-redis
|
| 31 |
+
# ports:
|
| 32 |
+
# - "6379:6379"
|
| 33 |
+
# restart: unless-stopped
|
| 34 |
+
# networks:
|
| 35 |
+
# - living-lore-network
|
| 36 |
+
|
| 37 |
+
# Optional: Nginx reverse proxy (uncomment for production)
|
| 38 |
+
# nginx:
|
| 39 |
+
# image: nginx:alpine
|
| 40 |
+
# container_name: living-lore-nginx
|
| 41 |
+
# ports:
|
| 42 |
+
# - "80:80"
|
| 43 |
+
# - "443:443"
|
| 44 |
+
# volumes:
|
| 45 |
+
# - ./nginx.conf:/etc/nginx/nginx.conf:ro
|
| 46 |
+
# - ./ssl:/etc/nginx/ssl:ro
|
| 47 |
+
# depends_on:
|
| 48 |
+
# - backend
|
| 49 |
+
# restart: unless-stopped
|
| 50 |
+
# networks:
|
| 51 |
+
# - living-lore-network
|
| 52 |
+
|
| 53 |
+
networks:
|
| 54 |
+
living-lore-network:
|
| 55 |
+
driver: bridge
|
| 56 |
+
|
| 57 |
+
volumes:
|
| 58 |
+
data:
|
image_gen.py
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
import urllib.parse
|
| 2 |
+
import requests
|
| 3 |
+
import base64
|
| 4 |
+
import asyncio
|
| 5 |
+
from fastapi import HTTPException
|
| 6 |
+
|
| 7 |
+
async def generate_avatar(character_name: str, entity_type: str, description: str) -> str:
|
| 8 |
+
# 1. Build the prompt
|
| 9 |
+
prompt = (
|
| 10 |
+
f"A stunning fantasy digital art portrait of {character_name}. "
|
| 11 |
+
f"They are a {entity_type}. "
|
| 12 |
+
f"Distinctive features: {description}. "
|
| 13 |
+
"Highly detailed, cinematic lighting, concept art style, centered, dark background, no text."
|
| 14 |
+
)
|
| 15 |
+
|
| 16 |
+
# 2. Safely encode the text so it can be sent inside a URL
|
| 17 |
+
safe_prompt = urllib.parse.quote(prompt)
|
| 18 |
+
|
| 19 |
+
# 3. Use Pollinations AI (Free, No Auth, FLUX model under the hood)
|
| 20 |
+
# We add width, height, and nologo=true to keep the image clean
|
| 21 |
+
url = f"https://image.pollinations.ai/prompt/{safe_prompt}?width=512&height=512&nologo=true"
|
| 22 |
+
|
| 23 |
+
def _fetch_image():
|
| 24 |
+
# Notice this is a simple GET request now, no headers or tokens needed!
|
| 25 |
+
response = requests.get(url)
|
| 26 |
+
if response.status_code != 200:
|
| 27 |
+
raise Exception(f"API Error: {response.status_code}")
|
| 28 |
+
return response.content
|
| 29 |
+
|
| 30 |
+
try:
|
| 31 |
+
print("\n--- FETCHING FROM POLLINATIONS AI ---")
|
| 32 |
+
print(f"Bypassing Hugging Face...")
|
| 33 |
+
|
| 34 |
+
image_bytes = await asyncio.to_thread(_fetch_image)
|
| 35 |
+
|
| 36 |
+
# 4. Format for the React frontend
|
| 37 |
+
b64 = base64.b64encode(image_bytes).decode("utf-8")
|
| 38 |
+
print("Success! Image generated.")
|
| 39 |
+
print("-------------------------------------\n")
|
| 40 |
+
|
| 41 |
+
return f"data:image/jpeg;base64,{b64}"
|
| 42 |
+
|
| 43 |
+
except Exception as e:
|
| 44 |
+
print(f"\n--- API ERROR ---")
|
| 45 |
+
print(str(e))
|
| 46 |
+
print(f"-----------------\n")
|
| 47 |
+
raise HTTPException(status_code=500, detail=str(e))
|
lore_generator.py
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
Lore Generator – LangChain + Groq (llama3-70b-8192) with Gemini fallback
|
| 3 |
+
|
| 4 |
+
Accepts a list of 2–6 NodeRef objects and weaves them into a single lore narrative.
|
| 5 |
+
|
| 6 |
+
Orchestration order:
|
| 7 |
+
1. cascade_config → verify budget & latency constraints
|
| 8 |
+
2. memory_manager → recall any prior lore for this entity group
|
| 9 |
+
3. Groq Llama 3 70B → generate new lore (ultra-fast via Groq API)
|
| 10 |
+
4. memory_manager → retain the generated lore
|
| 11 |
+
"""
|
| 12 |
+
from __future__ import annotations
|
| 13 |
+
|
| 14 |
+
import os
|
| 15 |
+
from typing import TYPE_CHECKING
|
| 16 |
+
|
| 17 |
+
from langchain_groq import ChatGroq
|
| 18 |
+
from langchain_google_genai import ChatGoogleGenerativeAI # Kept for future fallback!
|
| 19 |
+
from langchain_core.prompts import PromptTemplate
|
| 20 |
+
from fastapi import HTTPException
|
| 21 |
+
|
| 22 |
+
from agents.cascade_config import check_constraints, record_call
|
| 23 |
+
from agents.memory_manager import recall, retain
|
| 24 |
+
|
| 25 |
+
if TYPE_CHECKING:
|
| 26 |
+
# NodeRef is a Pydantic model defined in app.py; imported only for type hints
|
| 27 |
+
# to avoid a circular import at runtime.
|
| 28 |
+
from app import NodeRef
|
| 29 |
+
|
| 30 |
+
|
| 31 |
+
async def generate_lore(nodes: list) -> str:
|
| 32 |
+
"""Generate lore that weaves together all supplied nodes (2–6 entities).
|
| 33 |
+
|
| 34 |
+
Args:
|
| 35 |
+
nodes: list of NodeRef-like objects with `.name` and `.type` attributes.
|
| 36 |
+
"""
|
| 37 |
+
# 1. Load keys (Keeping both in the codebase as requested)
|
| 38 |
+
groq_key = os.getenv("GROQ_API_KEY")
|
| 39 |
+
google_key = os.getenv("GOOGLE_API_KEY") # Kept for fallback
|
| 40 |
+
|
| 41 |
+
if not groq_key:
|
| 42 |
+
raise HTTPException(status_code=500, detail="Groq API Key missing in .env file.")
|
| 43 |
+
|
| 44 |
+
# 2. Governance check
|
| 45 |
+
check_constraints()
|
| 46 |
+
|
| 47 |
+
# 3. Build a stable memory key from all node names (sorted for consistency)
|
| 48 |
+
sorted_names = sorted(n.name.lower() for n in nodes)
|
| 49 |
+
memory_key = "::".join(sorted_names)
|
| 50 |
+
prior = recall(memory_key)
|
| 51 |
+
memory_context = prior if prior else "No prior history recorded."
|
| 52 |
+
|
| 53 |
+
# 4. Dynamically format the entity list for the prompt
|
| 54 |
+
entities_text = "\n".join(
|
| 55 |
+
f"{i}. {node.name} (Type: {node.type})"
|
| 56 |
+
for i, node in enumerate(nodes, 1)
|
| 57 |
+
)
|
| 58 |
+
|
| 59 |
+
try:
|
| 60 |
+
print("\n--- GENERATING LORE WITH GROQ (Llama 3) ---")
|
| 61 |
+
|
| 62 |
+
# 5. Connect to Groq instead of Gemini
|
| 63 |
+
llm = ChatGroq(
|
| 64 |
+
model="openai/gpt-oss-120b", # Using the newer, more powerful 120B model
|
| 65 |
+
api_key=groq_key,
|
| 66 |
+
temperature=0.8
|
| 67 |
+
)
|
| 68 |
+
|
| 69 |
+
template = (
|
| 70 |
+
"You are a master fantasy worldbuilder. The user has selected a web of "
|
| 71 |
+
"interconnected entities from their world.\n\n"
|
| 72 |
+
"Entities to connect:\n{entity_list}\n\n"
|
| 73 |
+
"Prior context: {memory_context}\n\n"
|
| 74 |
+
"Write a cohesive, engaging, 3-paragraph piece of lore that organically "
|
| 75 |
+
"weaves all of these specific characters, locations, events, and organizations "
|
| 76 |
+
"together into a single narrative or historical record. Make it mysterious and "
|
| 77 |
+
"highly detailed. Ensure every entity listed above plays a meaningful role in "
|
| 78 |
+
"the story. Do not use markdown formatting."
|
| 79 |
+
)
|
| 80 |
+
|
| 81 |
+
prompt = PromptTemplate.from_template(template)
|
| 82 |
+
chain = prompt | llm
|
| 83 |
+
response = await chain.ainvoke({
|
| 84 |
+
"entity_list": entities_text,
|
| 85 |
+
"memory_context": memory_context,
|
| 86 |
+
})
|
| 87 |
+
|
| 88 |
+
lore = response.content
|
| 89 |
+
|
| 90 |
+
# 6. Persist to memory
|
| 91 |
+
retain(memory_key, lore)
|
| 92 |
+
|
| 93 |
+
# 7. Record usage for cascadeflow budget tracking
|
| 94 |
+
record_call()
|
| 95 |
+
|
| 96 |
+
print("Success! Lore generated instantly.")
|
| 97 |
+
print("-------------------------------------------\n")
|
| 98 |
+
|
| 99 |
+
return lore
|
| 100 |
+
|
| 101 |
+
except HTTPException:
|
| 102 |
+
raise
|
| 103 |
+
except Exception as e:
|
| 104 |
+
print(f"Groq API Error: {str(e)}")
|
| 105 |
+
raise HTTPException(status_code=500, detail="Failed to connect to Groq API.")
|
memory_manager.py
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""
|
| 2 |
+
Memory Manager – Hindsight integration
|
| 3 |
+
|
| 4 |
+
Uses Hindsight's retain/recall API to store and retrieve temporal lore facts
|
| 5 |
+
associated with pairs of entities (keyed as "entity_a::entity_b").
|
| 6 |
+
"""
|
| 7 |
+
from __future__ import annotations
|
| 8 |
+
|
| 9 |
+
try:
|
| 10 |
+
from hindsight import Memory
|
| 11 |
+
|
| 12 |
+
_mem = Memory()
|
| 13 |
+
|
| 14 |
+
def retain(key: str, value: str) -> None:
|
| 15 |
+
"""Store a lore fact under the given key."""
|
| 16 |
+
_mem.retain(key=key, value=value)
|
| 17 |
+
|
| 18 |
+
def recall(key: str) -> str | None:
|
| 19 |
+
"""Recall the most recent lore fact for the given key, or None."""
|
| 20 |
+
result = _mem.recall(key=key)
|
| 21 |
+
return result if result else None
|
| 22 |
+
|
| 23 |
+
except ImportError:
|
| 24 |
+
# Graceful fallback: in-process dictionary when Hindsight is unavailable
|
| 25 |
+
_store: dict[str, str] = {}
|
| 26 |
+
|
| 27 |
+
def retain(key: str, value: str) -> None: # type: ignore[misc]
|
| 28 |
+
_store[key] = value
|
| 29 |
+
|
| 30 |
+
def recall(key: str) -> str | None: # type: ignore[misc]
|
| 31 |
+
return _store.get(key)
|
nlp_extractor.py
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
import os
|
| 2 |
+
import json
|
| 3 |
+
import asyncio
|
| 4 |
+
from fastapi import HTTPException
|
| 5 |
+
from langchain_groq import ChatGroq
|
| 6 |
+
from langchain_google_genai import ChatGoogleGenerativeAI # Kept for future fallback!
|
| 7 |
+
from langchain_core.prompts import PromptTemplate
|
| 8 |
+
|
| 9 |
+
async def extract_entities(text: str) -> list[dict]:
|
| 10 |
+
# 1. Load keys (Keeping both in the codebase as requested)
|
| 11 |
+
groq_key = os.getenv("GROQ_API_KEY")
|
| 12 |
+
google_key = os.getenv("GOOGLE_API_KEY") # Kept for fallback
|
| 13 |
+
|
| 14 |
+
if not groq_key:
|
| 15 |
+
raise HTTPException(status_code=500, detail="Groq API Key missing in .env file.")
|
| 16 |
+
|
| 17 |
+
try:
|
| 18 |
+
print("\n--- EXTRACTING ENTITIES WITH GROQ ---")
|
| 19 |
+
|
| 20 |
+
# 2. Connect to Groq
|
| 21 |
+
llm = ChatGroq(
|
| 22 |
+
model="openai/gpt-oss-120b",
|
| 23 |
+
api_key=groq_key,
|
| 24 |
+
temperature=0.0 # Strict zero temperature for formatting consistency
|
| 25 |
+
)
|
| 26 |
+
|
| 27 |
+
# 3. Prompt tweaked to ensure strict JSON output for Llama 3
|
| 28 |
+
template = """
|
| 29 |
+
Analyze the following text and extract the key fantasy entities (characters, locations, events, or organizations).
|
| 30 |
+
|
| 31 |
+
CRITICAL INSTRUCTIONS:
|
| 32 |
+
1. Return the result ONLY as a valid JSON array of objects.
|
| 33 |
+
2. Absolutely NO conversational text, NO markdown formatting, and NO ```json blocks.
|
| 34 |
+
3. Each object must have exactly two keys: "name" (the entity name) and "type" (must be "character", "location", "event", or "organization").
|
| 35 |
+
|
| 36 |
+
Text: {text}
|
| 37 |
+
"""
|
| 38 |
+
prompt = PromptTemplate.from_template(template)
|
| 39 |
+
chain = prompt | llm
|
| 40 |
+
|
| 41 |
+
# 4. Get the response
|
| 42 |
+
response = await chain.ainvoke({"text": text})
|
| 43 |
+
|
| 44 |
+
# 5. Clean up in case Llama 3 disobeys the "no markdown" rule
|
| 45 |
+
raw_text = response.content.strip()
|
| 46 |
+
if raw_text.startswith("```json"):
|
| 47 |
+
raw_text = raw_text[7:-3].strip()
|
| 48 |
+
elif raw_text.startswith("```"):
|
| 49 |
+
raw_text = raw_text[3:-3].strip()
|
| 50 |
+
|
| 51 |
+
entities = json.loads(raw_text)
|
| 52 |
+
print(f"Success! Found {len(entities)} entities.")
|
| 53 |
+
print("-------------------------------------\n")
|
| 54 |
+
|
| 55 |
+
return entities
|
| 56 |
+
|
| 57 |
+
except Exception as e:
|
| 58 |
+
print(f"\n--- EXTRACTION ERROR ---")
|
| 59 |
+
print(str(e))
|
| 60 |
+
print("------------------------\n")
|
| 61 |
+
# Return an empty list if it fails so the frontend doesn't crash
|
| 62 |
+
return []
|
railway-config.json
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"build": {
|
| 3 |
+
"builder": "NIXPACKS",
|
| 4 |
+
"buildCommand": "pip install -r requirements.txt"
|
| 5 |
+
},
|
| 6 |
+
"deploy": {
|
| 7 |
+
"startCommand": "uvicorn app:app --host 0.0.0.0 --port $PORT",
|
| 8 |
+
"healthcheckPath": "/health",
|
| 9 |
+
"healthcheckTimeout": 100,
|
| 10 |
+
"restartPolicyType": "ON_FAILURE",
|
| 11 |
+
"restartPolicyMaxRetries": 10
|
| 12 |
+
}
|
| 13 |
+
}
|
requirements.txt
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
fastapi==0.111.0
|
| 2 |
+
uvicorn[standard]==0.30.1
|
| 3 |
+
python-dotenv==1.0.1
|
| 4 |
+
langchain==0.2.6
|
| 5 |
+
langchain-google-genai==1.0.6
|
| 6 |
+
langchain-groq==1.1.3
|
| 7 |
+
hindsight==0.3.2
|
| 8 |
+
cascadeflow==0.1.4
|
| 9 |
+
requests==2.32.3
|
| 10 |
+
python-multipart==0.0.9
|
| 11 |
+
pydantic==2.7.4
|
| 12 |
+
# Local FLUX.1-schnell pipeline (GPU)
|
| 13 |
+
# PyTorch must be installed separately with the CUDA index URL:
|
| 14 |
+
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
|
| 15 |
+
diffusers>=0.39.0
|
| 16 |
+
accelerate>=1.14.0
|
| 17 |
+
transformers>=5.13.0
|
| 18 |
+
safetensors>=0.8.0
|