Download models.py from TanujInsane/document-classification-env: direct link, hf CLI and curl.
- Browser
- Download file 11.7 kB
-
https://huggingface.co/spaces/TanujInsane/document-classification-env/resolve/main/models.py
- Command line
-
hf download hf://spaces/TanujInsane/document-classification-env/models.py
-
curl -L -o models.py https://huggingface.co/spaces/TanujInsane/document-classification-env/resolve/main/models.py
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") | |
| 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" | |
| ) | |
| 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") | |
| 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) | |
| 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) | |