Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,91 @@
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=layoutenv
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure stats directory exists and copy precomputed dataset stats when present.
+# Supports both common build-context layouts:
+# - context at repo root   -> /app/env/dataset/...
+# - context at layoutenv/  -> optional /app/dataset/... fallback
+RUN mkdir -p /app/env/dataset && \
+    if [ -f /app/env/dataset/genposter_5000_images_stats.npy ]; then \
+        echo "Using stats at /app/env/dataset/genposter_5000_images_stats.npy"; \
+    elif [ -f /app/dataset/genposter_5000_images_stats.npy ]; then \
+        cp /app/dataset/genposter_5000_images_stats.npy /app/env/dataset/genposter_5000_images_stats.npy; \
+        echo "Copied stats into /app/env/dataset/genposter_5000_images_stats.npy"; \
+    else \
+        echo "Warning: genposter_5000_images_stats.npy not found in build context."; \
+    fi
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/env/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/env/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+ENV PYTHONUNBUFFERED=1
+# Gradio Web UI at /web (same pattern as snake_env server)
+ENV ENABLE_WEB_INTERFACE=true
+
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -fsS http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,12 +1,231 @@
 ---
-title: Layoutenv
-emoji: 🐠
-colorFrom: blue
-colorTo: green
+title: LayoutEnv Environment Server
+emoji: 🎭
+colorFrom: green
+colorTo: yellow
 sdk: docker
 pinned: false
-license: apache-2.0
-short_description: OpenEnv environment for poster layout refinement via RL
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# LayoutEnv: Poster Layout Refinement Environment
+
+`layoutenv` is a practical OpenEnv benchmark for iterative poster/layout cleanup.
+An agent receives a noisy layout and improves it step-by-step using discrete edit actions:
+`MOVE`, `RESIZE`, `ALIGN`, `SNAP`, and `NO_OP`.
+
+The task is designed for:
+- spatial reasoning across multiple elements
+- optimization with shaped rewards
+- LLM and VLM agent evaluation on iterative improvement loops
+
+## Task Overview
+
+Each episode starts from a perturbed sample with normalized geometry.
+At every step, the agent picks:
+- target element (`element_id`)
+- action type (`MOVE`, `RESIZE`, `ALIGN`, `SNAP`, `NO_OP`)
+- action parameter (`UP`, `LEFT`, `CENTER_X`, `GRID`, etc.)
+- optional magnitude for `MOVE`/`RESIZE` (`SMALL`, `MEDIUM`, `LARGE`)
+
+The episode ends when:
+- max step budget is reached, or
+- agent emits `NO_OP` (treat as stop)
+
+## Quick Start
+
+The simplest way to use the environment is through the `LayoutEnv` client:
+
+```python
+from layoutenv import LayoutAction, LayoutEnv
+
+async def run_example() -> None:
+    env = await LayoutEnv.from_docker_image("layoutenv:latest")
+    try:
+        result = await env.reset(mode="llm")
+        print("Initial Q:", result.observation.quality_score)
+        result = await env.step(LayoutAction(
+            element_id=0,
+            action="ALIGN",
+            param="CENTER_X",
+            magnitude="MEDIUM",
+        ))
+        print("Reward:", result.reward, "Done:", result.done)
+    finally:
+        await env.close()
+
+import asyncio
+asyncio.run(run_example())
+```
+
+If you prefer a sync client flow, instantiate with `LayoutEnv(base_url=...)`
+and call the synchronous methods in your own wrapper.
+
+`LayoutEnv.from_docker_image(...)` handles:
+- starting the container
+- waiting for readiness
+- connecting the client
+- container cleanup on `close()`
+
+## Build the Docker Image
+
+From repo root:
+
+```bash
+docker build -t layoutenv:latest -f layoutenv/server/Dockerfile .
+```
+
+From `layoutenv/` directory:
+
+```bash
+docker build -t layoutenv:latest -f server/Dockerfile .
+```
+
+## Run the Server (Volume-Mounted Dataset)
+
+The current runtime expects dataset assets at `/app/env/dataset` in-container.
+Recommended run command from repo root:
+
+```bash
+docker run --rm -d \
+  --name layoutenv-server \
+  -p 8000:8000 \
+  -v "$(pwd)/dataset:/app/env/dataset" \
+  layoutenv:latest
+```
+
+Verify endpoints:
+
+```bash
+curl -s http://localhost:8000/health
+curl -s -X POST -H "Content-Type: application/json" -d '{}' http://localhost:8000/reset
+```
+
+Stop:
+
+```bash
+docker stop layoutenv-server
+```
+
+## Usage
+
+Submission baseline script is root `inference.py` (required location).
+It uses `LayoutEnv.from_docker_image()` and emits evaluator-friendly stdout:
+- `[START] ...`
+- `[STEP] ...`
+- `[END] ...`
+
+### LLM run
+
+```bash
+API_BASE_URL=... MODEL_NAME=... HF_TOKEN=... \
+IMAGE_NAME=layoutenv:latest python inference.py --seed 42
+```
+
+### VLM easy-task smoke
+
+```bash
+API_BASE_URL=... MODEL_NAME=... HF_TOKEN=... \
+IMAGE_NAME=layoutenv:latest python inference.py --mode vlm --task easy --max-steps 5 --seed 42
+```
+
+## Environment Details
+
+### Action (`LayoutAction`)
+
+Fields:
+- `element_id` (int): target element index
+- `action` (str): `MOVE` | `RESIZE` | `ALIGN` | `SNAP` | `NO_OP`
+- `param` (str):
+  - `MOVE`: `UP`, `DOWN`, `LEFT`, `RIGHT`
+  - `RESIZE`: `WIDER`, `NARROWER`, `TALLER`, `SHORTER`
+  - `ALIGN`: `LEFT`, `CENTER_X`, `RIGHT`, `TOP`, `CENTER_Y`, `BOTTOM`
+  - `SNAP`: `GRID`
+  - `NO_OP`: `NONE`
+- `magnitude` (str): `SMALL`, `MEDIUM`, `LARGE` (used for `MOVE`/`RESIZE`)
+
+### Observation (`LayoutObservation`)
+
+Per-step payload includes:
+- `canvas`: normalized canvas (`width=1.0`, `height=1.0`)
+- `elements`: list of `{id, type, cx, cy, w, h, font_size}`
+- `metrics`: layout metrics:
+  - `overlap` (lower better)
+  - `boundary` (lower better)
+  - `alignment` (higher better)
+  - `spacing` (higher better)
+  - `plausibility` (higher better)
+- `quality_score`: composite quality value `Q`
+- `initial_quality_score`: `Q` at reset
+- `step`, `max_steps`
+- optional VLM fields (`image_path`, `rendered_image_base64`)
+- optional `text_feedback`
+
+### State (`LayoutState`)
+
+Server state tracks:
+- `episode_id`, `step_count`
+- current `elements`
+- `previous_quality`, `initial_quality`
+- VLM context (`current_image_rel`, `dataset_json_path`)
+
+### Reward
+
+Step reward is shaped by quality improvements:
+- `reward = REWARD_SCALE * (Q_t - Q_{t-1}) + STEP_PENALTY`
+- invalid actions incur a penalty
+- terminal shaping applies at episode end
+
+This gives dense training/evaluation signal, not only terminal success.
+
+## Task Grading
+
+Deterministic grading logic is implemented in `layoutenv/grader.py`:
+- `q_delta = final_q - initial_q`
+- `score = clamp((q_delta + 2.0) / 4.0, 0, 1)`
+- task-specific success thresholds:
+  - `easy >= 0.05`
+  - `medium >= 0.10`
+  - `hard >= 0.15`
+
+Note: score is intentionally clamped to `[0, 1]` for stable reporting.
+
+## Deploy to Hugging Face Spaces
+
+From `layoutenv/`:
+
+```bash
+openenv push
+```
+
+Or specify repo:
+
+```bash
+openenv push --repo-id <namespace>/<space-name>
+```
+
+After deploy, verify:
+- `POST /reset` returns 200
+- `/docs` is reachable
+- `/health` is healthy
+
+## Project Structure
+
+```text
+layoutenv/
+├── __init__.py
+├── client.py
+├── grader.py
+├── models.py
+├── openenv.yaml
+├── pyproject.toml
+├── README.md
+└── server/
+    ├── app.py
+    ├── layout_environment.py
+    ├── metrics.py
+    └── Dockerfile
+```

__init__.py

@@ -0,0 +1,12 @@
+from .client import LayoutEnv
+from .grader import TaskGrade, grade_episode
+from .models import LayoutAction, LayoutObservation, LayoutState
+
+__all__ = [
+    "LayoutAction",
+    "LayoutObservation",
+    "LayoutState",
+    "LayoutEnv",
+    "TaskGrade",
+    "grade_episode",
+]

client.py

@@ -0,0 +1,63 @@
+"""
+Layout Environment Client.
+
+HTTP / WebSocket client for interacting with a remote LayoutEnvironment server.
+"""
+
+from typing import Dict
+
+
+from openenv.core.client_types import StepResult  # noqa: F401
+from openenv.core.env_client import EnvClient
+from .models import LayoutAction, LayoutObservation, LayoutState
+
+
+class LayoutEnv(EnvClient[LayoutAction, LayoutObservation, LayoutState]):
+    """
+    Client for the Layout Environment.
+
+    Example:
+        >>> with LayoutEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.quality_score)
+        ...     result = client.step(LayoutAction(
+        ...         element_id=0, action="MOVE", param="UP", magnitude="LARGE",
+        ...     ))
+    """
+
+    def _step_payload(self, action: LayoutAction) -> Dict:
+        return action.to_dict()
+
+    def _parse_result(self, payload: Dict) -> StepResult[LayoutObservation]:
+        if "observation" not in payload:
+            raise ValueError(f"Invalid response: {payload}")
+
+        obs_data = payload["observation"]
+
+        observation = LayoutObservation(
+            canvas=obs_data.get("canvas", {"width": 1.0, "height": 1.0}),
+            elements=obs_data.get("elements", []),
+            metrics=obs_data.get("metrics", {}),
+            step=obs_data.get("step", 0),
+            max_steps=obs_data.get("max_steps", 20),
+            quality_score=obs_data.get("quality_score", 0.0),
+            initial_quality_score=obs_data.get("initial_quality_score", 0.0),
+            text_feedback=obs_data.get("text_feedback"),
+            done=payload.get("done", False),
+            reward=payload.get("reward", 0.0),
+            metadata=obs_data.get("metadata", {}),
+            image_path=obs_data.get("image_path"),
+            rendered_image_base64=obs_data.get("rendered_image_base64"),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", 0.0),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> LayoutState:
+        return LayoutState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

grader.py

@@ -0,0 +1,57 @@
+"""
+Deterministic task graders for layoutenv benchmark tasks.
+"""
+
+from dataclasses import dataclass
+
+
+TASK_SUCCESS_Q_DELTA = {
+    "easy": 0.05,
+    "medium": 0.1,
+    "hard": 0.15,
+}
+
+
+@dataclass(frozen=True)
+class TaskGrade:
+    task_id: str
+    score: float
+    success: bool
+    q_delta: float
+
+
+def _clamp01(x: float) -> float:
+    return min(max(x, 0.0), 1.0)
+
+
+def score_from_q_delta(q_delta: float) -> float:
+    """
+    Map quality delta to [0, 1] score.
+
+    The linear map is intentionally clamped so large outliers do not
+    destabilize reported leaderboard-compatible scores.
+    """
+    return _clamp01((q_delta + 2.0) / 4.0)
+
+
+def success_from_q_delta(task_id: str, q_delta: float, default_threshold: float) -> bool:
+    """
+    Determine success using task-specific threshold if available.
+    """
+    threshold = TASK_SUCCESS_Q_DELTA.get(task_id, default_threshold)
+    return q_delta >= threshold
+
+
+def grade_episode(
+    task_id: str,
+    initial_quality: float,
+    final_quality: float,
+    success_q_delta: float = 0.1,
+) -> TaskGrade:
+    q_delta = final_quality - initial_quality
+    return TaskGrade(
+        task_id=task_id,
+        score=score_from_q_delta(q_delta),
+        success=success_from_q_delta(task_id, q_delta, success_q_delta),
+        q_delta=q_delta,
+    )

models.py

@@ -0,0 +1,126 @@
+"""
+Data models for the Layout Environment.
+
+The layout environment is an RL environment for training language models
+to iteratively improve UI poster layouts via discrete actions.
+"""
+
+from typing import Dict, List, Optional
+
+from pydantic import Field
+from openenv.core.env_server.types import Action, Observation, State
+
+
+ACTIONS = {
+    "MOVE": ["UP", "DOWN", "LEFT", "RIGHT"],
+    "RESIZE": ["WIDER", "NARROWER", "TALLER", "SHORTER"],
+    "ALIGN": ["LEFT", "CENTER_X", "RIGHT", "TOP", "CENTER_Y", "BOTTOM"],
+    "SNAP": ["GRID"],
+    "NO_OP": ["NONE"],
+}
+
+MAGNITUDES = {
+    "SMALL": 0.01,
+    "MEDIUM": 0.05,
+    "LARGE": 0.1,
+}
+
+ALL_VALID_PARAMS = {param for params in ACTIONS.values() for param in params}
+
+
+class LayoutAction(Action):
+    """
+    Action for the Layout environment. The agent selects one element and applies one operation per step.
+
+    Attributes:
+        element_id: Index of the target element in the layout.
+        action: One of "MOVE", "RESIZE", "ALIGN", "SNAP", "NO_OP".
+        param: Parameter for the action (e.g. "UP", "WIDER", "CENTER_X").
+        magnitude: Step size for MOVE/RESIZE — "SMALL" (0.01), "MEDIUM" (0.05),
+                   "LARGE" (0.10). Ignored for other action types.
+    """
+
+    element_id: int = Field(default=0, description="Target element index")
+    action: str = Field(default="NO_OP", description="Action type")
+    param: str = Field(default="NONE", description="Action parameter")
+    magnitude: str = Field(default="MEDIUM", description="Step size for MOVE/RESIZE")
+
+    def is_valid(self, num_elements: int) -> bool:
+        # Validate action type
+        if self.action not in ACTIONS:
+            return False
+
+        # Validate param for the given action
+        valid_params = ACTIONS[self.action]
+        if self.param not in valid_params:
+            return False
+
+        # Validate element index (except NO_OP)
+        if self.action != "NO_OP":
+            if not isinstance(self.element_id, int):
+                return False
+            if not (0 <= self.element_id < num_elements):
+                return False
+
+        if self.action in ["MOVE", "RESIZE"] and self.magnitude not in MAGNITUDES:
+            return False
+
+        return True
+
+    def to_dict(self) -> Dict:
+        return {
+            "element_id": self.element_id,
+            "action": self.action,
+            "param": self.param,
+            "magnitude": self.magnitude,
+        }
+
+
+class LayoutObservation(Observation):
+    """
+    Observation from the Layout environment.
+
+    All float coordinates are in normalised [0, 1] space and rounded to 3 decimal places to minimise LM token count.
+
+    Attributes:
+        canvas: Canvas dimensions (always {"width": 1.0, "height": 1.0}).
+        elements: Current element list with id, type, cx, cy, w, h, font_size.
+        metrics: Per-metric scores (overlap, boundary, alignment, spacing, plausibility).
+        step: Current step within the episode.
+        max_steps: Maximum steps allowed in this episode.
+        quality_score: Composite Q(state) — higher is better.
+        initial_quality_score: Q(state_0) at the start of this episode.
+        image_path: In VLM mode, path relative to the dataset JSON to the background (e.g. ``images/id_bg.png``).
+        rendered_image_base64: Optional in VLM mode. PNG of the background with
+            layout boxes and labels, base64-encoded, when server-side rendering
+            is enabled for the episode.
+    """
+
+    canvas: Dict = Field(default_factory=lambda: {"width": 1.0, "height": 1.0})
+    elements: List[Dict] = Field(default_factory=list)
+    metrics: Dict = Field(default_factory=dict)
+
+    step: int = 0
+    max_steps: int = 500
+
+    quality_score: float = 0.0
+    initial_quality_score: float = 0.0
+
+    text_feedback: Optional[str] = None
+
+    image_path: Optional[str] = None          # background image path
+    rendered_image_base64: Optional[str] = None  # layout rendered on background (visual prompt)
+    
+class LayoutState(State):
+    """
+    State of the Layout environment.
+    """
+    # Base State provides: episode_id, step_count
+    elements: List[Dict] = Field(default_factory=list)
+    
+    # Quality tracking (for delta calculation)
+    previous_quality: float = 0.0  # Q(t-1)
+    initial_quality: float = 0.0   # Q(0)
+    
+    current_image_rel: Optional[str] = None
+    dataset_json_path: Optional[str] = None

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: layoutenv
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

openenv_layoutenv.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: openenv-layoutenv
+Version: 0.1.0
+Summary: Layout refinement RL environment for OpenEnv
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_layoutenv.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+./__init__.py
+./client.py
+./models.py
+openenv_layoutenv.egg-info/PKG-INFO
+openenv_layoutenv.egg-info/SOURCES.txt
+openenv_layoutenv.egg-info/dependency_links.txt
+openenv_layoutenv.egg-info/entry_points.txt
+openenv_layoutenv.egg-info/requires.txt
+openenv_layoutenv.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/layout_environment.py
+server/metrics.py

openenv_layoutenv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_layoutenv.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = layoutenv.server.app:main

openenv_layoutenv.egg-info/requires.txt

@@ -0,0 +1,10 @@
+openenv-core[core]>=0.2.1
+fastapi>=0.115.0
+pydantic>=2.0.0
+uvicorn[standard]>=0.24.0
+numpy>=1.24.0
+pillow>=10.0.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

openenv_layoutenv.egg-info/top_level.txt

@@ -0,0 +1 @@
+layoutenv

pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-layoutenv"
+version = "0.1.0"
+description = "Layout refinement RL environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core[core]>=0.2.1",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn[standard]>=0.24.0",
+    "numpy>=1.24.0",
+    "pillow>=10.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+server = "layoutenv.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["layoutenv", "layoutenv.server"]
+package-dir = { "layoutenv" = ".", "layoutenv.server" = "server" }

server/__init__.py

@@ -0,0 +1,3 @@
+from .layout_environment import LayoutEnvironment
+
+__all__ = ["LayoutEnvironment"]

server/app.py

@@ -0,0 +1,54 @@
+"""
+FastAPI application for the Layout Environment.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+The mode (llm/vlm) and text_feedback flag are set per-episode via reset().
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e: 
+    raise ImportError(
+        "openenv is required for the web interface. "
+        "Install dependencies with 'uv sync'"
+    ) from e
+
+try:
+    from ..models import LayoutAction, LayoutObservation
+    from .layout_environment import LayoutEnvironment
+except ImportError:
+    from models import LayoutAction, LayoutObservation
+    from server.layout_environment import LayoutEnvironment
+
+app = create_app(
+    LayoutEnvironment,
+    LayoutAction,
+    LayoutObservation,
+    env_name="layoutenv",
+    max_concurrent_envs=1,
+)
+
+
+def main() -> None:
+    """Entry point for direct execution via ``uv run --project . server``."""
+    import argparse
+    import uvicorn
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--host", type=str, default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    uvicorn.run(app, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

server/layout_environment.py

@@ -0,0 +1,666 @@
+"""
+Layout Environment Implementation.
+
+An RL environment for iteratively refining UI poster layouts.
+The agent receives a layout and must improve it using discrete actions
+(MOVE, RESIZE, ALIGN, SNAP, NO_OP).
+
+Perturbations are the responsibility of the caller (e.g. inference.py);
+this environment is agnostic to how the initial layout was produced.
+"""
+from __future__ import annotations
+import base64
+import io
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+from uuid import uuid4
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+
+from openenv.core.env_server.interfaces import Environment
+
+try:
+    from ..models import ACTIONS, MAGNITUDES, LayoutAction, LayoutObservation, LayoutState
+except (ImportError, ModuleNotFoundError):
+    from models import ACTIONS, MAGNITUDES, LayoutAction, LayoutObservation, LayoutState
+
+from .metrics import (
+    _axis_value,
+    _to_ltrb,
+    compute_all_metrics,
+    quality_score,
+)
+
+
+# Single baked-in training-free layout (normalised bboxes).
+# Training code should load the full dataset and pass ``sample=`` into ``reset``.
+DEFAULT_LAYOUT_SAMPLE: Dict[str, Any] = {
+    "id": 0,
+    "canvas_size": [3556, 2000],
+    "elements": [
+        {
+            "type": "Title",
+            "text": "Demo",
+            "bbox": [0.2, 0.15, 0.8, 0.25],
+            "font_size": 120.0,
+        },
+        {
+            "type": "Bodytext",
+            "text": "Stateless default episode",
+            "bbox": [0.15, 0.4, 0.85, 0.55],
+            "font_size": 90.0,
+        },
+        {
+            "type": "Website",
+            "text": "example.com",
+            "bbox": [0.35, 0.85, 0.65, 0.92],
+            "font_size": 48.0,
+        },
+    ],
+}
+
+
+def _bbox_to_centre(bbox: List[float]) -> Dict[str, float]:
+    x1, y1, x2, y2 = bbox
+    return {
+        "cx": (x1 + x2) / 2,
+        "cy": (y1 + y2) / 2,
+        "w": x2 - x1,
+        "h": y2 - y1,
+    }
+
+
+def _default_stats_from_sample(sample: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Per-element-type Gaussian plausibility priors matching sample's ground truth.
+    Shared isotropic covariance (loose prior) so perturbed layouts still score smoothly.
+    """
+    inv_cov = np.linalg.inv((0.1**2) * np.eye(5) + 1e-6 * np.eye(5))
+    out: Dict[str, Any] = {}
+    for elem in sample.get("elements", []):
+        etype = elem.get("type")
+        if not etype or etype in out:
+            continue
+        centre = _bbox_to_centre(elem["bbox"])
+        canvas_h = float(sample["canvas_size"][1])
+        fs_raw = float(elem.get("font_size", 0.0) or 0.0)
+        fs_norm = fs_raw / canvas_h if canvas_h > 0 else 0.0
+        mu = np.array(
+            [centre["cx"], centre["cy"], centre["w"], centre["h"], fs_norm],
+            dtype=np.float64,
+        )
+        out[etype] = {"mu": mu, "cov_inv": inv_cov}
+    return out
+
+
+DEFAULT_STATS: Dict[str, Any] = _default_stats_from_sample(DEFAULT_LAYOUT_SAMPLE)
+
+
+def _sample_to_elements(sample: Dict) -> List[Dict]:
+    """Convert a dataset sample to the internal element list."""
+    canvas_w, canvas_h = sample["canvas_size"]
+    elements = []
+    for i, elem in enumerate(sample.get("elements", [])):
+        centre = _bbox_to_centre(elem["bbox"])
+        fs_raw = float(elem.get("font_size", 0.0) or 0.0)
+        fs_norm = fs_raw / canvas_h if canvas_h > 0 else 0.0
+        elements.append({
+            "id": i,
+            "type": elem.get("type", "unknown"),
+            "text": elem.get("text", ""),
+            "cx": centre["cx"],
+            "cy": centre["cy"],
+            "w": centre["w"],
+            "h": centre["h"],
+            "font_size": fs_norm,
+        })
+    return elements
+
+
+# Action application
+def _apply_action(
+    elements: List[Dict],
+    action: LayoutAction,
+) -> None:
+    """Mutate elements in-place according to action"""
+    eid = action.element_id
+    act = action.action
+    param = action.param
+    delta = MAGNITUDES.get(action.magnitude, MAGNITUDES["MEDIUM"])
+    elem = elements[eid]
+
+    if act == "MOVE":
+        if param == "UP":
+            elem["cy"] -= delta
+        elif param == "DOWN":
+            elem["cy"] += delta
+        elif param == "LEFT":
+            elem["cx"] -= delta
+        elif param == "RIGHT":
+            elem["cx"] += delta
+
+    elif act == "RESIZE":
+        if param == "WIDER":
+            elem["w"] += delta
+        elif param == "NARROWER":
+            elem["w"] -= delta
+        elif param == "TALLER":
+            elem["h"] += delta
+        elif param == "SHORTER":
+            elem["h"] -= delta
+        # Keep geometry valid for downstream metric computations.
+        elem["w"] = max(0.01, min(1.0, elem["w"]))
+        elem["h"] = max(0.01, min(1.0, elem["h"]))
+
+    elif act == "ALIGN":
+        _apply_align(elements, eid, param)
+
+    elif act == "SNAP":
+        grid = 0.05
+        elem["cx"] = round(elem["cx"] / grid) * grid
+        elem["cy"] = round(elem["cy"] / grid) * grid
+
+
+_PARAM_TO_AXIS = {
+    "LEFT": "left", "RIGHT": "right", "CENTER_X": "cx",
+    "TOP": "top", "BOTTOM": "bottom", "CENTER_Y": "cy",
+}
+
+
+def _apply_align(
+    elements: List[Dict],
+    eid: int,
+    param: str,
+    threshold: float = 0.15,
+) -> None:
+    """Nearest-neighbour inter-element alignment with canvas fallback."""
+    target = elements[eid]
+    others = [e for e in elements if e["id"] != target["id"]]
+    axis = _PARAM_TO_AXIS.get(param, param.lower())
+
+    target_val = _axis_value(target, axis)
+    best_val: Optional[float] = None
+    best_dist = float("inf")
+
+    for other in others:
+        other_val = _axis_value(other, axis)
+        dist = abs(target_val - other_val)
+        if dist < best_dist:
+            best_dist = dist
+            best_val = other_val
+
+    if best_val is not None and best_dist < threshold:
+        snap_to = best_val
+    else:
+        canvas_anchors = {
+            "left": 0.0, "right": 1.0, "cx": 0.5,
+            "top": 0.0, "bottom": 1.0, "cy": 0.5,
+        }
+        snap_to = canvas_anchors[axis]
+
+    _set_axis_value(target, axis, snap_to)
+
+
+def _set_axis_value(e: Dict, axis: str, val: float) -> None:
+    hw, hh = e["w"] / 2, e["h"] / 2
+    if axis == "left":
+        e["cx"] = val + hw
+    elif axis == "right":
+        e["cx"] = val - hw
+    elif axis == "cx":
+        e["cx"] = val
+    elif axis == "top":
+        e["cy"] = val + hh
+    elif axis == "bottom":
+        e["cy"] = val - hh
+    elif axis == "cy":
+        e["cy"] = val
+
+
+
+# Round helpers
+def _round_elements(elements: List[Dict], dp: int = 3) -> List[Dict]:
+    """Return a copy with floats rounded for observation output."""
+    out = []
+    for e in elements:
+        out.append({
+            "id": e["id"],
+            "type": e["type"],
+            "cx": round(e["cx"], dp),
+            "cy": round(e["cy"], dp),
+            "w": round(e["w"], dp),
+            "h": round(e["h"], dp),
+            "font_size": round(e["font_size"], dp),
+        })
+    return out
+
+
+def _resolve_media_path(dataset_json_path: str, relative_path: str) -> Path:
+    """
+    Resolve e.g. images/0_bg.png relative to the dataset JSON directory.
+    This supports volume-mounted datasets when the server container can access
+    the dataset path.
+    """
+    return Path(dataset_json_path).resolve().parent / relative_path
+
+
+def _render_layout_on_background(
+    bg_path: str | Path | None,
+    elements: List[Dict],
+    bg_pil: Image.Image | None = None,
+) -> Image.Image:
+    """
+    Draw normalized layout (cx, cy, w, h in [0, 1]) on top of the background.
+    Filled rectangles use distinct colors; label = type and truncated text.
+    If bg_path is None or missing, a neutral placeholder canvas is used.
+    bg_pil allows passing an already-loaded PIL image (e.g. decoded from
+    base64) so the environment can work without filesystem access.
+    """
+    if bg_pil is not None:
+        base = bg_pil.convert("RGBA")
+        w_px, h_px = base.size
+    elif bg_path is None:
+        w_px, h_px = 1024, 1024
+        base = Image.new("RGBA", (w_px, h_px), (245, 245, 245, 255))
+    else:
+        path = Path(bg_path)
+        if not path.is_file():
+            w_px, h_px = 1024, 1024
+            base = Image.new("RGBA", (w_px, h_px), (245, 245, 245, 255))
+        else:
+            with Image.open(path) as img:
+                base = img.convert("RGBA")
+            w_px, h_px = base.size
+
+    overlay = Image.new("RGBA", (w_px, h_px), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(overlay)
+
+    palette = [
+        (255, 99, 71, 90),
+        (60, 179, 113, 90),
+        (65, 105, 225, 90),
+        (238, 130, 238, 90),
+        (255, 215, 0, 90),
+        (0, 206, 209, 90),
+        (255, 140, 0, 90),
+        (147, 112, 219, 90),
+    ]
+    line_w = max(1, min(w_px, h_px) // 100)
+
+    for i, e in enumerate(elements):
+        cx, cy, ew, eh = (
+            float(e["cx"]),
+            float(e["cy"]),
+            float(e["w"]),
+            float(e["h"]),
+        )
+        x1 = int((cx - ew / 2) * w_px)
+        y1 = int((cy - eh / 2) * h_px)
+        x2 = int((cx + ew / 2) * w_px)
+        y2 = int((cy + eh / 2) * h_px)
+        x1 = max(0, min(x1, w_px - 1))
+        y1 = max(0, min(y1, h_px - 1))
+        x2 = max(0, min(x2, w_px - 1))
+        y2 = max(0, min(y2, h_px - 1))
+        if x2 <= x1:
+            x2 = min(w_px - 1, x1 + 1)
+        if y2 <= y1:
+            y2 = min(h_px - 1, y1 + 1)
+
+        fill = palette[i % len(palette)]
+        outline = (*fill[:3], 255)
+        draw.rectangle([x1, y1, x2, y2], fill=fill, outline=outline, width=line_w)
+
+    composed = Image.alpha_composite(base, overlay)
+    d2 = ImageDraw.Draw(composed)
+
+    font_size = max(8, min(w_px, h_px) // 18)
+    font: ImageFont.FreeTypeFont | ImageFont.ImageFont
+    try:
+        font = ImageFont.truetype(
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", font_size
+        )
+    except OSError:
+        try:
+            font = ImageFont.truetype("DejaVuSans.ttf", font_size)
+        except OSError:
+            font = ImageFont.load_default()
+
+    for i, e in enumerate(elements):
+        cx, cy, ew, eh = (
+            float(e["cx"]),
+            float(e["cy"]),
+            float(e["w"]),
+            float(e["h"]),
+        )
+        x1 = int((cx - ew / 2) * w_px)
+        y1 = int((cy - eh / 2) * h_px)
+        x2 = int((cx + ew / 2) * w_px)
+        y2 = int((cy + eh / 2) * h_px)
+        x1 = max(0, min(x1, w_px - 1))
+        y1 = max(0, min(y1, h_px - 1))
+        x2 = max(0, min(x2, w_px - 1))
+        y2 = max(0, min(y2, h_px - 1))
+        if x2 <= x1:
+            x2 = min(w_px - 1, x1 + 1)
+        if y2 <= y1:
+            y2 = min(h_px - 1, y1 + 1)
+
+        raw_text = str(e.get("text", "") or "").strip()
+        label = str(e.get("type", "unknown") or "unknown")
+        if raw_text:
+            label = f"{label}: {raw_text}"
+        if len(label) > 48:
+            label = label[:45] + "..."
+
+        tb = d2.textbbox((0, 0), label, font=font)
+        tw, th = tb[2] - tb[0], tb[3] - tb[1]
+        tx = x1 + max(2, (x2 - x1 - tw) // 2)
+        ty = y1 + max(2, (y2 - y1 - th) // 2)
+
+        d2.text(
+            (tx, ty),
+            label,
+            font=font,
+            fill=(255, 255, 255, 255),
+            stroke_width=max(1, line_w // 2),
+            stroke_fill=(0, 0, 0, 255),
+        )
+
+    if composed.mode == "RGBA":
+        rgb = Image.new("RGB", composed.size, (255, 255, 255))
+        rgb.paste(composed, mask=composed.split()[3])
+        return rgb
+    return composed.convert("RGB")
+
+
+def _pil_to_png_base64(img: Image.Image) -> str:
+    buf = io.BytesIO()
+    img.save(buf, format="PNG", optimize=True)
+    return base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def _generate_text_feedback(
+    delta_q: float,
+    metrics: Dict[str, float],
+    elements: List[Dict],
+) -> str:
+    """
+    Produce a concise, actionable text hint from the current metrics.
+
+    The feedback tells the model (a) whether it improved, and (b) which
+    metric to target next with a concrete suggestion.
+    """
+    parts: List[str] = []
+
+    if delta_q > 0.01:
+        parts.append(f"Quality improved by +{delta_q:.3f}. Keep going.")
+    elif delta_q < -0.01:
+        parts.append(f"Quality dropped by {delta_q:.3f}. Undo or try a different action.")
+    else:
+        parts.append("Negligible change. Try a different element or direction.")
+
+    overlap = metrics.get("overlap", 0.0)
+    boundary = metrics.get("boundary", 0.0)
+    alignment = metrics.get("alignment", 1.0)
+    spacing = metrics.get("spacing", 1.0)
+
+    penalties = {"overlap": overlap, "boundary": boundary}
+    worst_penalty_name = max(penalties, key=penalties.get)  # type: ignore[arg-type]
+    worst_penalty_val = penalties[worst_penalty_name]
+
+    rewards = {"alignment": alignment, "spacing": spacing}
+    worst_reward_name = min(rewards, key=rewards.get)  # type: ignore[arg-type]
+    worst_reward_val = rewards[worst_reward_name]
+
+    if worst_penalty_val > 0.05:
+        if worst_penalty_name == "overlap":
+            parts.append(
+                f"Overlap is high ({overlap:.3f}). "
+                "MOVE overlapping elements apart or RESIZE them smaller."
+            )
+        else:
+            oob = [
+                e["id"] for e in elements
+                if _is_out_of_bounds(e)
+            ]
+            if oob:
+                parts.append(
+                    f"Boundary violation ({boundary:.3f}) on element(s) {oob}. "
+                    "MOVE them inward or RESIZE them smaller."
+                )
+            else:
+                parts.append(
+                    f"Boundary penalty ({boundary:.3f}). "
+                    "Some elements may be near the edge; MOVE inward."
+                )
+    elif worst_reward_val < 0.5:
+        if worst_reward_name == "alignment":
+            parts.append(
+                f"Alignment is low ({alignment:.3f}). "
+                "Use ALIGN (CENTER_X, LEFT, etc.) to snap edges together."
+            )
+        else:
+            parts.append(
+                f"Spacing is uneven ({spacing:.3f}). "
+                "MOVE elements to equalise vertical/horizontal gaps."
+            )
+
+    return " ".join(parts)
+
+
+def _is_out_of_bounds(e: Dict) -> bool:
+    hw, hh = e["w"] / 2, e["h"] / 2
+    l, t, r, b = e["cx"] - hw, e["cy"] - hh, e["cx"] + hw, e["cy"] + hh
+    return l < 0 or t < 0 or r > 1 or b > 1
+
+
+# Environment
+INVALID_ACTION_PENALTY = -0.5
+STEP_PENALTY = -0.05      
+REWARD_SCALE = 10.0
+TERMINAL_BONUS_SCALE = 5.0
+TERMINAL_PENALTY = -1.0
+# Align terminal shaping with the easiest grader delta threshold.
+Q_DELTA_THRESHOLD = 0.05
+
+
+class LayoutEnvironment(Environment):
+    """
+    An RL environment for layout refinement.
+
+    The caller is responsible for producing the initial layout (e.g. by
+    perturbing a ground-truth sample) and passing it via reset(sample=...).
+
+    Args:
+        max_steps: Maximum actions per episode.
+        weights: Optional metric weight overrides for Q.
+        stats: Plausibility metric config (e.g. loaded from *_stats.npy);
+               immutable for the lifetime of this env instance. If omitted,
+               DEFAULT_STATS (derived from DEFAULT_LAYOUT_SAMPLE) is used.
+    """
+
+    # This environment stores episode-specific fields on the instance.
+    # Do not advertise shared-instance concurrent session safety.
+    SUPPORTS_CONCURRENT_SESSIONS: bool = False
+
+    def __init__(
+        self,
+        max_steps: int = 500,
+        weights: Optional[Dict[str, float]] = None,
+        stats: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__()
+        self._state = LayoutState(episode_id=str(uuid4()), step_count=0)
+
+        self._max_steps = max_steps
+        self._weights = weights
+        self._stats: Dict[str, Any] = (
+            DEFAULT_STATS if stats is None else stats
+        )
+        self._mode: Literal["llm", "vlm"] = "llm"
+        self._text_feedback: bool = True
+        self._render_image_in_observation: bool = True
+
+    def _build_observation(
+        self,
+        step_num: int,
+        done: bool,
+        reward: float | int,
+        metrics: Dict,
+        q: float,
+    ) -> LayoutObservation:
+        image_path: Optional[str] = None
+        rendered_b64: Optional[str] = None
+        if self._mode == "vlm":
+            image_path = self._state.current_image_rel
+        if self._mode == "vlm" and self._render_image_in_observation:
+            resolved_bg_path: Optional[Path] = None
+            bg_img: Image.Image | None = None
+
+            inline_b64 = getattr(self._state, "_bg_image_base64", None)
+            if inline_b64:
+                with Image.open(io.BytesIO(base64.b64decode(inline_b64))) as decoded:
+                    bg_img = decoded.convert("RGBA")
+            elif self._state.current_image_rel and self._state.dataset_json_path:
+                resolved_bg_path = _resolve_media_path(
+                    self._state.dataset_json_path, self._state.current_image_rel
+                )
+                if resolved_bg_path.is_file():
+                    with Image.open(resolved_bg_path) as loaded:
+                        bg_img = loaded.convert("RGBA")
+
+            rendered = _render_layout_on_background(
+                resolved_bg_path, self._state.elements, bg_pil=bg_img
+            )
+            rendered_b64 = _pil_to_png_base64(rendered)
+
+        prev_q = self._state.previous_quality
+        delta_q = q - prev_q
+
+        feedback: Optional[str] = None
+        if self._text_feedback:
+            feedback = _generate_text_feedback(delta_q, metrics, self._state.elements)
+
+        obs = LayoutObservation(
+            canvas={"width": 1.0, "height": 1.0},
+            elements=_round_elements(self._state.elements),
+            metrics=metrics,
+            step=step_num,
+            max_steps=self._max_steps,
+            quality_score=q,
+            initial_quality_score=self._state.initial_quality,
+            text_feedback=feedback,
+            reward=reward,
+            done=done,
+            image_path=image_path,
+            rendered_image_base64=rendered_b64,
+        )
+        return obs
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        *,
+        sample: Optional[Dict[str, Any]] = None,
+        dataset_json_path: Optional[str] = None,
+        background_image_base64: Optional[str] = None,
+        mode: Optional[Literal["llm", "vlm"]] = None,
+        text_feedback: Optional[bool] = None,
+        render_image_in_observation: Optional[bool] = None,
+        **kwargs: Any,
+    ) -> LayoutObservation:
+        # Intentionally avoid touching module-global RNG state here.
+        # Seeding happens client-side for perturbation reproducibility.
+
+        if mode is not None:
+            self._mode = mode
+        if text_feedback is not None:
+            self._text_feedback = text_feedback
+        if render_image_in_observation is not None:
+            self._render_image_in_observation = render_image_in_observation
+
+        chosen = sample if sample is not None else DEFAULT_LAYOUT_SAMPLE
+
+        if self._mode == "vlm" and not chosen.get("image_path") and not background_image_base64:
+            raise ValueError(
+                "VLM mode requires sample['image_path'] or background_image_base64. "
+                "Pass a sample from your dataset on reset."
+            )
+
+        current_image_rel = (
+            chosen.get("image_path") if self._mode == "vlm" else None
+        )
+
+        elements = _sample_to_elements(chosen)
+
+        self._state = LayoutState(
+            episode_id=episode_id if episode_id is not None else str(uuid4()),
+            step_count=0,
+            elements=elements,
+            previous_quality=0.0,
+            initial_quality=0.0,
+            current_image_rel=current_image_rel,
+            dataset_json_path=dataset_json_path,
+        )
+
+        if background_image_base64:
+            self._state._bg_image_base64 = background_image_base64
+
+        metrics = compute_all_metrics(self._state.elements, self._stats)
+        q = quality_score(metrics, self._weights)
+        self._state.previous_quality = q
+        self._state.initial_quality = q
+
+        return self._build_observation(0, False, 0.0, metrics, q)
+
+    def step(self, action: LayoutAction) -> LayoutObservation:  # type: ignore[override]
+        self._state.step_count += 1
+        step_num = self._state.step_count
+
+        valid = action.is_valid(len(self._state.elements))
+
+        if not valid:
+            metrics = compute_all_metrics(self._state.elements, self._stats)
+            q = quality_score(metrics, self._weights)
+            done = step_num >= self._max_steps
+            reward = INVALID_ACTION_PENALTY + STEP_PENALTY
+            if done:
+                q_delta = q - self._state.initial_quality
+                reward += (
+                    TERMINAL_BONUS_SCALE if q_delta >= Q_DELTA_THRESHOLD else TERMINAL_PENALTY
+                )
+            return self._build_observation(
+                step_num, done, round(reward, 4), metrics, q
+            )
+
+        is_noop = action.action == "NO_OP"
+
+        if not is_noop:
+            _apply_action(self._state.elements, action)
+        else:
+            pass
+
+        metrics = compute_all_metrics(self._state.elements, self._stats)
+        q = quality_score(metrics, self._weights)
+        delta_q = q - self._state.previous_quality
+        self._state.previous_quality = q
+
+        done = is_noop or step_num >= self._max_steps
+
+        reward = REWARD_SCALE * delta_q + STEP_PENALTY
+        if done:
+            q_delta = q - self._state.initial_quality
+            reward += (
+                TERMINAL_BONUS_SCALE if q_delta >= Q_DELTA_THRESHOLD else TERMINAL_PENALTY
+            )
+
+        return self._build_observation(
+            step_num, done, round(reward, 4), metrics, q
+        )
+
+    @property
+    def state(self) -> LayoutState:
+        return self._state

server/metrics.py

@@ -0,0 +1,184 @@
+"""
+Layout quality metrics for the RL reward signal.
+
+Every metric operates on a list of element dicts in normalised [0,1] space:
+    {"cx": float, "cy": float, "w": float, "h": float, "type": str, "font_size": float}
+
+Penalties (lower is better, target 0):    overlap, boundary.
+Rewards (higher is better):               alignment, spacing, plausibility.
+"""
+from itertools import combinations
+from typing import Dict, List, Optional
+import numpy as np
+
+
+# Helpers
+def _to_ltrb(e: Dict) -> tuple[float, float, float, float]:
+    """cxywh to ltrb"""
+    hw, hh = e["w"] / 2, e["h"] / 2
+    return (e["cx"] - hw, e["cy"] - hh, e["cx"] + hw, e["cy"] + hh)
+
+
+def _area(e: Dict) -> float:
+    return max(e["w"], 0) * max(e["h"], 0)
+
+
+def _axis_value(e: Dict, axis: str) -> float:
+    l, t, r, b = _to_ltrb(e)
+    return {"left": l, "right": r, "cx": e["cx"],
+            "top": t, "bottom": b, "cy": e["cy"]}[axis]
+
+
+
+# Individual metrics
+def overlap_score(elements: List[Dict]) -> float:
+    """Sum of pairwise intersection / min-area.  0 = no overlap."""
+    if len(elements) < 2:
+        return 0.0
+    total = 0.0
+    for a, b in combinations(elements, 2):
+        la, ta, ra, ba_ = _to_ltrb(a)
+        lb, tb, rb, bb_ = _to_ltrb(b)
+        ix = max(0.0, min(ra, rb) - max(la, lb))
+        iy = max(0.0, min(ba_, bb_) - max(ta, tb))
+        inter = ix * iy
+        if inter > 0:
+            min_area = min(_area(a), _area(b))
+            total += inter / (min_area + 1e-8)
+    n_pairs = len(elements) * (len(elements) - 1) / 2
+    return total / n_pairs
+
+
+def boundary_score(elements: List[Dict]) -> float:
+    """Fraction of area outside [0,1]^2 per element, averaged.  0 = all inside."""
+    if not elements:
+        return 0.0
+    total = 0.0
+    for e in elements:
+        l, t, r, b = _to_ltrb(e)
+        full_area = _area(e)
+        if full_area <= 0:
+            continue
+        cl = max(l, 0.0)
+        ct = max(t, 0.0)
+        cr = min(r, 1.0)
+        cb = min(b, 1.0)
+        clipped_w = max(cr - cl, 0.0)
+        clipped_h = max(cb - ct, 0.0)
+        clipped_area = clipped_w * clipped_h
+        total += 1.0 - (clipped_area / (full_area + 1e-8))
+    return total / len(elements)
+
+
+def alignment_score(elements: List[Dict], eps: float = 0.02) -> float:
+    """Fraction of element-pairs that share an aligned edge/centre.  1 = perfect."""
+    if len(elements) < 2:
+        return 1.0
+    axes = ["left", "right", "cx", "top", "bottom", "cy"]
+    aligned = 0
+    total_pairs = 0
+    for axis in axes:
+        values = [_axis_value(e, axis) for e in elements]
+        for i, j in combinations(range(len(values)), 2):
+            total_pairs += 1
+            if abs(values[i] - values[j]) < eps:
+                aligned += 1
+    return aligned / total_pairs if total_pairs > 0 else 0.0
+
+
+def spacing_score(elements: List[Dict]) -> float:
+    """Consistency of vertical and horizontal gaps.  1 = perfectly uniform."""
+    if len(elements) < 2:
+        return 1.0
+
+    def _gap_consistency(sorted_elems: List[Dict], vertical: bool) -> float:
+        gaps = []
+        for i in range(len(sorted_elems) - 1):
+            a, b = sorted_elems[i], sorted_elems[i + 1]
+            if vertical:
+                _, _, _, ba = _to_ltrb(a)
+                _, tb, _, _ = _to_ltrb(b)
+                gaps.append(tb - ba)
+            else:
+                _, _, ra, _ = _to_ltrb(a)
+                lb, _, _, _ = _to_ltrb(b)
+                gaps.append(lb - ra)
+        if len(gaps) < 2:
+            return 1.0
+        arr = np.array(gaps)
+        mean = np.mean(arr)
+        if abs(mean) < 1e-8:
+            return 1.0
+        cv = np.std(arr) / (abs(mean) + 1e-8)
+        return float(np.clip(1.0 - cv, 0.0, 1.0))
+
+    by_cy = sorted(elements, key=lambda e: e["cy"])
+    by_cx = sorted(elements, key=lambda e: e["cx"])
+    v_score = _gap_consistency(by_cy, vertical=True)
+    h_score = _gap_consistency(by_cx, vertical=False)
+    return (v_score + h_score) / 2.0
+
+
+def plausibility_score(
+    elements: List[Dict],
+    stats: Optional[Dict] = None,
+) -> float:
+    """Gaussian plausibility per element type.  1 = perfect match to data distribution."""
+    if not elements or stats is None:
+        return 0.0
+    total = 0.0
+    counted = 0
+    for e in elements:
+        etype = e.get("type")
+        if etype not in stats:
+            continue
+        mu = stats[etype]["mu"]
+        cov_inv = stats[etype]["cov_inv"]
+        x = np.array([e["cx"], e["cy"], e["w"], e["h"], e.get("font_size", 0.0)])
+        x = np.clip(x, 0.0, 1.0)
+        diff = x - mu
+        mahal = float(np.sqrt(np.clip(diff @ cov_inv @ diff, 0.0, None)))
+        total += float(np.exp(-0.5 * mahal))
+        counted += 1
+    return total / counted if counted > 0 else 0.0
+
+
+
+# Composite quality function
+DEFAULT_WEIGHTS = {
+    "overlap": 2.0,
+    "boundary": 3.0,
+    "alignment": 1.0,
+    "spacing": 0.5,
+    "plausibility": 1.0,
+}
+
+
+def compute_all_metrics(
+    elements: List[Dict],
+    stats: Optional[Dict] = None,
+) -> Dict[str, float]:
+    """Return a dict of all individual metric scores."""
+    return {
+        "overlap": round(overlap_score(elements), 4),
+        "boundary": round(boundary_score(elements), 4),
+        "alignment": round(alignment_score(elements), 4),
+        "spacing": round(spacing_score(elements), 4),
+        "plausibility": round(plausibility_score(elements, stats), 4),
+    }
+
+
+def quality_score(
+    metrics: Dict[str, float],
+    weights: Optional[Dict[str, float]] = None,
+) -> float:
+    """Composite Q(state).  Higher is better."""
+    w = weights or DEFAULT_WEIGHTS
+    q = (
+        -w["overlap"] * metrics["overlap"]
+        - w["boundary"] * metrics["boundary"]
+        + w["alignment"] * metrics["alignment"]
+        + w["spacing"] * metrics["spacing"]
+        + w["plausibility"] * metrics["plausibility"]
+    )
+    return round(q, 4)

server/requirements.txt

@@ -0,0 +1,5 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+numpy>=1.24.0
+pillow>=10.0.0