Spaces:
Running
Running
Download python/borderland_eval/gym_adapter.py from FatUnc6969/borderland-rl: direct link, hf CLI and curl.
- Browser
- Download file 12.7 kB
-
https://huggingface.co/spaces/FatUnc6969/borderland-rl/resolve/main/python/borderland_eval/gym_adapter.py
- Command line
-
hf download hf://spaces/FatUnc6969/borderland-rl/python/borderland_eval/gym_adapter.py
-
curl -L -o gym_adapter.py https://huggingface.co/spaces/FatUnc6969/borderland-rl/resolve/main/python/borderland_eval/gym_adapter.py
12.7 kB
| """Optional Gymnasium entry point. | |
| Install ``borderland-rl[gymnasium]`` and import ``BorderlandEnv`` here. | |
| Observations are current public Transition JSON, including legal_actions, without | |
| operator revision or diagnostics. Actions are JSON | |
| ``{"tag": "...", "arguments": {...}}`` objects. The additional tag | |
| ``replace_notebook`` takes exactly ``{"text": "..."}`` and obeys the engine's | |
| configured byte limit in generation three or 768-character limit in generation | |
| two. JSON text uses printable ASCII with Unicode escapes. | |
| Default reset starts a complete campaign. ``options={"checkpoint": N}`` starts | |
| a room diagnostic for N in 1..7 and ends when that room is left. For N > 1 a | |
| public-observation LegalReference executes the prefix and writes its legitimate | |
| notebook. This assisted diagnostic is never full-campaign success. Seeds are | |
| operator inputs; neither seeds nor prefix history enter observations or info. | |
| The default ``reward_mode="engine"`` preserves engine reward. For a checkpoint, | |
| ``reward_mode="room_exit"`` selects a binary local training surrogate and adds | |
| its versioned contract and separate actor returns to info only. | |
| ``options={"split": "train"}`` samples a frozen generation-specific split. | |
| The other split names are ``dev`` and ``test``. The reset seed selects a | |
| reproducible member. A split and ``world_seed`` are mutually exclusive. | |
| """ | |
| from __future__ import annotations | |
| import json | |
| import string | |
| import gymnasium as gym | |
| from gymnasium import spaces | |
| from borderland import Campaign | |
| from borderland.domain import ActionError | |
| from .context import actor_transition, actor_view | |
| class BorderlandEnv(gym.Env): | |
| """Text/tool environment with bounded attempts and default engine rewards. | |
| ``seed`` in reset controls world generation through Gymnasium's RNG. | |
| ``world_seed`` fixes a world for operator diagnostics independently of that RNG. | |
| A diagnostic ends on leaving its selected room, or on an engine terminal state. | |
| Invalid actions consume adapter attempts but leave the campaign unchanged. | |
| """ | |
| metadata = {"render_modes": []} | |
| def __init__(self, *, world_seed=None, max_steps=512, invalid_attempt_limit=32, | |
| generation_version=2, notebook_bytes=768, memory_profile="static"): | |
| super().__init__() | |
| if world_seed is not None and type(world_seed) is not int: | |
| raise ValueError("world_seed must be an integer or None") | |
| for name, value in (("max_steps", max_steps), ("invalid_attempt_limit", invalid_attempt_limit)): | |
| if type(value) is not int or value < 1: | |
| raise ValueError(f"{name} must be a positive integer") | |
| self._world_seed = world_seed | |
| self._max_steps = max_steps | |
| self._invalid_attempt_limit = invalid_attempt_limit | |
| self._profile(generation_version, notebook_bytes, memory_profile) | |
| self._generation_version = generation_version | |
| self._notebook_bytes = notebook_bytes | |
| self._memory_profile = memory_profile | |
| charset = string.ascii_letters + string.digits + string.punctuation + " " | |
| self.action_space = spaces.Text(max_length=16384, min_length=1, charset=charset) | |
| self.observation_space = spaces.Text(max_length=131072, min_length=1, charset=charset) | |
| self._campaign = None | |
| self._finished = True | |
| self._checkpoint = None | |
| self._reward_mode = "engine" | |
| self._actor_engine_return = 0.0 | |
| self._actor_training_return = 0.0 | |
| self._attempts = 0 | |
| self._invalid_attempts = 0 | |
| def reset(self, *, seed=None, options=None): | |
| if seed is not None and (type(seed) is not int or seed < 0): | |
| raise ValueError("seed must be a nonnegative integer or None") | |
| if options is not None and (type(options) is not dict or set(options) - {"checkpoint","archive_workload","generation_version","notebook_bytes","memory_profile","split","reward_mode"}): | |
| raise ValueError("options supports checkpoint, archive_workload, generation_version, notebook_bytes, memory_profile, split and reward_mode") | |
| checkpoint = None if options is None else options.get("checkpoint") | |
| if options is not None and "checkpoint" in options: | |
| if type(checkpoint) is not int or not 1 <= checkpoint <= 7: | |
| raise ValueError("checkpoint must be an integer from 1 to 7") | |
| workload = "standard" if options is None else options.get("archive_workload","standard") | |
| options = options or {} | |
| reward_mode = options.get("reward_mode", "engine") | |
| if type(reward_mode) is not str or reward_mode not in ("engine", "room_exit"): | |
| raise ValueError("reward_mode must be engine or room_exit") | |
| if reward_mode == "room_exit" and checkpoint is None: | |
| raise ValueError("room_exit reward requires a checkpoint") | |
| profile = self._profile(options.get("generation_version", self._generation_version), | |
| options.get("notebook_bytes", self._notebook_bytes), | |
| options.get("memory_profile", self._memory_profile)) | |
| split = options.get("split") | |
| if "split" in options and split not in ("train", "dev", "test"): | |
| raise ValueError("split must be train, dev, or test") | |
| if split is not None and self._world_seed is not None: | |
| raise ValueError("world_seed and split are mutually exclusive") | |
| super().reset(seed=seed) | |
| world_seed = self._world_seed | |
| if split is not None: | |
| from .manifests import manifest | |
| roots = manifest(split, profile["generation_version"])["root_seeds"] | |
| world_seed = roots[int(self.np_random.integers(len(roots)))] | |
| elif world_seed is None: | |
| world_seed = int(self.np_random.integers(0, 2**63)) | |
| campaign = Campaign.generated(world_seed, archive_workload=workload, **profile) | |
| transition = campaign.observe() | |
| if checkpoint is not None and checkpoint > 1: | |
| from borderland_verify.reference import public_reference | |
| reference = public_reference(actor_transition(transition)) | |
| for _ in range(240): | |
| if transition.done or int(transition.observation.phase) >= checkpoint: | |
| break | |
| note = reference.notebook(actor_transition(transition)) | |
| if note is not None: | |
| transition = campaign.replace_notebook(note, expected_revision=transition.revision) | |
| transition = campaign.step(reference.choose(actor_transition(transition)), expected_revision=transition.revision) | |
| if transition.context_reset: | |
| reference = type(reference)() | |
| if transition.error: | |
| raise RuntimeError("public reference could not reach diagnostic checkpoint") | |
| if transition.done or int(transition.observation.phase) != checkpoint: | |
| raise RuntimeError("public reference did not reach diagnostic checkpoint") | |
| self._campaign = campaign | |
| self._transition = transition | |
| self._checkpoint = checkpoint | |
| self._reward_mode = reward_mode | |
| self._actor_engine_return = 0.0 | |
| self._actor_training_return = 0.0 | |
| self._attempts = 0 | |
| self._invalid_attempts = 0 | |
| self._finished = False | |
| observation, _, _, _, info = self._result(transition) | |
| return observation, info | |
| def _profile(generation_version, notebook_bytes, memory_profile="static"): | |
| if type(generation_version) is not int or generation_version not in (2, 3): | |
| raise ValueError("generation_version must be 2 or 3") | |
| if type(notebook_bytes) is not int or notebook_bytes < 0: | |
| raise ValueError("notebook_bytes must be a nonnegative integer") | |
| if generation_version == 2 and notebook_bytes != 768: | |
| raise ValueError("custom byte capacity requires generation three") | |
| if memory_profile not in ("static", "commissioning") or (generation_version == 2 and memory_profile != "static"): | |
| raise ValueError("commissioning requires generation three") | |
| return {"generation_version": generation_version, "notebook_bytes": notebook_bytes, "memory_profile": memory_profile} | |
| def step(self, action): | |
| if self._finished or self._campaign is None: | |
| raise gym.error.ResetNeeded("Call reset before stepping a new episode") | |
| previous_phase = int(self._transition.observation.phase) | |
| self._attempts += 1 | |
| error = None | |
| if not self.action_space.contains(action): | |
| error = ActionError("malformed", "Expected printable ASCII JSON action text within the action-space bound.") | |
| else: | |
| try: | |
| raw = json.loads(action, parse_constant=self._reject_constant, object_pairs_hook=self._unique_object) | |
| except (ValueError, RecursionError): | |
| error = ActionError("malformed", "Expected finite JSON with unique object keys.") | |
| else: | |
| if type(raw) is dict and raw.get("tag") == "replace_notebook": | |
| if set(raw) != {"tag", "arguments"} or type(raw["arguments"]) is not dict or set(raw["arguments"]) != {"text"}: | |
| error = ActionError("malformed", "Notebook action requires exactly one text argument.") | |
| else: | |
| self._transition = self._campaign.replace_notebook(raw["arguments"]["text"]) | |
| else: | |
| self._transition = self._campaign.step(raw) | |
| if error is None: | |
| error = self._transition.error | |
| if error is not None: | |
| self._invalid_attempts += 1 | |
| return self._result(self._transition, error, previous_phase=previous_phase) | |
| def _reject_constant(value): | |
| raise ValueError("nonfinite JSON") | |
| def _unique_object(pairs): | |
| result = {} | |
| for key, value in pairs: | |
| if key in result: | |
| raise ValueError("duplicate JSON key") | |
| result[key] = value | |
| return result | |
| def _result(self, transition, error=None, *, previous_phase=None): | |
| data = actor_view(transition) | |
| data["error"] = None if error is None else error.to_dict() | |
| room_complete = self._checkpoint is not None and int(transition.observation.phase) != self._checkpoint | |
| terminated = bool(transition.terminated or room_complete) | |
| reason = None | |
| if not terminated and self._invalid_attempts >= self._invalid_attempt_limit: | |
| reason = "invalid_attempt_limit" | |
| elif not terminated and self._attempts >= self._max_steps: | |
| reason = "attempt_limit" | |
| truncated = bool(transition.truncated or reason is not None) | |
| self._finished = terminated or truncated | |
| info = {"outcome": transition.outcome, | |
| "generation_version": self._campaign._world.generation_version, | |
| "memory_profile": self._campaign._world.memory_profile, | |
| "context_reset": transition.context_reset, "error": data["error"], | |
| "scope": "campaign" if self._checkpoint is None else "room_diagnostic", | |
| "checkpoint": self._checkpoint, "assisted_prefix": self._checkpoint is not None and self._checkpoint > 1, | |
| "room_complete": room_complete or (self._checkpoint == 7 and transition.outcome == "escaped"), | |
| "full_campaign_success": self._checkpoint is None and transition.outcome == "escaped", | |
| "truncation_reason": reason} | |
| observation = json.dumps(data, ensure_ascii=True, allow_nan=False, separators=(",", ":"), sort_keys=True) | |
| reward = float(transition.reward) | |
| if self._reward_mode == "room_exit": | |
| reward = float(error is None and not truncated and previous_phase == self._checkpoint and ( | |
| (self._checkpoint < 7 and int(transition.observation.phase) == self._checkpoint + 1 | |
| and transition.outcome == "running") | |
| or (self._checkpoint == 7 and transition.outcome == "escaped"))) | |
| if previous_phase is not None: | |
| self._actor_engine_return += float(transition.reward) | |
| self._actor_training_return += reward | |
| info.update(reward_mode="room_exit", reward_contract="local_surrogate.room_exit.v1", | |
| engine_reward=float(transition.reward), | |
| actor_engine_return=self._actor_engine_return, | |
| actor_training_return=self._actor_training_return) | |
| return observation, reward, terminated, truncated, info | |