docs/app.md

Flask Demo Interface

Source files: app_flask.py, templates/index.html

---

Overview

app_flask.py is the demo application. It runs a Flask server on port 7860 and serves a single-page application with 10 tabs. The frontend uses Chart.js for reward/metric plots and vis-network for the cascade dependency graph visualization. There is no Gradio in the stack — app.py is a legacy file; app_flask.py is the production demo.

---

Architecture

Flask handles all HTTP routes. The frontend is a full HTML/JS application in templates/index.html. Tabs communicate with the backend via /api/* endpoints that return JSON. The vis-network cascade animation calls core/cascade_utils.py:animate_cascade() to get frame-by-frame cascade data.

---

Module-level singletons

These are instantiated at startup:

Variable	Type	Purpose
agent	LifeStackAgent	GRPO model + Groq fallback
memory	LifeStackMemory	ChromaDB trajectory + feedback store
MODEL_REGISTRY	dict	Maps model label → HF repo ID for v1–v4
_load_grpo_model	function	Lazy-loads a specific LoRA adapter

MODEL_REGISTRY allows the demo to switch between v1, v3, and v4 adapters on the fly via a dropdown in the UI.

---

Key API routes

Route	Purpose
GET /	Serves templates/index.html
POST /api/run_demo	Runs the agent on a preset conflict, returns step-by-step cascade frames and action JSON
POST /api/custom_run	Runs the agent on a user-typed situation
POST /api/submit_feedback	Stores OutcomeFeedback in ChromaDB memory
GET /api/cascade_animate	Returns frame list from animate_cascade() for the vis-network graph
GET /api/memory_stats	Returns LifeStackMemory.get_stats()
GET /api/health	Basic health check

---

Running

python app_flask.py      # serves on http://localhost:7860

In Docker, start.sh runs this as the foreground process. HuggingFace Spaces health-checks port 7860 — Flask must stay alive for the Space to remain healthy.

---

Related files

• templates/index.html — full frontend (Chart.js, vis-network)
• core/cascade_utils.py — animate_cascade() drives the dependency graph visualization
• agent/agent.py — LifeStackAgent with GRPO model
• agent/memory.py — LifeStackMemory
• start.sh — starts this as foreground service on port 7860