models.py

# Copyright (c) Meta Platforms, Inc. and affiliates.
# All rights reserved.
#
# This source code is licensed under the BSD-style license found in the
# LICENSE file in the root directory of this source tree.

"""
Data models for the Html Design Agent Environment.

The agent receives HTML and gets scored on branding adherence, spacing grid
compliance, accessibility, and compositional balance per the AGENTS.md spec.
"""

from typing import Any, Dict, List

from openenv.core.env_server.types import Action, Observation
from pydantic import Field


class HtmlDesignAgentAction(Action):
    """
    Action for the Html Design Agent.

    The agent submits HTML for evaluation against the design system.
    Task is fixed per episode (set via HTML_DESIGN_AGENT_TASK env var).
    """

    html: str = Field(..., description="Full HTML string to evaluate")
    task_id: str = Field(
        default="fix_contrast",
        description="Task identifier: fix_contrast | fix_spacing | fix_accessibility",
    )


class HtmlDesignAgentObservation(Observation):
    """
    Observation from the Html Design Agent environment.

    Contains the current HTML, design tokens for reference, per-dimension
    reward breakdown, and a list of specific violations to fix.
    """

    task_id: str = Field(default="", description="Current task identifier")
    current_html: str = Field(default="", description="The submitted (or initial) HTML")
    design_tokens: Dict[str, Any] = Field(
        default_factory=dict,
        description="Brand design tokens: palette, fonts, spacing scale",
    )
    reward_breakdown: Dict[str, float] = Field(
        default_factory=dict,
        description="Per-dimension scores: branding, spacing, a11y, composition",
    )
    violations: List[str] = Field(
        default_factory=list,
        description="Human-readable list of design violations found",
    )
    dom_summary: str = Field(
        default="",
        description="Simplified JSON summary of the rendered DOM structure",
    )
    step_count: int = Field(default=0, description="Current step within the episode")