File size: 11,657 Bytes
1b64cdd
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
"""
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)