Upload folder using huggingface_hub

Dockerfile

@@ -1,6 +1,8 @@
 ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
 FROM ${BASE_IMAGE} AS builder
 
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app/env
 COPY . /app/env
 

build/lib/freeciv_env/__init__.py

@@ -0,0 +1,10 @@
+from freeciv_env.client import FreecivEnv
+from freeciv_env.models import FreecivAction, FreecivObservation, FreecivState, LegalAction
+
+__all__ = [
+    "FreecivAction",
+    "FreecivEnv",
+    "FreecivObservation",
+    "FreecivState",
+    "LegalAction",
+]

build/lib/freeciv_env/adapter.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from freeciv_env.models import CitySummary, FreecivAction, FreecivObservation, LegalAction, UnitSummary
+
+
+ActionLookupKey = tuple[str, int | None, int | None, str | None]
+
+
+@dataclass(frozen=True)
+class ActionRef:
+    controller: str
+    actor_id: int | str
+    raw_action_key: str
+
+
+@dataclass
+class RawSnapshot:
+    turn: int
+    state: dict[str, Any]
+    actions: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class SnapshotMetrics:
+    score: float
+    known_tiles: int
+    visible_tiles: int
+    city_count: int
+    unit_count: int
+    techs_researched: int
+
+
+@dataclass
+class PreparedObservation:
+    observation: FreecivObservation
+    metrics: SnapshotMetrics
+    action_refs: dict[ActionLookupKey, ActionRef]
+
+
+def _map_status_rows(raw_state: dict[str, Any]) -> list[list[int | float]]:
+    raw_map = raw_state.get("map", {})
+    status = raw_map.get("status", [])
+    return status if isinstance(status, list) else []
+
+
+def count_known_tiles(raw_state: dict[str, Any]) -> int:
+    return sum(1 for row in _map_status_rows(raw_state) for value in row if value and value > 0)
+
+
+def count_visible_tiles(raw_state: dict[str, Any]) -> int:
+    return sum(1 for row in _map_status_rows(raw_state) for value in row if value and value >= 2)
+
+
+def extract_metrics(snapshot: RawSnapshot) -> SnapshotMetrics:
+    player = snapshot.state.get("player", {})
+    return SnapshotMetrics(
+        score=float(player.get("my_score", 0.0)),
+        known_tiles=count_known_tiles(snapshot.state),
+        visible_tiles=count_visible_tiles(snapshot.state),
+        city_count=len(snapshot.state.get("city", {})),
+        unit_count=len(snapshot.state.get("unit", {})),
+        techs_researched=int(player.get("my_techs_researched", 0) or 0),
+    )
+
+
+def action_lookup_key(action: FreecivAction) -> ActionLookupKey:
+    if action.action_type == "move_unit":
+        return ("move_unit", action.unit_id, action.direction, None)
+    if action.action_type == "build_city":
+        return ("build_city", action.unit_id, None, None)
+    if action.action_type == "set_city_production":
+        return ("set_city_production", action.city_id, None, action.target)
+    if action.action_type == "set_research":
+        return ("set_research", None, None, action.target)
+    return ("end_turn", None, None, None)
+
+
+def _parse_target_name(raw_action_key: str, prefix: str) -> str:
+    suffix = raw_action_key.removeprefix(prefix)
+    name, _sep, _tail = suffix.rpartition("_")
+    return name or suffix
+
+
+
+def _controller_actions(snapshot: RawSnapshot, controller: str) -> dict[str, Any]:
+    raw_actions = snapshot.actions.get(controller, {})
+    if isinstance(raw_actions, dict):
+        return raw_actions
+    if hasattr(raw_actions, "json_struct"):
+        json_actions = raw_actions.json_struct()
+        return json_actions if isinstance(json_actions, dict) else {}
+    return {}
+
+
+
+def _extract_legal_actions(snapshot: RawSnapshot) -> tuple[list[LegalAction], dict[ActionLookupKey, ActionRef]]:
+    legal_actions: list[LegalAction] = [
+        LegalAction(
+            action_type="end_turn",
+            label="End the current turn",
+            raw_action_key="__end_turn__",
+        )
+    ]
+    refs: dict[ActionLookupKey, ActionRef] = {}
+
+    for actor_id, action_map in _controller_actions(snapshot, "unit").items():
+        unit_id = int(actor_id)
+        if action_map.get("build"):
+            legal_actions.append(
+                LegalAction(
+                    action_type="build_city",
+                    label=f"Build a city with unit {unit_id}",
+                    unit_id=unit_id,
+                    raw_action_key="build",
+                )
+            )
+            refs[("build_city", unit_id, None, None)] = ActionRef(
+                controller="unit",
+                actor_id=unit_id,
+                raw_action_key="build",
+            )
+        for raw_action_key, enabled in sorted(action_map.items()):
+            if not enabled or not raw_action_key.startswith("goto_"):
+                continue
+            direction = int(raw_action_key.split("_", 1)[1])
+            legal_actions.append(
+                LegalAction(
+                    action_type="move_unit",
+                    label=f"Move unit {unit_id} in direction {direction}",
+                    unit_id=unit_id,
+                    direction=direction,
+                    raw_action_key=raw_action_key,
+                )
+            )
+            refs[("move_unit", unit_id, direction, None)] = ActionRef(
+                controller="unit",
+                actor_id=unit_id,
+                raw_action_key=raw_action_key,
+            )
+
+    for actor_id, action_map in _controller_actions(snapshot, "city").items():
+        city_id = int(actor_id)
+        for raw_action_key, enabled in sorted(action_map.items()):
+            if not enabled:
+                continue
+            if raw_action_key.startswith("change_unit_prod_"):
+                target = _parse_target_name(raw_action_key, "change_unit_prod_")
+            elif raw_action_key.startswith("change_improve_prod_"):
+                target = _parse_target_name(raw_action_key, "change_improve_prod_")
+            else:
+                continue
+            legal_actions.append(
+                LegalAction(
+                    action_type="set_city_production",
+                    label=f"Set city {city_id} production to {target}",
+                    city_id=city_id,
+                    target=target,
+                    raw_action_key=raw_action_key,
+                )
+            )
+            refs[("set_city_production", city_id, None, target)] = ActionRef(
+                controller="city",
+                actor_id=city_id,
+                raw_action_key=raw_action_key,
+            )
+
+    tech_actions = _controller_actions(snapshot, "tech").get("cur_player", {})
+    for raw_action_key, enabled in sorted(tech_actions.items()):
+        if not enabled or not raw_action_key.startswith("research_tech_"):
+            continue
+        target = _parse_target_name(raw_action_key, "research_tech_")
+        legal_actions.append(
+            LegalAction(
+                action_type="set_research",
+                label=f"Research {target}",
+                target=target,
+                raw_action_key=raw_action_key,
+            )
+        )
+        refs[("set_research", None, None, target)] = ActionRef(
+            controller="tech",
+            actor_id="cur_player",
+            raw_action_key=raw_action_key,
+        )
+
+    legal_actions.sort(
+        key=lambda item: (
+            item.action_type,
+            item.unit_id or -1,
+            item.city_id or -1,
+            item.direction or -1,
+            item.target or "",
+        )
+    )
+    return legal_actions, refs
+
+
+def _extract_unit_summaries(snapshot: RawSnapshot) -> list[UnitSummary]:
+    unit_actions = _controller_actions(snapshot, "unit")
+    units: list[UnitSummary] = []
+    for actor_id, unit in sorted(snapshot.state.get("unit", {}).items(), key=lambda item: int(item[0])):
+        action_map = unit_actions.get(str(actor_id), unit_actions.get(actor_id, {}))
+        move_directions = sorted(
+            int(raw_action_key.split("_", 1)[1])
+            for raw_action_key, enabled in action_map.items()
+            if enabled and raw_action_key.startswith("goto_")
+        )
+        units.append(
+            UnitSummary(
+                unit_id=int(actor_id),
+                unit_type=str(unit.get("type_rule_name", "Unknown")),
+                health=int(unit.get("health", 0) or 0),
+                moves_left=int(unit.get("moves_left", unit.get("movesleft", 0)) or 0),
+                home_city_id=(
+                    int(unit.get("home_city"))
+                    if unit.get("home_city") not in (None, -1, "")
+                    else None
+                ),
+                veteran_level=int(unit.get("veteran", 0) or 0),
+                can_build_city=bool(action_map.get("build", False)),
+                move_directions=move_directions,
+            )
+        )
+    return units
+
+
+def _extract_city_summaries(snapshot: RawSnapshot) -> list[CitySummary]:
+    city_actions = _controller_actions(snapshot, "city")
+    cities: list[CitySummary] = []
+    for actor_id, city in sorted(snapshot.state.get("city", {}).items(), key=lambda item: int(item[0])):
+        action_map = city_actions.get(str(actor_id), city_actions.get(actor_id, {}))
+        production_options = [
+            _parse_target_name(raw_action_key, "change_unit_prod_")
+            for raw_action_key, enabled in sorted(action_map.items())
+            if enabled and raw_action_key.startswith("change_unit_prod_")
+        ] + [
+            _parse_target_name(raw_action_key, "change_improve_prod_")
+            for raw_action_key, enabled in sorted(action_map.items())
+            if enabled and raw_action_key.startswith("change_improve_prod_")
+        ]
+        cities.append(
+            CitySummary(
+                city_id=int(actor_id),
+                size=int(city.get("size", 0) or 0),
+                prod_food=int(city.get("prod_food", 0) or 0),
+                prod_shield=int(city.get("prod_shield", 0) or 0),
+                prod_trade=int(city.get("prod_trade", 0) or 0),
+                surplus_food=int(city.get("surplus_food", 0) or 0),
+                surplus_shield=int(city.get("surplus_shield", 0) or 0),
+                surplus_trade=int(city.get("surplus_trade", 0) or 0),
+                production_kind=(
+                    int(city.get("production_kind"))
+                    if city.get("production_kind") is not None
+                    else None
+                ),
+                production_value=(
+                    int(city.get("production_value"))
+                    if city.get("production_value") is not None
+                    else None
+                ),
+                turns_to_complete=(
+                    float(city.get("turns_to_prod_complete"))
+                    if city.get("turns_to_prod_complete") is not None
+                    else None
+                ),
+                production_options=production_options,
+            )
+        )
+    return cities
+
+
+def _build_summary(
+    snapshot: RawSnapshot,
+    metrics: SnapshotMetrics,
+    units: list[UnitSummary],
+    cities: list[CitySummary],
+    legal_actions: list[LegalAction],
+) -> str:
+    player = snapshot.state.get("player", {})
+    lines = [
+        f"Turn {snapshot.turn}",
+        f"Score {metrics.score:.1f}",
+        f"Map: {metrics.known_tiles} known tiles, {metrics.visible_tiles} visible tiles",
+        f"Economy: {player.get('my_gold', 0)} gold, science rate {player.get('my_science', 0)}%",
+        f"Cities: {metrics.city_count}",
+    ]
+    for city in cities[:5]:
+        lines.append(
+            f"- City {city.city_id}: size {city.size}, food {city.prod_food}/{city.surplus_food:+d}, "
+            f"shields {city.prod_shield}/{city.surplus_shield:+d}, trade {city.prod_trade}/{city.surplus_trade:+d}"
+        )
+    lines.append(f"Units: {metrics.unit_count}")
+    for unit in units[:8]:
+        lines.append(
+            f"- Unit {unit.unit_id}: {unit.unit_type}, hp {unit.health}, moves_left {unit.moves_left}, "
+            f"build_city={str(unit.can_build_city).lower()}, move_dirs={unit.move_directions}"
+        )
+    lines.append(f"Techs researched: {metrics.techs_researched}")
+    lines.append(f"Legal actions exposed: {len(legal_actions)}")
+    return "\n".join(lines)
+
+
+def prepare_observation(
+    snapshot: RawSnapshot,
+    *,
+    reward: float,
+    done: bool,
+    status: str,
+    metadata: dict[str, Any] | None = None,
+) -> PreparedObservation:
+    legal_actions, action_refs = _extract_legal_actions(snapshot)
+    metrics = extract_metrics(snapshot)
+    units = _extract_unit_summaries(snapshot)
+    cities = _extract_city_summaries(snapshot)
+    observation = FreecivObservation(
+        turn=snapshot.turn,
+        score=metrics.score,
+        known_tiles=metrics.known_tiles,
+        visible_tiles=metrics.visible_tiles,
+        city_count=metrics.city_count,
+        unit_count=metrics.unit_count,
+        techs_researched=metrics.techs_researched,
+        status=status,
+        summary=_build_summary(snapshot, metrics, units, cities, legal_actions),
+        units=units,
+        cities=cities,
+        legal_actions=legal_actions,
+        reward=reward,
+        done=done,
+        metadata=metadata or {},
+    )
+    return PreparedObservation(observation=observation, metrics=metrics, action_refs=action_refs)

build/lib/freeciv_env/client.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from freeciv_env.models import FreecivAction, FreecivObservation, FreecivState
+
+
+class FreecivEnv(EnvClient[FreecivAction, FreecivObservation, FreecivState]):
+    def _step_payload(self, action: FreecivAction) -> dict:
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: dict) -> StepResult[FreecivObservation]:
+        observation = FreecivObservation(**payload["observation"])
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: dict) -> FreecivState:
+        return FreecivState(**payload)

build/lib/freeciv_env/grpo.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+from freeciv_env.models import FreecivAction, FreecivObservation, LegalAction
+
+SYSTEM_PROMPT = (
+    "You are choosing the next action for a Freeciv agent. "
+    "Return only the integer index of the best legal action. "
+    "Do not output words, punctuation, JSON, or explanations."
+)
+
+TASK_PROMPT = (
+    "Pick the legal action index that maximizes immediate reward. "
+    "Invalid actions are penalized. Shorter outputs are better."
+)
+
+
+def format_action_line(index: int, action: LegalAction) -> str:
+    return f"{index}: {action.label}"
+
+
+def build_turn_prompt(observation: FreecivObservation, task_prompt: str = TASK_PROMPT) -> str:
+    action_lines = [format_action_line(index, action) for index, action in enumerate(observation.legal_actions)]
+    return (
+        f"{task_prompt}\n\n"
+        f"State:\n{observation.summary}\n\n"
+        f"Legal actions:\n" + "\n".join(action_lines) + "\n\n"
+        "Return exactly one integer index."
+    )
+
+
+def parse_action_choice(completion_text: str, legal_actions: Iterable[LegalAction]) -> FreecivAction | None:
+    legal_actions = list(legal_actions)
+    match = re.search(r"-?\d+", completion_text)
+    if match is None:
+        return None
+    index = int(match.group(0))
+    if index < 0 or index >= len(legal_actions):
+        return None
+    action = legal_actions[index]
+    if action.action_type == "end_turn":
+        return FreecivAction(action_type="end_turn")
+    if action.action_type == "move_unit":
+        return FreecivAction(action_type="move_unit", unit_id=action.unit_id, direction=action.direction)
+    if action.action_type == "build_city":
+        return FreecivAction(action_type="build_city", unit_id=action.unit_id)
+    if action.action_type == "set_city_production":
+        return FreecivAction(action_type="set_city_production", city_id=action.city_id, target=action.target)
+    if action.action_type == "set_research":
+        return FreecivAction(action_type="set_research", target=action.target)
+    raise ValueError(f"unsupported action_type: {action.action_type}")
+
+
+def action_priority(action: LegalAction) -> tuple[int, int]:
+    if action.action_type == "build_city":
+        return (500, 0)
+    if action.action_type == "set_research":
+        return (400, 0)
+    if action.action_type == "set_city_production":
+        bonus = 50 if (action.target or "") == "Settlers" else 0
+        return (300 + bonus, 0)
+    if action.action_type == "move_unit":
+        return (200, -(action.direction or 0))
+    if action.action_type == "end_turn":
+        return (0, 0)
+    return (-1000, 0)
+
+
+
+def oracle_action_index(legal_actions: Iterable[LegalAction]) -> int:
+    legal_actions = list(legal_actions)
+    if not legal_actions:
+        raise ValueError("no legal actions available")
+    best_index = 0
+    best_priority = action_priority(legal_actions[0])
+    for index, action in enumerate(legal_actions[1:], start=1):
+        priority = action_priority(action)
+        if priority > best_priority:
+            best_index = index
+            best_priority = priority
+    return best_index
+
+
+
+def reward_from_oracle(completions, best_index, **kwargs):
+    del kwargs
+    rewards = []
+    for completion, expected in zip(completions, best_index):
+        match = re.search(r"-?\d+", completion if isinstance(completion, str) else str(completion))
+        if match is None:
+            rewards.append(-0.25)
+            continue
+        chosen = int(match.group(0))
+        rewards.append(1.0 if chosen == int(expected) else 0.0)
+    return rewards

build/lib/freeciv_env/models.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from openenv.core.env_server.types import Action, Observation, State
+
+
+class UnitSummary(BaseModel):
+    unit_id: int = Field(..., description="Freeciv unit id")
+    unit_type: str = Field(..., description="Ruleset unit type name")
+    health: int = Field(0, description="Current health")
+    moves_left: int = Field(0, description="Movement points remaining")
+    home_city_id: int | None = Field(None, description="Home city id, if any")
+    veteran_level: int = Field(0, description="Veteran level")
+    can_build_city: bool = Field(False, description="Whether the unit can found a city now")
+    move_directions: list[int] = Field(default_factory=list, description="Legal move direction indexes")
+
+
+class CitySummary(BaseModel):
+    city_id: int = Field(..., description="Freeciv city id")
+    size: int = Field(..., description="Population size")
+    prod_food: int = Field(0, description="Gross food output")
+    prod_shield: int = Field(0, description="Gross shield output")
+    prod_trade: int = Field(0, description="Gross trade output")
+    surplus_food: int = Field(0, description="Net food surplus")
+    surplus_shield: int = Field(0, description="Net shield surplus")
+    surplus_trade: int = Field(0, description="Net trade surplus")
+    production_kind: int | None = Field(None, description="Current production kind enum from Freeciv")
+    production_value: int | None = Field(None, description="Current production value id from Freeciv")
+    turns_to_complete: float | None = Field(None, description="Turns until current production completes")
+    production_options: list[str] = Field(default_factory=list, description="Legal production targets")
+
+
+class LegalAction(BaseModel):
+    action_type: Literal[
+        "end_turn",
+        "move_unit",
+        "build_city",
+        "set_city_production",
+        "set_research",
+    ]
+    label: str = Field(..., description="Human-readable action label")
+    unit_id: int | None = Field(None, description="Target unit id")
+    city_id: int | None = Field(None, description="Target city id")
+    direction: int | None = Field(None, description="Freeciv direction index 0..7")
+    target: str | None = Field(None, description="Production or tech target name")
+    raw_action_key: str | None = Field(None, description="Underlying freeciv-bot action key")
+
+
+class FreecivAction(Action):
+    action_type: Literal[
+        "end_turn",
+        "move_unit",
+        "build_city",
+        "set_city_production",
+        "set_research",
+    ]
+    unit_id: int | None = None
+    city_id: int | None = None
+    direction: int | None = None
+    target: str | None = None
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "FreecivAction":
+        if self.action_type == "end_turn":
+            return self
+        if self.action_type == "move_unit":
+            if self.unit_id is None or self.direction is None:
+                raise ValueError("move_unit requires unit_id and direction")
+            return self
+        if self.action_type == "build_city":
+            if self.unit_id is None:
+                raise ValueError("build_city requires unit_id")
+            return self
+        if self.action_type == "set_city_production":
+            if self.city_id is None or not self.target:
+                raise ValueError("set_city_production requires city_id and target")
+            return self
+        if self.action_type == "set_research":
+            if not self.target:
+                raise ValueError("set_research requires target")
+            return self
+        raise ValueError(f"unsupported action_type: {self.action_type}")
+
+
+class FreecivObservation(Observation):
+    turn: int = Field(..., description="Current game turn")
+    score: float = Field(..., description="Current player score")
+    known_tiles: int = Field(..., description="Tiles known to the player")
+    visible_tiles: int = Field(..., description="Tiles currently visible to the player")
+    city_count: int = Field(..., description="Number of owned cities")
+    unit_count: int = Field(..., description="Number of owned units")
+    techs_researched: int = Field(..., description="Number of researched techs")
+    status: str = Field("ok", description="High-level environment status")
+    summary: str = Field(..., description="Compact text summary for LLMs")
+    units: list[UnitSummary] = Field(default_factory=list, description="Compact unit summaries")
+    cities: list[CitySummary] = Field(default_factory=list, description="Compact city summaries")
+    legal_actions: list[LegalAction] = Field(default_factory=list, description="Legal actions exposed by the environment")
+    reward: float = Field(0.0, description="Reward from the last action")
+    done: bool = Field(False, description="Whether the episode is done")
+
+
+class FreecivState(State):
+    turn: int = Field(0, description="Current game turn")
+    score: float = Field(0.0, description="Current player score")
+    known_tiles: int = Field(0, description="Known tiles")
+    visible_tiles: int = Field(0, description="Visible tiles")
+    city_count: int = Field(0, description="Owned city count")
+    unit_count: int = Field(0, description="Owned unit count")
+    techs_researched: int = Field(0, description="Researched tech count")

build/lib/freeciv_env/runtime.py

@@ -0,0 +1,401 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import time
+from typing import Protocol
+from urllib.parse import urlencode, urlparse
+from urllib.request import Request, urlopen
+
+from freeciv_env.adapter import ActionRef, RawSnapshot
+
+
+class FreecivSession(Protocol):
+    def reset(self, seed: int | None = None) -> RawSnapshot: ...
+
+    def apply_action(self, action_ref: ActionRef) -> RawSnapshot: ...
+
+    def end_turn(self) -> RawSnapshot: ...
+
+    def close(self) -> None: ...
+
+
+class _InteractiveBot:
+    def __init__(self, session: "LiveFreecivSession"):
+        from freecivbot.bot.base_bot import BaseBot
+
+        class InteractiveBotImpl(BaseBot):
+            def __init__(self, owner: "LiveFreecivSession"):
+                super().__init__()
+                self._owner = owner
+
+            def conduct_turn(self, pplayer, info_controls, end_turn_hook):
+                super().conduct_turn(pplayer, info_controls, end_turn_hook)
+                self._publish_snapshot()
+
+            def calculate_next_move(self):
+                if self._turn_active:
+                    self._publish_snapshot()
+
+            def _publish_snapshot(self):
+                self._acquire_state()
+                self._owner._publish_snapshot(
+                    RawSnapshot(
+                        turn=self.turn,
+                        state=self._turn_state,
+                        actions=self._turn_opts,
+                    )
+                )
+
+        self.impl = InteractiveBotImpl(session)
+
+
+class _ConfiguredCivClient:
+    def __init__(self, bot, user_name: str, *, client_port: int, visual_monitor: bool = False):
+        from freecivbot.civclient import CivClient
+
+        class ConfiguredCivClientImpl(CivClient):
+            def init_control(self, ws_client):
+                self.ws_client = ws_client
+                self.init_controller()
+                if self.visual_monitor:
+                    self.monitor.start_monitor()
+                login_message = {
+                    "pid": 4,
+                    "username": self.user_name,
+                    "capability": "+Freeciv.Web.Devel-3.2",
+                    "version_label": "-dev",
+                    "major_version": 3,
+                    "minor_version": 1,
+                    "patch_version": 90,
+                    "port": self.client_port,
+                    "password": None,
+                    "subject": None,
+                }
+                self.ws_client.send(login_message)
+
+            def handle_chat_msg(self, packet):
+                from freecivbot.utils.fc_events import E_UNDEFINED
+
+                message = packet["message"]
+                conn_id = packet["conn_id"]
+                event = packet["event"]
+
+                if message is None:
+                    return
+                if event is None or event < 0 or event >= E_UNDEFINED:
+                    print("Undefined message event type")
+                    print(packet)
+                    print("\r\n")
+                    packet["event"] = event = E_UNDEFINED
+
+                if conn_id in self.clstate.connections:
+                    message = "<b>" + self.clstate.connections[conn_id]["username"] + ":</b>" + message
+                else:
+                    if "/metamessage" in message:
+                        return
+                    if "Metaserver message string" in message:
+                        return
+
+                packet["message"] = message
+                print(packet)
+                print("\r\n")
+
+                if "You are logged in as" in message:
+                    self.ws_client.send_message("/set minplayers 1")
+                    self.prepare_game()
+
+            def handle_conn_info(self, packet):
+                from freecivbot.connectivity.client_state import C_S_PREPARING
+                from freecivbot.utils.freecivlog import freelog
+
+                pconn = self.clstate.find_conn_by_id(packet["id"])
+
+                if not packet["used"]:
+                    if pconn is None:
+                        freelog(f"Server removed unknown connection {packet['id']}")
+                        return
+                    self.clstate.client_remove_cli_conn(pconn)
+                    pconn = None
+                else:
+                    pplayer = self.player_ctrl.valid_player_by_number(packet["player_num"])
+                    if pplayer is None:
+                        return
+                    packet["playing"] = pplayer
+
+                    if self.clstate.has_id(packet["id"]):
+                        self.clstate.init_state(packet)
+
+                    self.clstate.conn_list_append(packet)
+
+                if self.clstate.has_id(packet["id"]) and self.clstate.cur_player() != packet["playing"]:
+                    self.clstate.set_client_state(C_S_PREPARING)
+
+        self.impl = ConfiguredCivClientImpl(
+            bot,
+            user_name,
+            client_port=client_port,
+            visual_monitor=visual_monitor,
+        )
+
+
+class _ConfiguredCivConnection:
+    def __init__(self, civ_client, base_url: str, *, owner: "LiveFreecivSession", wait_for_server: int = 120, retry_interval: int = 5):
+        from math import ceil
+
+        import websocket
+
+        self._websocket = websocket
+        self.client = civ_client
+        self.base_url = base_url
+        self._owner = owner
+        self._loop = None
+        self._owner._connection = self
+        self.civserverport = self._reserve_client_port(base_url, civ_client.client_port)
+        self.client.client_port = self.civserverport
+        self.proxyport = 1000 + self.civserverport
+        self._retry_interval = retry_interval
+        self._num_retries = int(ceil(wait_for_server / retry_interval))
+        self._cur_retry = 0
+        self._ws_url = self._build_ws_url(base_url)
+        self.network_init()
+
+    def _build_ws_url(self, base_url: str) -> str:
+        parsed = urlparse(base_url)
+        scheme = "wss" if parsed.scheme == "https" else "ws"
+        host = parsed.hostname or "localhost"
+        port = parsed.port
+        if port is None:
+            port = 443 if scheme == "wss" else 80
+        return f"{scheme}://{host}:{port}/civsocket/{self.proxyport}"
+
+    def _reserve_client_port(self, base_url: str, requested_port: int) -> int:
+        parsed = urlparse(base_url)
+        scheme = parsed.scheme or "http"
+        host = parsed.hostname or "localhost"
+        port = parsed.port
+        if port is None:
+            port = 443 if scheme == "https" else 80
+        query = urlencode({"civserverport": requested_port})
+        launcher_url = f"{scheme}://{host}:{port}/civclientlauncher?{query}"
+        request = Request(launcher_url, method="POST")
+        with urlopen(request, timeout=10) as response:
+            result = response.headers.get("result")
+            reserved_port = response.headers.get("port")
+        if result != "success" or reserved_port is None:
+            raise RuntimeError(f"failed to reserve freeciv client port via {launcher_url}")
+        return int(reserved_port)
+
+    def _retry(self):
+        self._cur_retry += 1
+        time.sleep(self._retry_interval)
+        return self._detect_server_up()
+
+    def _detect_server_up(self):
+        ws = self._websocket.WebSocket()
+        try:
+            ws.connect(self._ws_url, timeout=10)
+            return True
+        except Exception as err:
+            print("Connect not successful:", err, " retrying in %s seconds." % self._retry_interval)
+            if self._cur_retry < self._num_retries:
+                return self._retry()
+            return False
+        finally:
+            try:
+                ws.close()
+            except Exception:
+                pass
+
+    def network_init(self):
+        self._cur_retry = 0
+        print("Connecting to server at %s ..." % self.base_url)
+        if self._detect_server_up():
+            self.websocket_init()
+        else:
+            print("Connection could not be established!")
+
+    def websocket_init(self):
+        from tornado import ioloop
+
+        from freecivbot.connectivity.clinet import CivWSClient
+
+        asyncio.set_event_loop(asyncio.new_event_loop())
+        ioloop.IOLoop.clear_current()
+        self._loop = ioloop.IOLoop.current()
+
+        client = CivWSClient(self.client)
+
+        def send_json(data):
+            if not client._ws_connection:
+                raise RuntimeError("Web socket connection is closed.")
+            msg = json.dumps(data, separators=(",", ":"))
+            client._ws_connection.write_message(msg)
+
+        client.send = send_json
+        client.connect(self._ws_url)
+
+        try:
+            self._loop.start()
+        except KeyboardInterrupt:
+            client.close()
+
+    def submit(self, fn) -> None:
+        if self._loop is None:
+            raise RuntimeError("freeciv connection loop is not ready")
+        done = threading.Event()
+        error: BaseException | None = None
+
+        def run():
+            nonlocal error
+            try:
+                fn()
+            except BaseException as exc:
+                error = exc
+            finally:
+                done.set()
+
+        self._loop.add_callback(run)
+        if not done.wait(timeout=10):
+            raise TimeoutError("timed out dispatching action to freeciv loop")
+        if error is not None:
+            raise error
+
+    def close(self) -> None:
+        if self._loop is None:
+            return
+        self.submit(self.client.close)
+
+
+class LiveFreecivSession:
+    def __init__(
+        self,
+        *,
+        username: str = "openenvbot",
+        client_port: int = 6000,
+        base_url: str = "http://localhost",
+        turn_timeout_s: float = 60.0,
+    ):
+        self.username = username
+        self.client_port = client_port
+        self.base_url = base_url
+        self.turn_timeout_s = turn_timeout_s
+
+        self._bot_wrapper: _InteractiveBot | None = None
+        self._client = None
+        self._connection: _ConfiguredCivConnection | None = None
+        self._thread: threading.Thread | None = None
+        self._ready = threading.Event()
+        self._snapshot_lock = threading.Lock()
+        self._snapshot: RawSnapshot | None = None
+        self._thread_error: BaseException | None = None
+        self._reset_counter = 0
+        self._session_seed = time.monotonic_ns() % 1_000_000
+
+    def reset(self, seed: int | None = None) -> RawSnapshot:
+        del seed
+        self.close()
+        self._reset_counter += 1
+        username = self._next_username()
+        client_port = self.client_port + ((self._session_seed + self._reset_counter - 1) % 3)
+
+        self._ready.clear()
+        self._thread_error = None
+        self._snapshot = None
+
+        self._bot_wrapper = _InteractiveBot(self)
+        self._client = _ConfiguredCivClient(
+            self._bot_wrapper.impl,
+            username,
+            client_port=client_port,
+            visual_monitor=False,
+        ).impl
+
+        def run() -> None:
+            try:
+                _ConfiguredCivConnection(self._client, self.base_url, owner=self)
+            except BaseException as exc:  # pragma: no cover - surfaced in waiters
+                self._thread_error = exc
+                self._ready.set()
+
+        self._thread = threading.Thread(target=run, name="freeciv-live-session", daemon=True)
+        self._thread.start()
+        return self._wait_for_snapshot("reset")
+
+    def apply_action(self, action_ref: ActionRef) -> RawSnapshot:
+        snapshot = self._require_snapshot()
+        action_list = snapshot.actions[action_ref.controller]
+        valid_actions = action_list.get_actions(action_ref.actor_id, valid_only=True)
+        action = None if valid_actions is None else valid_actions.get(action_ref.raw_action_key)
+        if action is None:
+            raise ValueError(
+                f"action {action_ref.raw_action_key} is no longer valid for {action_ref.controller}:{action_ref.actor_id}"
+            )
+        self._ready.clear()
+        connection = self._require_connection()
+        connection.submit(lambda: action_list.trigger_validated_action(action))
+        return self._wait_for_snapshot(action_ref.raw_action_key)
+
+    def end_turn(self) -> RawSnapshot:
+        if self._bot_wrapper is None:
+            raise RuntimeError("session has not been reset")
+        self._ready.clear()
+        connection = self._require_connection()
+        connection.submit(self._bot_wrapper.impl.end_turn)
+        return self._wait_for_snapshot("end_turn")
+
+    def close(self) -> None:
+        if self._connection is not None:
+            try:
+                self._connection.close()
+            except Exception:
+                pass
+        elif self._client is not None:
+            try:
+                self._client.close()
+            except Exception:
+                pass
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=5)
+        self._bot_wrapper = None
+        self._client = None
+        self._connection = None
+        self._thread = None
+        self._snapshot = None
+        self._thread_error = None
+        self._ready.clear()
+
+    def _publish_snapshot(self, snapshot: RawSnapshot) -> None:
+        with self._snapshot_lock:
+            self._snapshot = snapshot
+        self._ready.set()
+
+    def _next_username(self) -> str:
+        suffix = str(self._session_seed + self._reset_counter)
+        prefix_len = max(1, 31 - len(suffix))
+        return f"{self.username[:prefix_len]}{suffix}"
+
+    def _require_connection(self) -> _ConfiguredCivConnection:
+        if self._connection is None:
+            raise RuntimeError("freeciv connection is not ready")
+        return self._connection
+
+    def _require_snapshot(self) -> RawSnapshot:
+        with self._snapshot_lock:
+            if self._snapshot is None:
+                raise RuntimeError("no live snapshot is available")
+            return self._snapshot
+
+    def _wait_for_snapshot(self, reason: str) -> RawSnapshot:
+        deadline = time.monotonic() + self.turn_timeout_s
+        while time.monotonic() < deadline:
+            if self._thread_error is not None:
+                raise RuntimeError(f"freeciv session failed during {reason}") from self._thread_error
+            if self._ready.wait(timeout=0.1):
+                if self._thread_error is not None:
+                    raise RuntimeError(f"freeciv session failed during {reason}") from self._thread_error
+                snapshot = self._require_snapshot()
+                if snapshot is not None:
+                    return snapshot
+        raise TimeoutError(f"timed out waiting for freeciv snapshot during {reason}")

build/lib/freeciv_env/server/__init__.py

@@ -0,0 +1,3 @@
+from freeciv_env.server.freeciv_environment import FreecivEnvironment
+
+__all__ = ["FreecivEnvironment"]

build/lib/freeciv_env/server/app.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+
+from openenv.core.env_server import create_app
+
+from freeciv_env.models import FreecivAction, FreecivObservation
+from freeciv_env.runtime import LiveFreecivSession
+from freeciv_env.server.freeciv_environment import FreecivEnvironment
+
+
+def create_live_session() -> LiveFreecivSession:
+    return LiveFreecivSession(
+        username=os.getenv("FREECIV_USERNAME", "openenvbot"),
+        client_port=int(os.getenv("FREECIV_CLIENT_PORT", "6000")),
+        base_url=os.getenv("FREECIV_SERVER_URL", "http://localhost"),
+        turn_timeout_s=float(os.getenv("FREECIV_TURN_TIMEOUT_S", "60")),
+    )
+
+
+def create_freeciv_app(*, session_factory=create_live_session, max_turns: int | None = None):
+    if max_turns is None:
+        max_turns = int(os.getenv("FREECIV_MAX_TURNS", "50"))
+    return create_app(
+        lambda: FreecivEnvironment(session_factory=session_factory, max_turns=max_turns),
+        FreecivAction,
+        FreecivObservation,
+        env_name="freeciv_env",
+    )
+
+
+app = create_freeciv_app()
+
+
+def main() -> None:
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000, ws_ping_interval=300, ws_ping_timeout=300)
+
+
+if __name__ == "__main__":
+    main()

build/lib/freeciv_env/server/freeciv_environment.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from typing import Callable
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+
+from freeciv_env.adapter import (
+    ActionLookupKey,
+    ActionRef,
+    PreparedObservation,
+    RawSnapshot,
+    SnapshotMetrics,
+    action_lookup_key,
+    prepare_observation,
+)
+from freeciv_env.models import FreecivAction, FreecivObservation, FreecivState
+from freeciv_env.runtime import FreecivSession
+
+
+class FreecivEnvironment(Environment[FreecivAction, FreecivObservation, FreecivState]):
+    SUPPORTS_CONCURRENT_SESSIONS = False
+
+    def __init__(self, session_factory: Callable[[], FreecivSession], max_turns: int = 50):
+        super().__init__()
+        self._session_factory = session_factory
+        self.max_turns = max_turns
+        self._session: FreecivSession | None = None
+        self._snapshot: RawSnapshot | None = None
+        self._metrics: SnapshotMetrics | None = None
+        self._action_refs: dict[ActionLookupKey, ActionRef] = {}
+        self._state = FreecivState(episode_id=str(uuid4()), step_count=0)
+
+    def reset(
+        self,
+        seed: int | None = None,
+        episode_id: str | None = None,
+        **kwargs,
+    ) -> FreecivObservation:
+        del kwargs
+        self.close()
+        self._session = self._session_factory()
+        snapshot = self._session.reset(seed=seed)
+        prepared = prepare_observation(
+            snapshot,
+            reward=0.0,
+            done=self._is_done(snapshot),
+            status="ready",
+            metadata={},
+        )
+        self._commit(snapshot, prepared, episode_id=episode_id or str(uuid4()))
+        return prepared.observation
+
+    def step(
+        self,
+        action: FreecivAction,
+        timeout_s: float | None = None,
+        **kwargs,
+    ) -> FreecivObservation:
+        del timeout_s, kwargs
+        if self._session is None or self._snapshot is None or self._metrics is None:
+            raise RuntimeError("environment must be reset before step")
+
+        self._state.step_count += 1
+        if action.action_type == "end_turn":
+            next_snapshot = self._session.end_turn()
+            reward = self._reward_for_transition(action, self._metrics, next_snapshot)
+            prepared = prepare_observation(
+                next_snapshot,
+                reward=reward,
+                done=self._is_done(next_snapshot),
+                status="ok",
+                metadata={},
+            )
+            self._commit(next_snapshot, prepared, episode_id=self._state.episode_id)
+            return prepared.observation
+
+        ref = self._action_refs.get(action_lookup_key(action))
+        if ref is None:
+            prepared = prepare_observation(
+                self._snapshot,
+                reward=-0.25,
+                done=self._is_done(self._snapshot),
+                status="invalid_action",
+                metadata={"error": "action is not currently legal"},
+            )
+            self._commit(self._snapshot, prepared, episode_id=self._state.episode_id, replace_snapshot=False)
+            return prepared.observation
+
+        next_snapshot = self._session.apply_action(ref)
+        reward = self._reward_for_transition(action, self._metrics, next_snapshot)
+        prepared = prepare_observation(
+            next_snapshot,
+            reward=reward,
+            done=self._is_done(next_snapshot),
+            status="ok",
+            metadata={},
+        )
+        self._commit(next_snapshot, prepared, episode_id=self._state.episode_id)
+        return prepared.observation
+
+    @property
+    def state(self) -> FreecivState:
+        return self._state
+
+    def close(self) -> None:
+        if self._session is not None:
+            self._session.close()
+        self._session = None
+        self._snapshot = None
+        self._metrics = None
+        self._action_refs = {}
+
+    def _commit(
+        self,
+        snapshot: RawSnapshot,
+        prepared: PreparedObservation,
+        *,
+        episode_id: str,
+        replace_snapshot: bool = True,
+    ) -> None:
+        if replace_snapshot:
+            self._snapshot = snapshot
+        self._metrics = prepared.metrics
+        self._action_refs = prepared.action_refs
+        self._state = FreecivState(
+            episode_id=episode_id,
+            step_count=self._state.step_count,
+            turn=prepared.observation.turn,
+            score=prepared.observation.score,
+            known_tiles=prepared.observation.known_tiles,
+            visible_tiles=prepared.observation.visible_tiles,
+            city_count=prepared.observation.city_count,
+            unit_count=prepared.observation.unit_count,
+            techs_researched=prepared.observation.techs_researched,
+        )
+
+    def _reward_for_transition(
+        self,
+        action: FreecivAction,
+        previous: SnapshotMetrics,
+        next_snapshot: RawSnapshot,
+    ) -> float:
+        from freeciv_env.adapter import extract_metrics
+
+        current = extract_metrics(next_snapshot)
+        reward = {
+            "end_turn": 0.0,
+            "move_unit": 0.01,
+            "build_city": 0.10,
+            "set_city_production": 0.05,
+            "set_research": 0.05,
+        }[action.action_type]
+        reward += max(current.score - previous.score, 0.0) * 0.02
+        reward += max(current.known_tiles - previous.known_tiles, 0) * 0.01
+        reward += max(current.city_count - previous.city_count, 0) * 0.50
+        reward += max(current.techs_researched - previous.techs_researched, 0) * 0.25
+        return float(reward)
+
+    def _is_done(self, snapshot: RawSnapshot) -> bool:
+        player = snapshot.state.get("player", {})
+        alive = bool(player.get("my_is_alive", True))
+        return (not alive) or snapshot.turn >= self.max_turns

build/lib/server/app.py

@@ -0,0 +1,10 @@
+from freeciv_env.server.app import app as app
+from freeciv_env.server.app import main as _main
+
+
+def main() -> None:
+    _main()
+
+
+if __name__ == "__main__":
+    main()

freeciv_env.egg-info/PKG-INFO

@@ -17,6 +17,19 @@ Requires-Dist: datasets>=4.0.0; extra == "train"
 Requires-Dist: trl>=0.24.0; extra == "train"
 Requires-Dist: unsloth>=2026.3.4; extra == "train"
 
+---
+title: Freeciv Environment Server
+emoji: 🎮
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
 # freeciv-env
 
 OpenEnv environment for Freeciv, built on top of `freeciv-bot`.

freeciv_env/server/Dockerfile

@@ -1,6 +1,8 @@
 ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
 FROM ${BASE_IMAGE} AS builder
 
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app/env
 COPY . /app/env