models.py

"""
Data models for the PermitPathfinder environment.

PermitPathfinder simulates a stateful municipal permitting workflow.
An agent opens a business by navigating a DAG of permits, paying fees,
scheduling inspections, and respecting prerequisites — all under a
budget cap.
"""

from typing import Optional

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


class PermitAction(Action):
    """An action taken by the agent against the permitting system."""

    action_type: str = Field(
        ...,
        description=(
            "One of: 'submit', 'pay', 'inspect', 'query', 'list', 'set_task'. "
            "'list' ignores permit_id and returns all permits. "
            "'set_task' uses permit_id to carry the target task name."
        ),
    )
    permit_id: Optional[str] = Field(
        default=None,
        description="ID of the permit to act on (not required for 'list').",
    )


class PermitObservation(Observation):
    """The observation returned after each step."""

    message: str = Field(
        default="",
        description="Human-readable status message for the last action.",
    )
    permits: dict = Field(
        default_factory=dict,
        description=(
            "All permits in the task: "
            "{permit_id: {stage, fee, prereqs, prereqs_met}}"
        ),
    )
    budget_remaining: float = Field(
        default=0.0,
        description="Remaining budget after fees paid.",
    )
    wasted_submissions: int = Field(
        default=0,
        description="Count of illegal submit/pay/inspect attempts.",
    )
    last_action_error: Optional[str] = Field(
        default=None,
        description="Raw error from the last action, or None if successful.",
    )
    available_actions: list = Field(
        default_factory=list,
        description="List of action strings currently legal.",
    )
    task_name: str = Field(
        default="easy_foodtruck",
        description="Currently active task.",
    )