Setup_Guide.md

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:

python --version

You should see Python 3.10.x or newer.

Step 2 — Download the Project

Clone the repository to your computer:

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:

python -m venv venv
.\venv\Scripts\activate

Mac/Linux:

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:

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:

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:

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.

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!)

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.