""" Typed Pydantic models for the Document Classification OpenEnv. Implements the OpenEnv spec requirement for typed Observation, Action, and Reward models. Contains two sets of models: 1. DocAction / DocObservation / DocState — extend openenv-core base types for WebSocket-based EnvClient ↔ server communication (judges use these). 2. Action / Observation / Reward / EnvironmentState — legacy Pydantic models kept for the REST API and Gradio UI. """ from pydantic import BaseModel, Field, field_validator from typing import List, Optional, Literal from enum import Enum # ── OpenEnv framework-native models (extend openenv-core base types) ───────── try: from openenv.core.env_server.types import ( Action as _OEAction, Observation as _OEObservation, ) _OPENENV_AVAILABLE = True except ImportError: # graceful fallback so existing code still works without openenv _OEAction = BaseModel _OEObservation = BaseModel _OPENENV_AVAILABLE = False class DocAction(_OEAction): """ Typed action for the Document Classification environment. action_id meanings (for difficulty='easy', 5 categories): 0..4 → classify document into category 0..4 5 → request metadata (tool, costs -0.05 reward) 6 → escalate to human (safe fallback, 0.0 reward) Use num_categories from the observation to determine valid range: classify: 0 .. total_documents-related N metadata: N escalate: N+1 """ action_id: int = Field(..., ge=0, description="Integer action index") difficulty: str = Field("easy", description="Task difficulty: easy | medium | hard") class DocObservation(_OEObservation): """ Typed observation returned by reset() and step(). Inherits from openenv Observation which provides: reward, done, metadata. """ document_id: str = Field("", description="Unique ID for the current document") content: str = Field("", description="Raw text of the support ticket") word_count: int = Field(0, ge=0, description="Number of words") has_urgency_markers: bool = Field(False, description="True if document is VIP / urgent") features: List[float] = Field(default_factory=list, description="TF-IDF feature vector (dim=100)") document_index: int = Field(0, ge=0, description="Current document index in episode") total_documents: int = Field(0, ge=0, description="Total documents in this episode") metadata_response: str = Field( "Not requested. Use action to request customer history.", description="Response from Request Metadata tool", ) sla_remaining: float = Field(999.0, ge=0.0, description="Seconds before SLA breach") class DocState(BaseModel): """ Episode-level state returned by state(). Exposes ground-truth metrics for graders and evaluation harnesses. NOT visible to the agent during training. """ episode_id: str = Field(..., description="Unique episode identifier") step_count: int = Field(..., ge=0, description="Number of steps taken so far") difficulty: str = Field(..., description="Task difficulty: easy | medium | hard") accuracy: float = Field(..., ge=0.0, le=1.0, description="Classification accuracy so far") total_reward: float = Field(..., description="Cumulative reward for this episode") sla_breaches: int = Field(0, ge=0, description="Number of SLA breaches so far") # ─── Action Models ─────────────────────────────────────────────────────────── class ActionType(str, Enum): """Types of actions an agent can take.""" CLASSIFY = "classify" REQUEST_METADATA = "request_metadata" ESCALATE = "escalate" class Action(BaseModel): """ Typed action model for the Document Classification environment. Actions 0..N-1 classify the document into a category. Action N requests customer metadata (tool usage, costs -0.05 reward). Action N+1 escalates to a human manager (safe fallback, 0.0 reward). """ action_id: int = Field(..., ge=0, description="Integer action index") action_type: ActionType = Field(..., description="Type of action taken") category_name: Optional[str] = Field(None, description="Category name if classify action") @classmethod def from_raw(cls, action_id: int, num_categories: int, category_map: dict) -> "Action": """Create a typed Action from a raw integer action.""" if action_id < num_categories: return cls( action_id=action_id, action_type=ActionType.CLASSIFY, category_name=category_map.get(action_id, f"Unknown_{action_id}") ) elif action_id == num_categories: return cls( action_id=action_id, action_type=ActionType.REQUEST_METADATA, category_name=None ) elif action_id == num_categories + 1: return cls( action_id=action_id, action_type=ActionType.ESCALATE, category_name=None ) else: raise ValueError(f"Invalid action_id: {action_id}. Must be 0..{num_categories + 1}") # ─── Observation Models ────────────────────────────────────────────────────── class Observation(BaseModel): """ Typed observation model returned by reset() and step(). Contains the document content, metadata features, and progress tracking. """ document_id: str = Field(..., description="Unique identifier for the current document") content: str = Field(..., description="Raw text content of the support ticket") word_count: int = Field(..., ge=0, description="Number of words in the document") has_urgency_markers: bool = Field(..., description="Whether document contains urgency indicators") features: List[float] = Field(..., description="Pre-extracted TF-IDF feature vector (normalized)") document_index: int = Field(..., ge=0, description="Current document index in the episode") total_documents: int = Field(..., ge=0, description="Total documents in the episode") metadata_response: str = Field( default="Not requested. Use action to request customer history.", description="Response from the metadata tool, if previously requested" ) sla_remaining: float = Field( default=999.0, ge=0.0, description="Seconds remaining before SLA breach for current document" ) @classmethod def from_gym_obs(cls, obs: dict) -> "Observation": """Create a typed Observation from a raw Gymnasium observation dict.""" return cls( document_id=obs.get("document_id", ""), content=obs.get("content", ""), word_count=int(obs["word_count"][0]) if hasattr(obs.get("word_count"), '__len__') else int(obs.get("word_count", 0)), has_urgency_markers=bool(obs["has_urgency_markers"][0]) if hasattr(obs.get("has_urgency_markers"), '__len__') else bool(obs.get("has_urgency_markers", False)), features=[float(f) for f in obs.get("features", [])], document_index=int(obs["document_index"][0]) if hasattr(obs.get("document_index"), '__len__') else int(obs.get("document_index", 0)), total_documents=int(obs["total_documents"][0]) if hasattr(obs.get("total_documents"), '__len__') else int(obs.get("total_documents", 0)), metadata_response=obs.get("metadata_response", "Not requested."), sla_remaining=float(obs["sla_remaining"][0]) if hasattr(obs.get("sla_remaining"), '__len__') else float(obs.get("sla_remaining", 999.0)), ) # ─── Reward Models ─────────────────────────────────────────────────────────── class Reward(BaseModel): """ Typed reward model returned by step(). Decomposes the scalar reward into interpretable components. """ total: float = Field(..., description="Total scalar reward for this step") accuracy_component: float = Field(0.0, description="+1.0 for correct, -0.4 for wrong, 0.0 for escalate") tool_cost: float = Field(0.0, description="-0.05 if metadata was requested, 0.0 otherwise") is_correct: bool = Field(False, description="Whether the classification was correct") @classmethod def from_step(cls, reward: float, info: dict) -> "Reward": """Create a typed Reward from raw step() outputs.""" pred = info.get("predicted_category", "") if pred == "TOOL_METADATA": return cls(total=reward, accuracy_component=0.0, tool_cost=-0.05, is_correct=False) elif pred == "ESCALATED": return cls(total=reward, accuracy_component=0.0, tool_cost=0.0, is_correct=False) else: is_correct = info.get("is_correct", False) acc = 1.0 if is_correct else -0.4 return cls(total=reward, accuracy_component=acc, tool_cost=0.0, is_correct=is_correct) # ─── State Model ───────────────────────────────────────────────────────────── class EnvironmentState(BaseModel): """ Typed state model returned by state(). Provides a complete snapshot of the environment's internal state. """ document_index: int = Field(..., ge=0) total_documents: int = Field(..., ge=0) current_true_label: Optional[int] = None current_true_category: Optional[str] = None total_reward: float accuracy: float = Field(..., ge=0.0, le=1.0) avg_time_ms: float = Field(..., ge=0.0) difficulty: Literal["easy", "medium", "hard"] sla_breaches: int = Field(default=0, ge=0, description="Number of SLA breaches") action_history: List[int] = Field(default_factory=list) reward_history: List[float] = Field(default_factory=list) processing_times_ms: List[float] = Field(default_factory=list) @classmethod def from_state_dict(cls, state: dict) -> "EnvironmentState": """Create a typed EnvironmentState from raw state() output.""" return cls( document_index=state["document_index"], total_documents=state["total_documents"], current_true_label=state.get("current_true_label"), current_true_category=state.get("current_true_category"), total_reward=state["total_reward"], accuracy=state["accuracy"], avg_time_ms=state["avg_time_ms"], difficulty=state["difficulty"], sla_breaches=state.get("sla_breaches", 0), action_history=state.get("action_history", []), reward_history=state.get("reward_history", []), processing_times_ms=state.get("processing_times_ms", []), ) # ─── Episode Summary ───────────────────────────────────────────────────────── class EpisodeSummary(BaseModel): """Summary metrics for a completed episode.""" total_reward: float avg_reward: float accuracy: float = Field(..., ge=0.0, le=1.0) total_classified: int = Field(..., ge=0) avg_time_ms: float = Field(..., ge=0.0) total_time_s: float = Field(..., ge=0.0)