---
title: UI Layout Optimizer
emoji: 🎨
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
---

# UI Layout Optimizer: Adaptive UI Optimization Environment (OpenEnv)

[![OpenEnv](https://img.shields.io/badge/OpenEnv-Compatible-blue.svg)](https://github.com/OpenEnv-Protocol)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Motivation
In modern digital products, static A/B testing often fails to capture the nuance of diverse user behaviors. The **UI Layout Optimizer** is an OpenEnv-compliant environment designed to train agents that dynamically adapt layout configurations—such as button sizes, form lengths, and wizard steps—to maximize conversion rates and user satisfaction in real-time.

By simulating various user personas (impatient, careful, new users) and their psychological responses to UI friction, this environment provides a standardized benchmark for autonomous UI optimization agents.

---

## 🛠️ Environment Specification

### Action Space
The agent can manipulate the UI layout through seven distinct actions:

| Action | Description |
| :--- | :--- |
| `increase_button` | Increments the button size multiplier. |
| `decrease_form` | Reduces the number of form fields to lower friction. |
| `increase_steps` | Adds a step to the checkout flow/wizard. |
| `decrease_steps` | Removes a step to streamline the completion flow. |
| `reorder_sections` | Optimizes the component arrangement. |
| `set_button_size` | Continuously tunes the button size (0.5 - 2.0). |
| `noop` | Maintains the current layout state. |

### Observation Space
At each step, the agent receives an `Observation` containing:

- **Device**: `mobile` or `desktop` (affects user tolerance thresholds).
- **Layout**: Current `button_size`, `form_length`, and number of `steps`.
- **Progress**: A scalar value (0.0 to 1.0) representing task completion.
- **Last Action**: Feedback on the previous operation.

### Task Descriptions
Evaluation is conducted across three difficulty tiers:

1. **Easy**: Discrete actions only, stable user types, and low noise levels.
2. **Medium**: Mixed user personas with stochastic drop-off rates.
3. **Hard**: Hidden user types, continuous action tuning, and highly noisy feedback.

---

## 💻 Usage

### Prerequisites
- Python 3.10+
- Hugging Face API Token (for LLM-based agents)

### Local Execution
1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
2. Run the baseline evaluation:
   ```bash
   export HF_TOKEN="your_token_here"
   python baseline.py
   ```

### Running with Docker
1. Build the image:
   ```bash
   docker build -t ui-optimizer .
   ```
2. Run the container:
   ```bash
   docker run -e HF_TOKEN="your_token_here" ui-optimizer
   ```

---

## ☁️ Deployment to Hugging Face Spaces

This project is optimized for deployment as a **Docker Space**.

1. Create a new Space on [Hugging Face](https://huggingface.co/new-space).
2. Select **Docker** as the SDK.
3. In the Space **Settings**, add your `HF_TOKEN` as a Secret.
4. Push the project files (including `Dockerfile` and `requirements.txt`) to the Space repository.
5. Hugging Face will automatically build and deploy the container.

---

## 📊 Baseline Results (Example)
Evaluation results using the provided `baseline.py` hybrid agent:

| Task | Avg Reward | Completion Rate | Final Score |
| :--- | :--- | :--- | :--- |
| Easy | 1.8450 | 92.0% | 0.8931 |
| Medium | 1.4210 | 78.0% | 0.7323 |
| Hard | 0.9820 | 54.0% | 0.5126 |

---

## 📜 License
This project is licensed under the MIT License - see the LICENSE file for details.