StillWorking commited on
Commit
a387ea0
·
verified ·
1 Parent(s): 368c0a6

Upload 16 files

Browse files
Files changed (16) hide show
  1. .dockerignore +53 -0
  2. .env.example +23 -0
  3. .gitignore +74 -0
  4. Dockerfile +38 -0
  5. Procfile +1 -0
  6. README.md +242 -7
  7. __init__.py +1 -0
  8. app.py +118 -0
  9. cascade_config.py +48 -0
  10. docker-compose.yml +58 -0
  11. image_gen.py +47 -0
  12. lore_generator.py +105 -0
  13. memory_manager.py +31 -0
  14. nlp_extractor.py +62 -0
  15. railway-config.json +13 -0
  16. 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
- title: Lore
3
- emoji: 🔥
4
- colorFrom: pink
5
- colorTo: pink
6
- sdk: static
7
- pinned: false
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8
  ---
9
 
10
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
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