""" Document Classification Environment — OpenEnv server-side implementation. Bridges the existing DocumentClassificationEnv (gym-style) to the OpenEnv Environment base class. The gym env contains all real RL logic; this adapter only converts types and wires up reset/step/state for the OpenEnv HTTP server. Architecture: OpenEnv HTTP/WebSocket server (server/app.py) └── DocumentClassificationEnvironment ← this file └── DocumentClassificationEnv ← environment.py (gym env, unchanged) """ from __future__ import annotations import sys import os import uuid from typing import Any, Optional # Allow importing from parent directory (environment.py, models.py, tasks.py) sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from openenv.core.env_server import Environment from environment import DocumentClassificationEnv from models import DocAction, DocObservation, DocState class DocumentClassificationEnvironment(Environment): """ OpenEnv-compliant wrapper around DocumentClassificationEnv. Satisfies the OpenEnv Environment interface: - reset(seed, **kwargs) → DocObservation - step(DocAction) → DocObservation (obs.done, obs.reward set) - state (property) → DocState One instance = one difficulty level. The create_app() factory in app.py instantiates a fresh instance per WebSocket session (for isolation). """ def __init__(self, difficulty: str = "easy", seed: int = 42): self._difficulty = difficulty self._seed = seed self._gym_env = DocumentClassificationEnv( task_difficulty=difficulty, seed=seed ) self._episode_id: str = str(uuid.uuid4()) self._step_count: int = 0 # ── OpenEnv interface ───────────────────────────────────────────────────── def reset( self, seed: Optional[int] = None, episode_id: Optional[str] = None, **kwargs: Any, ) -> DocObservation: """Start a new episode and return the first observation.""" obs, _ = self._gym_env.reset(seed=seed) self._episode_id = episode_id or str(uuid.uuid4()) self._step_count = 0 return self._make_obs(obs, reward=0.0, done=False) def step(self, action: DocAction, **kwargs: Any) -> DocObservation: """Execute one classification action and return the resulting observation.""" obs, reward, done, _, info = self._gym_env.step(int(action.action_id)) self._step_count += 1 return self._make_obs(obs, reward=float(reward), done=bool(done), metadata=info) @property def state(self) -> DocState: """Return episode-level state metadata (not exposed to agent during training).""" s = self._gym_env.state() return DocState( episode_id=self._episode_id, step_count=self._step_count, difficulty=self._difficulty, accuracy=float(s.get("accuracy", 0.0)), total_reward=float(s.get("total_reward", 0.0)), sla_breaches=int(s.get("sla_breaches", 0)), ) # ── Internal helpers ────────────────────────────────────────────────────── def _make_obs( self, gym_obs: dict, reward: float, done: bool, metadata: Optional[dict] = None, ) -> DocObservation: """Convert a raw gymnasium observation dict to a typed DocObservation.""" def _scalar(value, default=0): """Unwrap numpy scalars / 1-element arrays to Python primitives.""" if value is None: return default if hasattr(value, "__len__") and len(value) == 1: return type(default)(value[0]) if hasattr(value, "item"): return value.item() return value features_raw = gym_obs.get("features", []) features = ( features_raw.tolist() if hasattr(features_raw, "tolist") else list(features_raw) ) return DocObservation( document_id=gym_obs.get("document_id", ""), content=gym_obs.get("content", ""), word_count=int(_scalar(gym_obs.get("word_count"), 0)), has_urgency_markers=bool(_scalar(gym_obs.get("has_urgency_markers"), 0)), features=[float(f) for f in features], document_index=int(_scalar(gym_obs.get("document_index"), 0)), total_documents=int(_scalar(gym_obs.get("total_documents"), 0)), metadata_response=gym_obs.get( "metadata_response", "Not requested. Use action to request customer history." ), sla_remaining=float(_scalar(gym_obs.get("sla_remaining"), 999.0)), reward=reward, done=done, metadata=metadata or {}, )