feat: backend updates for hosted demo (CORS, stats, seed, rate limit, Procfile)

.gitignore

@@ -15,3 +15,8 @@ chroma_db/
 __pycache__/
 *.pyc
 .pytest_cache/
+
+# Node / Next.js frontend
+web/node_modules/
+web/.next/
+web/.env

Procfile

@@ -0,0 +1 @@
+web: uvicorn api.main:app --host 0.0.0.0 --port $PORT

agent/core.py

@@ -90,6 +90,8 @@ class Agent:
             "brief": brief,
             "prompt_version": prompt_version,
             "retrieved_examples": len(retrieved),
+            # Surfaced to the frontend so it can show the loop is self-improving.
+            "retrieved_count": len(retrieved),
             "outputs": scored_outputs,
             "feedback": feedback_summary,
         }

api/main.py

@@ -1,23 +1,38 @@
-"""FastAPI app exposing a single endpoint to trigger the full agent loop.
+"""FastAPI app for the hosted public demo.
 
-POST /run with a brand brief -> retrieve -> generate -> evaluate -> feedback,
-returning the generated outputs and their scores.
+Endpoints:
+- GET  /health  -> liveness probe for Railway
+- GET  /stats   -> live counts (runs, golden, flagged) for the frontend strip
+- POST /run     -> full agent loop (rate limited), returns outputs + scores
 
-Run with:  uvicorn api.main:app --reload
+CORS is configured for the Vercel frontend, the Groq key is protected by a
+per-IP rate limit, and a fresh deployment is seeded so the first visitor sees
+non-zero stats and working retrieval.
+
+Run locally:  uvicorn api.main:app --reload
 """
 
+import os
+from contextlib import asynccontextmanager
 from typing import Any
 
 from dotenv import load_dotenv
-from fastapi import FastAPI, HTTPException
-from pydantic import BaseModel, Field
 
-load_dotenv()  # pick up GROQ_API_KEY from .env if present
+load_dotenv()  # pick up GROQ_API_KEY / CORS_ORIGINS from .env if present
 
-from agent.core import Agent  # noqa: E402  (after load_dotenv on purpose)
+from fastapi import FastAPI, HTTPException, Request  # noqa: E402
+from fastapi.middleware.cors import CORSMiddleware  # noqa: E402
+from pydantic import BaseModel, Field  # noqa: E402
+from slowapi import Limiter, _rate_limit_exceeded_handler  # noqa: E402
+from slowapi.errors import RateLimitExceeded  # noqa: E402
+from slowapi.util import get_remote_address  # noqa: E402
 
-app = FastAPI(title="Self-Improving Ad Copy Agent", version="1.0.0")
+from agent.core import Agent  # noqa: E402  (after load_dotenv on purpose)
+from seed.loader import load_seed_if_empty  # noqa: E402
 
+# --------------------------------------------------------------------------- #
+# Shared singletons
+# --------------------------------------------------------------------------- #
 # A single shared agent (and therefore shared Store/Memory) for the process.
 _agent: Agent | None = None
 
@@ -29,6 +44,59 @@ def get_agent() -> Agent:
     return _agent
 
 
+# --------------------------------------------------------------------------- #
+# CORS origins
+# --------------------------------------------------------------------------- #
+def _cors_origins() -> list[str]:
+    """Origins from CORS_ORIGINS (comma-separated), always plus localhost:3000.
+
+    If CORS_ORIGINS is unset, default to allow-all ("*").
+    """
+    raw = os.getenv("CORS_ORIGINS")
+    if not raw:
+        return ["*"]
+    origins = [o.strip() for o in raw.split(",") if o.strip()]
+    if "http://localhost:3000" not in origins:
+        origins.append("http://localhost:3000")
+    return origins
+
+
+# --------------------------------------------------------------------------- #
+# Lifespan: seed a fresh deployment on startup
+# --------------------------------------------------------------------------- #
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    try:
+        agent = get_agent()
+        seeded = load_seed_if_empty(agent.store, agent.memory)
+        if seeded:
+            print(f"[startup] Seeded {seeded} golden/memory example(s).")
+    except Exception as exc:  # noqa: BLE001 — never block startup on seeding.
+        print(f"[startup] Seed skipped: {exc}")
+    yield
+
+
+# --------------------------------------------------------------------------- #
+# App + rate limiter
+# --------------------------------------------------------------------------- #
+limiter = Limiter(key_func=get_remote_address)
+
+app = FastAPI(title="Self-Improving Ad Copy Agent", version="1.0.0", lifespan=lifespan)
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_cors_origins(),
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# --------------------------------------------------------------------------- #
+# Schemas
+# --------------------------------------------------------------------------- #
 class BrandBrief(BaseModel):
     brand: str = Field(..., examples=["FitFuel"])
     product: str = Field(..., examples=["High-protein meal replacement shake"])
@@ -37,14 +105,34 @@ class BrandBrief(BaseModel):
     goal: str = Field(..., examples=["Drive trial purchases"])
 
 
+# --------------------------------------------------------------------------- #
+# Endpoints
+# --------------------------------------------------------------------------- #
 @app.get("/")
 def root() -> dict[str, str]:
     return {"status": "ok", "endpoint": "POST /run with a brand brief"}
 
 
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/stats")
+def stats() -> dict[str, int]:
+    """Live counts for the frontend stats strip."""
+    store = get_agent().store
+    return {
+        "runs": store.count_runs(),
+        "golden": store.count_golden(),
+        "flagged": store.count_flagged(),
+    }
+
+
 @app.post("/run")
-def run(brief: BrandBrief) -> dict[str, Any]:
-    """Trigger the full agent loop for a brand brief."""
+@limiter.limit("10/minute")
+def run(request: Request, brief: BrandBrief) -> dict[str, Any]:
+    """Trigger the full agent loop for a brand brief (rate limited per IP)."""
     try:
         agent = get_agent()
         return agent.run(brief.model_dump())

db/store.py

@@ -239,6 +239,22 @@ class Store:
             result.append(d)
         return result
 
+    # ------------------------------------------------------------------ counts
+    def count_runs(self) -> int:
+        with self._lock:
+            row = self._conn.execute("SELECT COUNT(*) AS n FROM runs").fetchone()
+        return int(row["n"])
+
+    def count_golden(self) -> int:
+        with self._lock:
+            row = self._conn.execute("SELECT COUNT(*) AS n FROM golden").fetchone()
+        return int(row["n"])
+
+    def count_flagged(self) -> int:
+        with self._lock:
+            row = self._conn.execute("SELECT COUNT(*) AS n FROM flagged_outputs").fetchone()
+        return int(row["n"])
+
     # ------------------------------------------------------------------- close
     def close(self) -> None:
         with self._lock:

requirements.txt

@@ -4,6 +4,7 @@ sentence-transformers==3.3.1
 fastapi==0.115.6
 uvicorn==0.34.0
 rich==13.9.4
+slowapi==0.1.9
 pytest==8.3.4
 python-dotenv==1.0.1
 pydantic==2.10.4

seed/golden_seed.json

@@ -0,0 +1,59 @@
+[
+  {
+    "brief": {
+      "brand": "FitFuel",
+      "product": "High-protein meal replacement shake",
+      "audience": "Busy professionals aged 25-40",
+      "tone": "Energetic and no-nonsense",
+      "goal": "Drive trial purchases"
+    },
+    "variant_type": "headline",
+    "output": "Fuel Your Hustle, Not Your Hunger",
+    "scores": {
+      "hook_strength": 5,
+      "brand_alignment": 5,
+      "clarity": 5,
+      "conversion_intent": 4,
+      "weighted_average": 4.8
+    },
+    "prompt_version": "GENERATION_PROMPT_V1"
+  },
+  {
+    "brief": {
+      "brand": "FitFuel",
+      "product": "High-protein meal replacement shake",
+      "audience": "Busy professionals aged 25-40",
+      "tone": "Energetic and no-nonsense",
+      "goal": "Drive trial purchases"
+    },
+    "variant_type": "body",
+    "output": "No time to cook, no patience for slumps. FitFuel packs 30g of protein into one fast shake so you stay sharp from the 9am standup to the 6pm sprint. Real fuel, zero fuss.",
+    "scores": {
+      "hook_strength": 4,
+      "brand_alignment": 5,
+      "clarity": 5,
+      "conversion_intent": 4,
+      "weighted_average": 4.5
+    },
+    "prompt_version": "GENERATION_PROMPT_V1"
+  },
+  {
+    "brief": {
+      "brand": "BrightBrew",
+      "product": "Cold brew coffee concentrate",
+      "audience": "Remote workers who want better coffee at home",
+      "tone": "Calm, premium, understated",
+      "goal": "Drive subscription sign-ups"
+    },
+    "variant_type": "body",
+    "output": "Skip the cafe queue. One bottle of BrightBrew concentrate makes twelve smooth, low-acidity cups right at your desk. Subscribe and your next batch arrives before you run out.",
+    "scores": {
+      "hook_strength": 4,
+      "brand_alignment": 4,
+      "clarity": 5,
+      "conversion_intent": 4,
+      "weighted_average": 4.25
+    },
+    "prompt_version": "GENERATION_PROMPT_V1"
+  }
+]

seed/loader.py

@@ -0,0 +1,52 @@
+"""Startup seed loader.
+
+A fresh deployment has an empty golden dataset and empty memory, so the very
+first visitor would see zeroed stats and get no few-shot retrieval. To avoid
+that cold-start look, we load a small set of pre-scored example outputs into
+both SQLite (golden) and ChromaDB (memory) the first time the app boots with an
+empty golden table.
+
+Idempotent: if the golden dataset already has entries, this does nothing.
+"""
+
+import json
+import os
+from datetime import datetime, timezone
+
+from agent.memory import Memory
+from db.store import Store
+
+SEED_PATH = os.path.join(os.path.dirname(__file__), "golden_seed.json")
+
+
+def load_seed_if_empty(store: Store, memory: Memory) -> int:
+    """Load seed examples into golden + memory iff golden is currently empty.
+
+    Returns the number of entries seeded (0 if it was already populated).
+    """
+    if store.count_golden() > 0:
+        return 0
+
+    with open(SEED_PATH, "r", encoding="utf-8") as f:
+        entries = json.load(f)
+
+    now = datetime.now(timezone.utc).isoformat()
+    seeded = 0
+    for entry in entries:
+        brief = entry["brief"]
+        variant_type = entry["variant_type"]
+        output = entry["output"]
+        scores = entry["scores"]
+        prompt_version = entry.get("prompt_version", "GENERATION_PROMPT_V1")
+
+        store.add_golden(brief, variant_type, output, scores, prompt_version)
+        memory.add(
+            brief=brief,
+            variant_type=variant_type,
+            output=output,
+            score=float(scores["weighted_average"]),
+            prompt_version=prompt_version,
+            timestamp=now,
+        )
+        seeded += 1
+    return seeded