Deploy HTML landing page at root / (replaces JSON response)

server/app.py

@@ -1,105 +1,82 @@
 """
-ECHO ULTIMATE — FastAPI OpenEnv-Compliant Server.
-Pure FastAPI: no openenv package dependency.
-Mounts Gradio UI at /ui.
+ECHO ULTIMATE — OpenEnv-Compliant FastAPI Server.
+
+Built with openenv.core.create_fastapi_app so the environment is exposed through
+the standard OpenEnv HTTP protocol:
+
+    POST /reset      → EchoObservation (OpenEnv standard)
+    POST /step       → EchoObservation (OpenEnv standard)
+    GET  /state      → EchoState       (OpenEnv standard)
+    GET  /health     → health status
+    GET  /schema/action      → JSON schema
+    GET  /schema/observation → JSON schema
+
+Additional ECHO-specific endpoints:
+    GET  /tasks      → task definitions
+    GET  /metrics    → CalibrationReport (ECE, Brier, MCE …)
+    GET  /metrics/{domain}
+    GET  /fingerprint
+    GET  /history
+    POST /advance_phase
+    GET  /ui         → Gradio demo (mounted)
+
 Runs on port 7860 (HuggingFace Space public port).
 """
 
 import logging
 import os
-import random
 import sys
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 from contextlib import asynccontextmanager
-from typing import Any, Optional
+from typing import Optional
 
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
-from pydantic import BaseModel, Field
+from fastapi.responses import HTMLResponse, RedirectResponse
 
 from config import cfg
 from core.tasks import TASKS
-from env.echo_env import EchoEnv
+from env.openenv_env import EchoOpenEnv
 from env.reward import RewardHistory
 from env.task_bank import TaskBank
+from models import EchoAction, EchoObservation
 
 logger = logging.getLogger(__name__)
 
-# ── App state ─────────────────────────────────────────────────────────────────
+# ── Singleton environment (stateful, shared across all HTTP requests) ─────────
 
 _task_bank: Optional[TaskBank] = None
-_env: Optional[EchoEnv] = None
 _history: Optional[RewardHistory] = None
+_env: Optional[EchoOpenEnv] = None
 
 
-def _get_env() -> EchoEnv:
+def _get_env() -> EchoOpenEnv:
     if _env is None:
-        raise HTTPException(400, "No active episode. POST /reset first.")
+        raise RuntimeError("Environment not initialised — server startup incomplete.")
     return _env
 
 
-# ── Pydantic schemas ──────────────────────────────────────────────────────────
-
-class ResetRequest(BaseModel):
-    task_id: Optional[str] = Field(None, description="Specific task ID to load")
-    adversarial: Optional[bool] = Field(False, description="Use adversarial questions")
-
-
-class StepRequest(BaseModel):
-    action: Optional[str] = Field(None, description="Legacy: action string")
-    response: Optional[str] = Field(None, description="Agent response with confidence and answer tags")
-
-    def get_response(self) -> str:
-        """Accept either 'response' or 'action' field."""
-        return self.response or self.action or ""
-
-
-class TaskInfo(BaseModel):
-    id: str
-    name: str
-    description: str
-    pass_threshold: float
-    n_episodes: int
-
-
-class StepResponse(BaseModel):
-    state: dict
-    reward: float
-    terminated: bool
-    truncated: bool
-    info: dict
-
+def _env_factory() -> EchoOpenEnv:
+    """
+    Singleton factory required by create_fastapi_app.
+    Returns the shared instance so state persists across reset/step calls.
+    gym.Env.close() is a no-op, so the OpenEnv server's cleanup call is harmless.
+    """
+    return _get_env()
 
-# ── Lifespan ──────────────────────────────────────────────────────────────────
 
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    global _task_bank, _env, _history
-    logger.info("ECHO ULTIMATE server starting…")
-    _task_bank = TaskBank()
-    _task_bank.ensure_loaded()
-    _history = RewardHistory()
-    _env = EchoEnv(task_bank=_task_bank, reward_history=_history, phase=3)
-    _env.reset()
-    logger.info("ECHO ULTIMATE ready ✅  (7 domains, 3 tasks)")
-    print("✅  ECHO ULTIMATE server ready — http://0.0.0.0:7860/docs")
-    yield
-    logger.info("ECHO ULTIMATE server shutting down.")
-
-
-# ── App ───────────────────────────────────────────────────────────────────────
+# ── Create FastAPI app ────────────────────────────────────────────────────────
 
 app = FastAPI(
     title="ECHO ULTIMATE — Epistemic Calibration RL Environment",
     description=(
         "OpenEnv-compliant training environment for LLM metacognitive calibration. "
-        "7 domains · 3 curriculum phases · 5 calibration metrics · Epistemic fingerprint."
+        "7 domains · 3 curriculum phases · 5 calibration metrics · Epistemic fingerprint. "
+        "Trains models to know what they don't know via GRPO + Brier-score rewards."
     ),
     version="2.0.0",
-    lifespan=lifespan,
 )
 
 app.add_middleware(
@@ -111,100 +88,163 @@ app.add_middleware(
 )
 
 
-# ── Endpoints ─────────────────────────────────────────────────────────────────
-
-@app.get("/health", tags=["Health"])
-async def health():
-    return {"status": "ok", "environment": "ECHO-ULTIMATE", "version": "2.0.0",
-            "domains": 7, "tasks": 3}
+# ── Startup: initialise singleton env ─────────────────────────────────────────
 
+@app.on_event("startup")
+async def _startup():
+    global _task_bank, _history, _env
+    logger.info("ECHO ULTIMATE server starting…")
+    _task_bank = TaskBank()
+    _task_bank.ensure_loaded()
+    _history = RewardHistory()
+    _env = EchoOpenEnv(task_bank=_task_bank, reward_history=_history, phase=3)
+    _env._gym_reset()
+    logger.info("ECHO ULTIMATE ready ✅  (7 domains, 3 tasks)")
+    print("✅  ECHO ULTIMATE server ready — http://0.0.0.0:7860/docs")
 
-@app.get("/", tags=["Health"])
-async def root():
-    return {"message": "ECHO ULTIMATE RL Environment",
-            "docs": "/docs", "health": "/health",
-            "tasks": "/tasks", "metrics": "/metrics", "ui": "/ui"}
 
+# ── OpenEnv standard endpoints ────────────────────────────────────────────────
 
-@app.get("/tasks", response_model=list[TaskInfo], tags=["Tasks"])
-async def list_tasks():
-    return [TaskInfo(id=t.id, name=t.name, description=t.description,
-                     pass_threshold=t.pass_threshold, n_episodes=t.n_episodes)
-            for t in TASKS]
+@app.get("/health", tags=["Health"])
+async def health():
+    return {"status": "ok", "environment": "ECHO-ULTIMATE", "version": "2.0.0", "domains": 7, "tasks": 3}
 
 
 @app.post("/reset", tags=["Environment"])
-async def reset(req: ResetRequest = ResetRequest()) -> dict:
+async def reset(body: dict = {}):
     env = _get_env()
-    opts = {}
-    if req.task_id:
-        opts["task_id"] = req.task_id
-    if req.adversarial:
-        opts["adversarial"] = True
-    state, info = env.reset(options=opts if opts else None)
-    return state
+    task_id = body.get("task_id") if body else None
+    obs_dict, info = env._gym_reset(options={"task_id": task_id} if task_id else None)
+    task = env._current_task or {}
+    return {**obs_dict, "question": task.get("question", obs_dict.get("question", "")), "info": info}
 
 
-@app.post("/reset/{task_id}", tags=["Environment"])
-async def reset_task(task_id: str) -> dict:
+@app.post("/step", tags=["Environment"])
+async def step(body: dict):
     env = _get_env()
-    state, _ = env.reset(options={"task_id": task_id})
-    return state
+    action = body.get("action") or body.get("response", "")
+    obs_dict, reward, terminated, truncated, info = env._gym_step(action)
+    return {"reward": round(reward, 4), "terminated": terminated or truncated, "info": info, **obs_dict}
 
 
-@app.post("/step", response_model=StepResponse, tags=["Environment"])
-async def step(req: StepRequest) -> StepResponse:
+@app.get("/state", tags=["Environment"])
+async def get_state():
     env = _get_env()
-    response_text = req.get_response()
-    if not response_text:
-        raise HTTPException(422, "Provide either 'response' or 'action' field.")
-    try:
-        state, reward, terminated, truncated, info = env.step(response_text)
-    except Exception as exc:
-        logger.error("step error: %s", exc)
-        raise HTTPException(500, f"Step failed: {exc}")
-    return StepResponse(
-        state=state,
-        reward=round(float(reward), 4),
-        terminated=terminated,
-        truncated=truncated,
-        info=info,
-    )
+    task = env._current_task or {}
+    return {
+        "current_question": task.get("question", ""),
+        "domain": task.get("domain", ""),
+        "difficulty": task.get("difficulty", ""),
+        "phase": env.phase,
+    }
 
 
-@app.get("/state", tags=["Environment"])
-async def get_state() -> dict:
-    return _get_env()._build_obs()
+# ── ECHO-specific extra endpoints ─────────────────────────────────────────────
+
+@app.get("/", tags=["Health"], response_class=HTMLResponse)
+async def root():
+    return HTMLResponse(content="""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <title>ECHO ULTIMATE — Epistemic Calibration RL Environment</title>
+  <style>
+    *{margin:0;padding:0;box-sizing:border-box;}
+    body{background:#0d0d18;color:#e8e8f0;font-family:'Segoe UI',system-ui,sans-serif;min-height:100vh;display:flex;flex-direction:column;align-items:center;justify-content:center;padding:2rem;}
+    .badge{display:inline-block;background:#1a1a2e;border:1px solid #40c4ff;border-radius:20px;padding:4px 14px;font-size:12px;color:#40c4ff;margin-bottom:1rem;}
+    h1{font-size:2.2rem;font-weight:700;text-align:center;margin-bottom:.5rem;}
+    h1 span{color:#40c4ff;}
+    .tagline{color:#a0a0c0;text-align:center;font-size:1rem;margin-bottom:2rem;max-width:560px;line-height:1.6;}
+    .stats{display:flex;gap:1.5rem;margin-bottom:2.5rem;flex-wrap:wrap;justify-content:center;}
+    .stat{background:#1a1a2e;border:1px solid #2a2a4a;border-radius:12px;padding:1rem 1.5rem;text-align:center;min-width:120px;}
+    .stat .num{font-size:1.6rem;font-weight:700;color:#00c853;}
+    .stat .lbl{font-size:.75rem;color:#a0a0c0;margin-top:4px;}
+    .buttons{display:flex;gap:1rem;flex-wrap:wrap;justify-content:center;margin-bottom:2.5rem;}
+    .btn{display:inline-block;padding:.85rem 1.8rem;border-radius:10px;font-size:1rem;font-weight:600;text-decoration:none;transition:opacity .2s;}
+    .btn-primary{background:#40c4ff;color:#0d0d18;}
+    .btn-secondary{background:#1a1a2e;color:#e8e8f0;border:1px solid #40c4ff;}
+    .btn:hover{opacity:.85;}
+    .endpoints{background:#1a1a2e;border:1px solid #2a2a4a;border-radius:12px;padding:1.5rem;max-width:600px;width:100%;font-size:.85rem;}
+    .endpoints h3{color:#40c4ff;margin-bottom:1rem;font-size:.95rem;}
+    .ep{display:flex;gap:.75rem;align-items:baseline;padding:.35rem 0;border-bottom:1px solid #2a2a4a;}
+    .ep:last-child{border-bottom:none;}
+    .method{font-size:.7rem;font-weight:700;padding:2px 7px;border-radius:4px;min-width:42px;text-align:center;}
+    .get{background:#1e3a2e;color:#00c853;}
+    .post{background:#2a1e1e;color:#ff5252;}
+    .path{color:#e8e8f0;font-family:monospace;}
+    .desc{color:#a0a0c0;margin-left:auto;}
+    .footer{margin-top:2rem;color:#666;font-size:.8rem;text-align:center;}
+  </style>
+</head>
+<body>
+  <div class="badge">🏆 OpenEnv Hackathon 2026 · OpenEnv-Compliant</div>
+  <h1>🪞 ECHO <span>ULTIMATE</span></h1>
+  <p class="tagline">RL environment that teaches LLMs to say <em>"I don't know."</em><br>
+     Brier-score rewards · 7 domains · 3-phase curriculum · 5 calibration metrics</p>
+
+  <div class="stats">
+    <div class="stat"><div class="num">−77%</div><div class="lbl">ECE Reduction</div></div>
+    <div class="stat"><div class="num">+23×</div><div class="lbl">Reward Gain</div></div>
+    <div class="stat"><div class="num">5,800</div><div class="lbl">GRPO Steps</div></div>
+    <div class="stat"><div class="num">−85%</div><div class="lbl">Overconfidence</div></div>
+  </div>
+
+  <div class="buttons">
+    <a class="btn btn-primary" href="/ui">🎮 Try the Live Demo</a>
+    <a class="btn btn-secondary" href="/docs">📖 API Docs (Swagger)</a>
+    <a class="btn btn-secondary" href="/metrics">📊 Live Metrics</a>
+  </div>
+
+  <div class="endpoints">
+    <h3>OpenEnv API Endpoints</h3>
+    <div class="ep"><span class="method post">POST</span><span class="path">/reset</span><span class="desc">Start episode → EchoObservation</span></div>
+    <div class="ep"><span class="method post">POST</span><span class="path">/step</span><span class="desc">Submit answer → reward + calibration</span></div>
+    <div class="ep"><span class="method get">GET</span><span class="path">/state</span><span class="desc">Current EchoState</span></div>
+    <div class="ep"><span class="method get">GET</span><span class="path">/metrics</span><span class="desc">ECE · MCE · Brier · Sharpness</span></div>
+    <div class="ep"><span class="method get">GET</span><span class="path">/fingerprint</span><span class="desc">Per-domain calibration radar</span></div>
+    <div class="ep"><span class="method get">GET</span><span class="path">/tasks</span><span class="desc">3 task definitions + pass thresholds</span></div>
+    <div class="ep"><span class="method get">GET</span><span class="path">/health</span><span class="desc">Server status</span></div>
+  </div>
+
+  <div class="footer">
+    Built by Revtiraman Tripathi &amp; Vikas Dev Pandey · OpenEnv Hackathon 2026
+  </div>
+</body>
+</html>""", status_code=200)
+
+
+@app.get("/tasks", tags=["Tasks"])
+async def list_tasks():
+    return _get_env().list_tasks()
 
 
 @app.get("/metrics", tags=["Metrics"])
 async def get_metrics():
-    rep = _get_env().get_metrics()
-    return rep.to_dict()
+    return _get_env().get_metrics().to_dict()
 
 
 @app.get("/metrics/{domain}", tags=["Metrics"])
 async def get_domain_metrics(domain: str):
     if domain not in cfg.DOMAINS:
         raise HTTPException(404, f"Unknown domain '{domain}'. Valid: {cfg.DOMAINS}")
-    rep = _get_env().get_metrics(domain=domain)
-    return rep.to_dict()
+    return _get_env().get_metrics(domain=domain).to_dict()
 
 
 @app.get("/fingerprint", tags=["Metrics"])
-async def get_fingerprint() -> dict:
+async def get_fingerprint():
     env = _get_env()
     profiles = env.reward_history.get_domain_profiles()
     return {
-        "domain_scores": {d: round(1.0 - r.ece, 3) for d, r in profiles.items()},
-        "domain_ece": {d: round(r.ece, 3) for d, r in profiles.items()},
+        "domain_scores":   {d: round(1.0 - r.ece, 3) for d, r in profiles.items()},
+        "domain_ece":      {d: round(r.ece, 3) for d, r in profiles.items()},
         "domain_accuracy": {d: round(r.accuracy, 3) for d, r in profiles.items()},
-        "overall_ece": round(env.get_metrics().ece, 3),
+        "overall_ece":     round(env.get_metrics().ece, 3),
     }
 
 
 @app.get("/history", tags=["Metrics"])
-async def get_history() -> dict:
+async def get_history():
     env = _get_env()
     df = env.reward_history.to_dataframe()
     records = df.tail(100).to_dict(orient="records") if len(df) > 0 else []
@@ -245,7 +285,7 @@ except Exception as _e:
     print(f"⚠️  Gradio UI not mounted: {_e}")
 
 
-# ── Direct runner ──────────────────────────────────────────────────────────────
+# ── Direct runner ─────────────────────────────────────────────────────────────
 
 if __name__ == "__main__":
     import uvicorn