feat: standardizing inference output format and adding Setup Guide

Setup_Guide.md

@@ -0,0 +1,124 @@
+# UI LAYOUT OPTIMIZER OPENENV
+**Complete Beginner's Setup & Run Guide**
+*Meta x PyTorch OpenEnv Hackathon 2026*
+Step-by-step from zero to running RL agent
+
+---
+
+## What You Will Build
+This guide walks you through running the **UI Layout Optimizer Simulator** — a Reinforcement Learning environment built on Meta's OpenEnv framework. By the end, you'll have a real RL agent that manipulates digital checkout components (button sizes, form lengths, wizard steps) to maximize user conversion and minimize cart abandonment, using a HuggingFace LLM-driven agent as a baseline.
+
+## Prerequisites — What You Need Before Starting
+Check all of these before going to the next step:
+- Python 3.10 or newer (3.11 recommended)
+- `pip` (comes with Python)
+- `git`
+- A terminal / command prompt
+- A HuggingFace account (free) for LLM API access
+- A Code Editor (VS Code recommended)
+
+---
+
+## Step 1 — Check Your Python Version
+Python 3.10+ is required. Verify first:
+```bash
+python --version
+```
+*You should see Python 3.10.x or newer.*
+
+## Step 2 — Download the Project
+Clone the repository to your computer:
+```bash
+git clone https://github.com/Prasannakolapkar/UI-Layout-optimizer.git
+cd UI-Layout-optimizer
+```
+
+## Step 3 — Create a Virtual Environment
+A virtual environment keeps this project's packages separate from everything else on your computer.
+
+**Windows:**
+```bash
+python -m venv venv
+.\venv\Scripts\activate
+```
+
+**Mac/Linux:**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+*You will see `(venv)` at the start of your terminal prompt when it's active.* **Always activate before running project commands.**
+
+## Step 4 — Install Dependencies
+Install all the Python packages the project needs:
+```bash
+pip install -r requirements.txt
+```
+*(This installs FastAPI, Pydantic, Uvicorn, httpx, and other core libraries).*
+
+## Step 5 — Get Your HuggingFace API Token
+Our baseline agent uses a HuggingFace model to route UI decisions. You need a free API token to call it.
+1. Go to huggingface.co and sign up.
+2. Go to **Settings > Access Tokens**.
+3. Create a **New Token** with `Read` access.
+4. Copy the token (it starts with `hf_`).
+
+## Step 6 — Set Up Your Environment Variables
+We use a `.env` file (or exported variables) to store your HuggingFace token securely.
+
+Create a file named `.env` in the project root:
+```ini
+HF_TOKEN=hf_your_token_here
+```
+*If you don't use the LLM fallback agent, the purely mathematical `HeuristicAgent` works automatically without a token!*
+
+## Step 7 — Understand the Project Structure
+Before running anything, it helps to know what each file does:
+- `env.py` - Core RL logic: `reset()`, `step()`, simulates user drops, computes rewards.
+- `benchmark.py` - Evaluates agents over easy, medium, and hard tasks.
+- `server/app.py` - The FastAPI environment server that exposes REST endpoints for agents and the UI.
+- `frontend/` - Contains the HTML/JS web interface for real-time visualization.
+- `baseline.py` & `heuristic_agent.py` - Your RL agent implementations.
+- `openenv.yaml` - OpenEnv specification declaration for HuggingFace deployment.
+
+## Step 8 — Run the Grader (Quickest Test)
+The benchmark script is the fastest way to verify everything works. It calculates the leaderboard score across all difficulties:
+```bash
+python benchmark.py
+```
+**What to expect:** You'll see episodes running and evaluating the agent's performance (score, completion rate, drop rate). The internal `HeuristicAgent` correctly minimizes dropping users by acting ethically and intelligently!
+
+## Step 9 — Start the FastAPI Local Server
+The server exposes the environment locally so the visualizer and external agents can interact with it.
+```bash
+uvicorn server.app:app --reload
+```
+**Verify it's running:** Open a browser and go to `http://127.0.0.1:7860/` (or `8000` depending on port settings). You will see the Interactive UI Simulator!
+
+## Step 10 — Connect an Agent (Client Usage)
+Now let's verify our LLM baseline router connects with the logic correctly:
+*(Open a second terminal, activate `venv`!)*
+```bash
+python baseline.py
+```
+You'll see step-by-step UI adjustments printed in the console. The agent reduces form complexity and resizes buttons to perfection.
+
+## Step 11 — Understanding the Reward Function
+This is the heart of the RL environment. The UI layout directly targets human psychology.
+- **Completion Reward**: Big positive impact for moving the progress bar.
+- **Drop Penalty (-1.0)**: Catastrophic penalty if user abandons the cart due to frustration.
+- **Distrust Penalty (-0.2)**: Small penalty if buttons look glitchy or fields are invasive.
+- **Ideal States**: Optimal form length is ~3, optimal steps ~2, optimal button size ~1.1x.
+
+## Step 12 — Common Errors and Fixes
+- `KeyError: 'grader'`: Ensure your `openenv.yaml` contains `grader: "env:UIEnv.grade_easy"` for each task. (Already patched!)
+- `TypeError: Cannot read properties of undefined (reading 'toFixed')`: Make sure you have the latest `frontend/script.js` with the safe `fmt()` helper.
+- `ModuleNotFoundError: No module named 'openenv'`: Ensure your `venv` is active and requirements are installed.
+- `Connection refused`: Make sure the Uvicorn server is actively running in another tab.
+
+## Step 13 — Deploy to HuggingFace Spaces (Optional)
+Your code is fully OpenEnv compliant and Docker-ready!
+1. Create a New Space on HuggingFace.
+2. Choose **Docker** environment.
+3. In space settings, add `HF_TOKEN` to your Secrets.
+4. The deployment will automatically host the `FastAPI` instance and validation system globally so judges can score you.

frontend/script.js

@@ -280,7 +280,7 @@ async function resetEnv() {
         dom.metricOutcome.textContent = "--";
         dom.metricOutcome.className = "text-lg font-bold text-dark-400";
 
-        addLog("Environment reset. Episode started.", "system");
+        addLog(`[START] task=default env=ui_layout_optimizer model=${dom.agentSelect.value}`, "system");
     } catch (err) {
         addLog("Error: " + err.message, "negative");
     }
@@ -319,8 +319,9 @@ async function stepAgent() {
             state.done = s.done;
 
             updateUI(s.observation, s.reward, s.info);
+            const errorStr = s.info.error ? s.info.error : "null";
             addLog(
-                `Step ${s.info.step_count}: ${s.action}  ->  reward=${s.reward >= 0 ? "+" : ""}${fmt(s.reward, 3)}  outcome=${s.info.outcome}`,
+                `[STEP] step=${s.info.step_count} action=${s.action} reward=${fmt(s.reward, 2)} done=${s.done} error=${errorStr}`,
                 s.reward >= 0 ? "reward" : "negative"
             );
 
@@ -330,7 +331,9 @@ async function stepAgent() {
                 const outcome = s.info.outcome;
                 setEpisodeStatus(outcome === "complete" ? "DONE" : "DROPPED", outcome);
                 setControlsEnabled(false);
-                addLog(`Episode ended: ${outcome}. Total reward: ${fmt(state.totalReward, 3)}`, "outcome");
+                const success = outcome === "complete" ? "true" : "false";
+                const rewardsStr = state._cachedSteps.slice(0, state._cacheIdx).map(st => fmt(st.reward, 2)).join(",");
+                addLog(`[END] success=${success} steps=${s.info.step_count} rewards=${rewardsStr}`, "outcome");
                 state._cachedSteps = null;
             }
         }
@@ -352,7 +355,7 @@ async function runEpisode() {
     dom.btnRun.textContent = "Running...";
     setControlsEnabled(false);
 
-    addLog(`--- Running full episode with ${agent} agent ---`, "system");
+    addLog(`[START] task=default env=ui_layout_optimizer model=${agent}`, "system");
 
     try {
         const data = await api("/run_episode", "POST", { agent });
@@ -368,8 +371,9 @@ async function runEpisode() {
             updateUI(s.observation, s.reward, s.info);
 
             const actionLabel = s.action + (s.action_value !== null ? `(${s.action_value})` : "");
+            const errorStr = s.info.error ? s.info.error : "null";
             addLog(
-                `Step ${s.info.step_count}: ${actionLabel}  ->  R=${s.reward >= 0 ? "+" : ""}${fmt(s.reward, 3)}  [${s.info.outcome}]`,
+                `[STEP] step=${s.info.step_count} action=${actionLabel} reward=${fmt(s.reward, 2)} done=${s.done} error=${errorStr}`,
                 s.reward >= 0 ? "reward" : "negative"
             );
 
@@ -379,8 +383,10 @@ async function runEpisode() {
 
         const outcome = data.final_outcome;
         setEpisodeStatus(outcome === "complete" ? "DONE" : "DROPPED", outcome);
+        const success = outcome === "complete" ? "true" : "false";
+        const rewardsStr = data.steps.map(st => fmt(st.reward, 2)).join(",");
         addLog(
-            `Episode complete: ${outcome}  |  Total reward: ${fmt(state.totalReward, 3)}  |  Steps: ${data.total_steps}`,
+            `[END] success=${success} steps=${data.total_steps} rewards=${rewardsStr}`,
             "outcome"
         );
 

inference.py

@@ -23,10 +23,10 @@ def log_step(step: int, action: str, reward: float, done: bool, error: Optional[
         flush=True,
     )
 
-def log_end(success: bool, steps: int, score: float, rewards: List[float]) -> None:
+def log_end(success: bool, steps: int, rewards: List[float]) -> None:
     rewards_str = ",".join(f"{r:.2f}" for r in rewards)
     success_val = str(success).lower()
-    print(f"[END] success={success_val} steps={steps} score={score:.3f} rewards={rewards_str}", flush=True)
+    print(f"[END] success={success_val} steps={steps} rewards={rewards_str}", flush=True)
 
 def run_inference(task_id: str = "easy") -> None:
     """
@@ -89,8 +89,7 @@ def run_inference(task_id: str = "easy") -> None:
 
     # Enforce strict (0,1) bound
     score = clamp_score(score)
-    
-    log_end(success=completed, steps=step_count, score=score, rewards=rewards)
+    log_end(success=completed, steps=step_count, rewards=rewards)
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="Run UIEnv Inference")