TanujInsane
Update inference.py retry loop for server connection
1b64cdd
Raw History Blame Contribute Delete
11.7 kB
"""
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)