histrategy-sdk 0.1.0__tar.gz

histrategy_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: histrategy-sdk
+Version: 0.1.0
+Summary: Python SDK for 三國志略 (Histrategy) — AI-powered Three Kingdoms strategy game engine
+Author: Emergence Science
+License-Expression: MIT
+Keywords: three-kingdoms,strategy-game,ai-game,llm,deepseek
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment :: Turn Based Strategy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: engine
+Requires-Dist: histrategy-engine>=0.1.0; extra == "engine"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+
+# histrategy-sdk
+
+Python SDK for [三國志略 (Histrategy)](https://emergence.science/play/histrategy) — AI-powered Three Kingdoms strategy game.
+
+```bash
+pip install histrategy-sdk
+```
+
+## Quick Start
+
+### Server Client (HTTP)
+
+```python
+from histrategy_sdk import ServerClient
+
+client = ServerClient()
+
+# Create a new game as Shu Han (刘备)
+game = client.create_game(faction="shu")
+print(game["narrative"])
+# → "建安十二年冬，刘备屯兵新野，寄居刘表麾下..."
+
+# Get strategic suggestions
+plan = client.get_plan(game["game_id"])
+for s in plan["suggestions"]:
+    print(f"  • {s}")
+
+# Execute a command
+result = client.execute_command(game["game_id"], "联吴抗曹，攻打襄阳")
+print(result["narrative"])
+print(f"Token usage: {result['token_usage']}")
+```
+
+### Direct Engine (In-Process)
+
+```bash
+pip install histrategy-sdk[engine]
+```
+
+```python
+from histrategy_sdk import DirectEngine
+
+engine = DirectEngine(faction="cao")  # Play as 曹操
+intro = engine.get_intro()
+result = engine.execute("南征刘备，先取新野")
+
+# Save game state
+save = engine.to_dict()
+
+# Restore later
+engine2 = DirectEngine.from_dict(save)
+```
+
+## API Reference
+
+### `ServerClient`
+
+| Method | Description |
+|--------|-------------|
+| `create_game(faction, scenario)` | Create new game → `GameIntro` |
+| `get_plan(game_id)` | Get advisor suggestions → `PlanData` |
+| `execute_command(game_id, decision)` | Process turn → `TurnResult` |
+| `get_status(game_id)` | Get faction resources → `FactionStatus` |
+| `restore_game(world_state)` | Restore from save → `RestoreResult` |
+| `health()` | Check server status |
+
+### `DirectEngine`
+
+| Method | Description |
+|--------|-------------|
+| `DirectEngine(faction, llm_api_key)` | Create new in-process engine |
+| `get_intro()` | Get intro scene → `GameIntro` |
+| `get_plan()` | Get suggestions → `PlanData` |
+| `execute(decision)` | Process turn → `TurnResult` |
+| `get_status()` | Get faction status → `FactionStatus` |
+| `to_dict()` | Serialize game state |
+| `DirectEngine.from_dict(data)` | Restore from saved state |
+
+### `TurnResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `narrative` | `str` | AI-generated historical chronicle |
+| `aftermath` | `str` | Resource changes summary |
+| `state_changes` | `dict` | Numerical state deltas |
+| `new_suggestions` | `list[str]` | Next-turn strategy suggestions |
+| `token_usage` | `TokenUsage` | LLM token consumption |
+| `game_over` | `dict \| None` | Victory/defeat message |
+| `faction_status` | `FactionStatus` | Current resources and territories |
+
+## License
+
+MIT — Emergence Science

histrategy_sdk-0.1.0/README.md

@@ -0,0 +1,93 @@
+# histrategy-sdk
+
+Python SDK for [三國志略 (Histrategy)](https://emergence.science/play/histrategy) — AI-powered Three Kingdoms strategy game.
+
+```bash
+pip install histrategy-sdk
+```
+
+## Quick Start
+
+### Server Client (HTTP)
+
+```python
+from histrategy_sdk import ServerClient
+
+client = ServerClient()
+
+# Create a new game as Shu Han (刘备)
+game = client.create_game(faction="shu")
+print(game["narrative"])
+# → "建安十二年冬，刘备屯兵新野，寄居刘表麾下..."
+
+# Get strategic suggestions
+plan = client.get_plan(game["game_id"])
+for s in plan["suggestions"]:
+    print(f"  • {s}")
+
+# Execute a command
+result = client.execute_command(game["game_id"], "联吴抗曹，攻打襄阳")
+print(result["narrative"])
+print(f"Token usage: {result['token_usage']}")
+```
+
+### Direct Engine (In-Process)
+
+```bash
+pip install histrategy-sdk[engine]
+```
+
+```python
+from histrategy_sdk import DirectEngine
+
+engine = DirectEngine(faction="cao")  # Play as 曹操
+intro = engine.get_intro()
+result = engine.execute("南征刘备，先取新野")
+
+# Save game state
+save = engine.to_dict()
+
+# Restore later
+engine2 = DirectEngine.from_dict(save)
+```
+
+## API Reference
+
+### `ServerClient`
+
+| Method | Description |
+|--------|-------------|
+| `create_game(faction, scenario)` | Create new game → `GameIntro` |
+| `get_plan(game_id)` | Get advisor suggestions → `PlanData` |
+| `execute_command(game_id, decision)` | Process turn → `TurnResult` |
+| `get_status(game_id)` | Get faction resources → `FactionStatus` |
+| `restore_game(world_state)` | Restore from save → `RestoreResult` |
+| `health()` | Check server status |
+
+### `DirectEngine`
+
+| Method | Description |
+|--------|-------------|
+| `DirectEngine(faction, llm_api_key)` | Create new in-process engine |
+| `get_intro()` | Get intro scene → `GameIntro` |
+| `get_plan()` | Get suggestions → `PlanData` |
+| `execute(decision)` | Process turn → `TurnResult` |
+| `get_status()` | Get faction status → `FactionStatus` |
+| `to_dict()` | Serialize game state |
+| `DirectEngine.from_dict(data)` | Restore from saved state |
+
+### `TurnResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `narrative` | `str` | AI-generated historical chronicle |
+| `aftermath` | `str` | Resource changes summary |
+| `state_changes` | `dict` | Numerical state deltas |
+| `new_suggestions` | `list[str]` | Next-turn strategy suggestions |
+| `token_usage` | `TokenUsage` | LLM token consumption |
+| `game_over` | `dict \| None` | Victory/defeat message |
+| `faction_status` | `FactionStatus` | Current resources and territories |
+
+## License
+
+MIT — Emergence Science

histrategy_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "histrategy-sdk"
+version = "0.1.0"
+description = "Python SDK for 三國志略 (Histrategy) — AI-powered Three Kingdoms strategy game engine"
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+authors = [{name = "Emergence Science"}]
+keywords = ["three-kingdoms", "strategy-game", "ai-game", "llm", "deepseek"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Games/Entertainment :: Turn Based Strategy",
+]
+
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+engine = ["histrategy-engine>=0.1.0"]
+dev = ["pytest>=8", "pytest-cov>=5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-v", "--tb=short"]

histrategy_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

histrategy_sdk-0.1.0/src/histrategy_sdk/__init__.py

@@ -0,0 +1,79 @@
+"""histrategy-sdk — Python SDK for 三國志略 (Histrategy).
+
+三國志略 is an AI-powered Three Kingdoms strategy game where the LLM acts
+as the game engine — generating advisor speeches, strategic suggestions,
+consequences, and NPC actions based on actual world state.
+
+Quick Start
+-----------
+
+**Option A: Remote Server (lightweight, no engine deps)**
+
+    from histrategy_sdk import ServerClient
+
+    client = ServerClient()
+    game = client.create_game(faction="shu")
+    result = client.execute_command(game["game_id"], "联吴抗曹，攻打襄阳")
+    print(result["narrative"])
+
+**Option B: Direct Engine (in-process, needs histrategy-engine)**
+
+    pip install histrategy-sdk[engine]
+
+    from histrategy_sdk import DirectEngine
+
+    engine = DirectEngine(faction="shu")
+    intro = engine.get_intro()
+    result = engine.execute("联吴抗曹")
+    print(result["narrative"])
+
+    # Save and restore
+    data = engine.to_dict()
+    engine2 = DirectEngine.from_dict(data)
+"""
+
+from ._client import ServerClient
+from .exceptions import (
+    APIError,
+    ConnectionError,
+    EngineNotAvailableError,
+    GameNotFoundError,
+    HistrategyError,
+    TurnExecutionError,
+)
+from .types import (
+    FactionStatus,
+    GameIntro,
+    PlanData,
+    RestoreResult,
+    TokenUsage,
+    TurnResult,
+)
+
+# DirectEngine is optional — import fails gracefully if histrategy not installed
+try:
+    from ._engine import DirectEngine
+except ImportError:
+    DirectEngine = None  # type: ignore[assignment]
+
+__all__ = [
+    # Client
+    "ServerClient",
+    # Engine (optional)
+    "DirectEngine",
+    # Types
+    "FactionStatus",
+    "GameIntro",
+    "PlanData",
+    "RestoreResult",
+    "TokenUsage",
+    "TurnResult",
+    # Exceptions
+    "HistrategyError",
+    "GameNotFoundError",
+    "ConnectionError",
+    "APIError",
+    "EngineNotAvailableError",
+    "TurnExecutionError",
+]
+__version__ = "0.1.0"

histrategy_sdk-0.1.0/src/histrategy_sdk/_client.py

@@ -0,0 +1,230 @@
+"""ServerClient — HTTP client for remote histrategy server.
+
+Use this when the game engine runs on a separate server (Railway, etc.).
+Lightweight: only depends on httpx.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .exceptions import APIError, ConnectionError, GameNotFoundError
+from .types import (
+    FactionStatus,
+    GameIntro,
+    PlanData,
+    RestoreResult,
+    TurnResult,
+)
+
+
+class ServerClient:
+    """HTTP client for a remote histrategy game server.
+
+    Usage:
+        client = ServerClient(base_url="https://histrategy.example.com")
+        game = client.create_game(faction="shu")
+        result = client.execute_command(game["game_id"], "联吴抗曹")
+        print(result["narrative"])
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://histrategy-emergence.railway.app",
+        timeout: float = 120.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> ServerClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ── HTTP helpers ──────────────────────────────────────
+
+    def _get(self, path: str) -> dict:
+        try:
+            r = self._client.get(f"{self.base_url}{path}")
+        except httpx.RequestError as e:
+            raise ConnectionError(f"Could not reach server: {e}") from e
+        if r.status_code == 404:
+            raise GameNotFoundError(f"Game not found at {path}")
+        if not r.is_success:
+            detail = ""
+            try:
+                detail = r.json().get("detail", r.text)
+            except Exception:
+                detail = r.text
+            raise APIError(r.status_code, detail)
+        return r.json()
+
+    def _post(self, path: str, json: dict | None = None) -> dict:
+        try:
+            r = self._client.post(f"{self.base_url}{path}", json=json)
+        except httpx.RequestError as e:
+            raise ConnectionError(f"Could not reach server: {e}") from e
+        if r.status_code == 404:
+            raise GameNotFoundError(f"Resource not found at {path}")
+        if not r.is_success:
+            detail = ""
+            try:
+                detail = r.json().get("detail", r.text)
+            except Exception:
+                detail = r.text
+            raise APIError(r.status_code, detail)
+        return r.json()
+
+    # ── Game API ──────────────────────────────────────────
+
+    def create_game(
+        self,
+        faction: str = "shu",
+        scenario: str = "207",
+        llm_api_key: str | None = None,
+        session_id: str | None = None,
+        language_style: str | None = None,
+    ) -> GameIntro:
+        """Create a new game and return the intro scene.
+
+        Args:
+            faction: "shu" (刘备), "cao" (曹操), or "wu" (孙权)
+            scenario: Scenario ID, currently only "207"
+            llm_api_key: User's own DeepSeek API key (not persisted)
+            session_id: Orchestrator session ID for persistence
+            language_style: "classical" (古文风) or "vernacular" (白话文)
+
+        Returns:
+            GameIntro with game_id, intro narrative, suggestions, faction status
+        """
+        body: dict[str, Any] = {"faction": faction, "scenario": scenario}
+        if llm_api_key:
+            body["llm_api_key"] = llm_api_key
+        if session_id:
+            body["session_id"] = session_id
+        if language_style:
+            body["language_style"] = language_style
+
+        data = self._post("/api/games", body)
+        intro = data.get("intro", {})
+        if isinstance(intro, dict):
+            narrative = intro.get("narrative", "")
+            suggestions = intro.get("new_choices", [])
+        else:
+            narrative = str(intro)
+            suggestions = []
+
+        return GameIntro(
+            game_id=data["game_id"],
+            scenario=data.get("scenario", scenario),
+            faction=data.get("faction", faction),
+            narrative=narrative,
+            suggestions=suggestions,
+            faction_status=FactionStatus(**data.get("faction_status", {})),
+        )
+
+    def get_status(self, game_id: str) -> FactionStatus:
+        """Get current faction status for a game.
+
+        Returns:
+            FactionStatus with strength, food, treasury, territories, etc.
+        """
+        data = self._get(f"/api/games/{game_id}")
+        return FactionStatus(**data.get("faction_status", {}))
+
+    def get_plan(self, game_id: str) -> PlanData:
+        """Get Plan Mode: advisor court dialogue + strategic suggestions.
+
+        Returns:
+            PlanData with court_dialogue, suggestions, faction_status
+        """
+        data = self._post(f"/api/games/{game_id}/plan")
+        return PlanData(
+            game_id=data["game_id"],
+            court_dialogue=data.get("court_dialogue", ""),
+            suggestions=data.get("suggestions", []),
+            season_summary=data.get("season_summary", ""),
+            year=data.get("year", 207),
+            season=data.get("season", "春"),
+            turn=data.get("turn", 1),
+            faction_status=FactionStatus(**data.get("faction_status", {})),
+        )
+
+    def execute_command(self, game_id: str, decision: str) -> TurnResult:
+        """Submit a player decision and process the turn.
+
+        Args:
+            game_id: Game ID from create_game / restore_game
+            decision: Free-text player decision (e.g. "联吴抗曹，攻打襄阳")
+
+        Returns:
+            TurnResult with narrative, aftermath, state_changes, suggestions, etc.
+        """
+        data = self._post(f"/api/games/{game_id}/command", {"decision": decision})
+
+        # Build token usage from response (may be empty if not tracked)
+        token_usage: dict[str, int] = {}
+        for key in ("command_tokens", "plan_tokens", "npc_tokens", "sim_tokens"):
+            token_usage[key] = data.get(key, 0)
+
+        from .types import TokenUsage as _TU
+
+        return TurnResult(
+            game_id=data["game_id"],
+            narrative=data.get("narrative", ""),
+            aftermath=data.get("aftermath", ""),
+            state_changes=data.get("state_changes", {}),
+            events_occurred=data.get("events_occurred", []),
+            npc_actions=data.get("npc_actions", []),
+            new_suggestions=data.get("new_suggestions", []),
+            game_over=data.get("game_over"),
+            faction_status=FactionStatus(**data.get("faction_status", {})),
+            year=data.get("year", 207),
+            season=data.get("season", "春"),
+            turn=data.get("turn", 1),
+            token_usage=_TU(**token_usage),
+        )
+
+    def restore_game(
+        self,
+        world_state: dict,
+        session_id: str | None = None,
+        llm_api_key: str | None = None,
+    ) -> RestoreResult:
+        """Restore a game from a previously saved world_state dict.
+
+        Args:
+            world_state: Full world_state dict (from engine.to_dict() or previous save)
+            session_id: Orchestrator session ID for persistence
+            llm_api_key: User's own DeepSeek API key
+
+        Returns:
+            RestoreResult with game_id and restored faction status
+        """
+        body: dict[str, Any] = {"world_state": world_state}
+        if session_id:
+            body["session_id"] = session_id
+        if llm_api_key:
+            body["llm_api_key"] = llm_api_key
+
+        data = self._post("/api/games/restore", body)
+        return RestoreResult(
+            game_id=data["game_id"],
+            scenario=data.get("scenario", "207"),
+            faction=data.get("faction", "?"),
+            faction_status=FactionStatus(**data.get("faction_status", {})),
+            restored=data.get("restored", False),
+            restored_turn=data.get("restored_turn", 1),
+            restored_year=data.get("restored_year", 207),
+        )
+
+    def health(self) -> dict:
+        """Check server health and LLM availability."""
+        return self._get("/api/health")

histrategy_sdk-0.1.0/src/histrategy_sdk/_engine.py

@@ -0,0 +1,270 @@
+"""DirectEngine — in-process game engine wrapper.
+
+Use this when you have histrategy-engine installed locally.
+No server needed — the game runs in your Python process.
+
+Requires: pip install histrategy-sdk[engine]
+"""
+
+from __future__ import annotations
+
+from .exceptions import EngineNotAvailableError, TurnExecutionError
+from .types import FactionStatus, GameIntro, PlanData, TurnResult
+
+
+class DirectEngine:
+    """In-process game engine for 三國志略.
+
+    Usage:
+        engine = DirectEngine(faction="shu")
+        intro = engine.get_intro()
+        plan = engine.get_plan()
+        result = engine.execute("联吴抗曹，攻打襄阳")
+        print(result["narrative"])
+
+        # Save and restore
+        data = engine.to_dict()
+        engine2 = DirectEngine.from_dict(data)
+    """
+
+    def __init__(
+        self,
+        scenario: str = "207",
+        faction: str = "shu",
+        llm_api_key: str | None = None,
+        llm_provider: str | None = None,
+    ):
+        """Create a new game engine.
+
+        Args:
+            scenario: Scenario ID ("207")
+            faction: Player faction ("shu", "cao", "wu")
+            llm_api_key: API key for LLM provider (auto-detected if unset)
+            llm_provider: Override provider detection ("deepseek", "openai", "tongyi")
+        """
+        self._ensure_engine_available()
+
+        import os as _os
+
+        if llm_api_key:
+            _os.environ["DEEPSEEK_API_KEY"] = llm_api_key
+
+        from histrategy.engine.game import GameEngine
+        from histrategy.llm.adapter import LLMAdapter
+
+        try:
+            llm = LLMAdapter(provider=llm_provider or None)
+        except Exception:
+            llm = None
+
+        self._engine = GameEngine(scenario=scenario, new_game=True, llm=llm)
+        self._engine.set_player_faction(faction)
+        self._game_id = self._engine.world_state_v2.player_faction_id if self._engine._use_v2 else "local"
+
+    @staticmethod
+    def _ensure_engine_available() -> None:
+        try:
+            import histrategy.engine.game  # noqa: F401
+        except ImportError:
+            raise EngineNotAvailableError(
+                "DirectEngine requires the full histrategy package.\n"
+                "Install with: pip install histrategy-sdk[engine]\n"
+                "Or use ServerClient for remote games."
+            ) from None
+
+    # ── Properties ────────────────────────────────────────
+
+    @property
+    def game_id(self) -> str:
+        return self._game_id
+
+    # ── Game API ──────────────────────────────────────────
+
+    def get_intro(self) -> GameIntro:
+        """Get the game intro scene.
+
+        Returns:
+            GameIntro with narrative, suggestions, faction_status.
+        """
+        from histrategy.engine.game import _suppress_stderr
+
+        with _suppress_stderr():
+            intro = self._engine.get_intro_scene()
+
+        ws = self._engine.world_state_v2
+
+        narrative = ""
+        suggestions: list[str] = []
+        if isinstance(intro, dict):
+            narrative = intro.get("narrative", "")
+            suggestions = intro.get("new_choices", [])
+        elif isinstance(intro, str):
+            narrative = intro
+
+        return GameIntro(
+            game_id=self._game_id,
+            scenario=self._engine.scenario,
+            faction=ws.player_faction_id,
+            narrative=narrative,
+            suggestions=suggestions,
+            faction_status=self._get_status_inner(),
+        )
+
+    def get_plan(self) -> PlanData:
+        """Get Plan Mode: advisor court dialogue + strategic suggestions.
+
+        Returns:
+            PlanData with court_dialogue, suggestions, faction_status.
+        """
+        from histrategy.engine.game import _suppress_stderr
+
+        with _suppress_stderr():
+            plan = self._engine.get_plan_data()
+
+        status = self._get_status_inner()
+
+        return PlanData(
+            game_id=self._game_id,
+            court_dialogue=plan.get("court_dialogue", ""),
+            suggestions=plan.get("suggestions", []),
+            season_summary=plan.get("season_summary", ""),
+            year=status.get("year", 207),
+            season=status.get("season", "春"),
+            turn=status.get("turn", 1),
+            faction_status=status,
+        )
+
+    def execute(self, decision: str) -> TurnResult:
+        """Submit a player decision and process the turn.
+
+        Args:
+            decision: Free-text player decision (e.g. "联吴抗曹，攻打襄阳")
+
+        Returns:
+            TurnResult with narrative, aftermath, state_changes, suggestions.
+        """
+        from histrategy.engine.game import _suppress_stderr
+
+        try:
+            with _suppress_stderr():
+                result = self._engine.process_turn(decision)
+        except Exception as e:
+            raise TurnExecutionError(f"Turn execution failed: {e}") from e
+
+        status = self._get_status_inner()
+
+        usage = result.get("_usage", {})
+        from .types import TokenUsage
+
+        return TurnResult(
+            game_id=self._game_id,
+            narrative=result.get("narrative", ""),
+            aftermath=result.get("aftermath", ""),
+            state_changes=result.get("state_changes", {}),
+            events_occurred=result.get("events_occurred", []),
+            npc_actions=result.get("npc_actions", result.get("npc_reactions", [])),
+            new_suggestions=result.get("new_choices", []),
+            game_over=result.get("game_over"),
+            faction_status=status,
+            year=status.get("year", 207),
+            season=status.get("season", "春"),
+            turn=status.get("turn", 1),
+            token_usage=TokenUsage(
+                command_tokens=usage.get("command_tokens", 0),
+                plan_tokens=usage.get("plan_tokens", 0),
+                npc_tokens=usage.get("npc_tokens", 0),
+                sim_tokens=usage.get("sim_tokens", 0),
+            ),
+        )
+
+    def get_status(self) -> FactionStatus:
+        """Get current faction status."""
+        return self._get_status_inner()
+
+    def to_dict(self) -> dict:
+        """Serialize the full game state to a JSON-safe dict.
+
+        Use with from_dict() to save and restore games.
+        """
+        return self._engine.to_dict()
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: dict,
+        llm_api_key: str | None = None,
+        llm_provider: str | None = None,
+    ) -> DirectEngine:
+        """Restore a game from a previously saved world_state dict.
+
+        Args:
+            data: Full world_state dict (from to_dict())
+            llm_api_key: API key for LLM provider
+            llm_provider: Override provider detection
+
+        Returns:
+            DirectEngine with restored game state.
+        """
+        cls._ensure_engine_available()
+
+        import os as _os
+
+        if llm_api_key:
+            _os.environ["DEEPSEEK_API_KEY"] = llm_api_key
+
+        from histrategy.engine.game import GameEngine
+        from histrategy.llm.adapter import LLMAdapter
+
+        try:
+            llm = LLMAdapter(provider=llm_provider or None)
+        except Exception:
+            llm = None
+
+        engine = GameEngine.from_dict(data, llm=llm)
+        instance = cls.__new__(cls)
+        instance._engine = engine
+        instance._game_id = engine.world_state_v2.player_faction_id
+        return instance
+
+    # ── Internal ──────────────────────────────────────────
+
+    def _get_status_inner(self) -> FactionStatus:
+        """Extract faction status from the engine (mirrors server api.py)."""
+        ws = self._engine.world_state_v2
+        player = ws.factions.get(ws.player_faction_id)
+        if not player:
+            return FactionStatus(
+                name="?",
+                faction_id="?",
+                strength=0,
+                food=0,
+                treasury=0,
+                territories=[],
+                territory_names=[],
+                morale=0,
+                is_active=False,
+                year=ws.year,
+                season=ws.season.cn if hasattr(ws.season, "cn") else ws.season.value,
+                turn=ws.turn_number,
+            )
+
+        # Resolve territory names
+        territory_names = []
+        for tid in player.territories:
+            t = ws.territories.get(tid)
+            territory_names.append(t.name if t else tid)
+
+        return FactionStatus(
+            name=player.name,
+            faction_id=ws.player_faction_id,
+            strength=player.strength_actual,
+            food=player.food,
+            treasury=player.treasury,
+            territories=list(player.territories),
+            territory_names=territory_names,
+            morale=player.morale_actual,
+            is_active=player.is_active,
+            year=ws.year,
+            season=ws.season.cn if hasattr(ws.season, "cn") else ws.season.value,
+            turn=ws.turn_number,
+        )

histrategy_sdk-0.1.0/src/histrategy_sdk/exceptions.py

@@ -0,0 +1,33 @@
+"""SDK-specific exceptions."""
+
+
+class HistrategyError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class GameNotFoundError(HistrategyError):
+    """The requested game was not found (expired or never created)."""
+
+
+class ConnectionError(HistrategyError):
+    """Could not connect to the histrategy server."""
+
+
+class APIError(HistrategyError):
+    """Server returned an error response."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class EngineNotAvailableError(HistrategyError):
+    """DirectEngine requires histrategy-engine to be installed.
+
+    Install with: pip install histrategy-sdk[engine]
+    """
+
+
+class TurnExecutionError(HistrategyError):
+    """Failed to process a game turn."""

histrategy_sdk-0.1.0/src/histrategy_sdk/types.py

@@ -0,0 +1,85 @@
+"""Type definitions for histrategy-sdk."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class FactionStatus(TypedDict, total=False):
+    """Current status of the player's faction."""
+
+    name: str
+    faction_id: str
+    strength: int
+    food: int
+    treasury: int
+    territories: list[str]
+    territory_names: list[str]
+    morale: int
+    is_active: bool
+    year: int
+    season: str
+    turn: int
+
+
+class GameIntro(TypedDict):
+    """Response from create_game / restore_game."""
+
+    game_id: str
+    scenario: str
+    faction: str
+    narrative: str
+    suggestions: list[str]
+    faction_status: FactionStatus
+
+
+class PlanData(TypedDict):
+    """Response from get_plan."""
+
+    game_id: str
+    court_dialogue: str
+    suggestions: list[str]
+    season_summary: str
+    year: int
+    season: str
+    turn: int
+    faction_status: FactionStatus
+
+
+class TurnResult(TypedDict):
+    """Response from execute_command."""
+
+    game_id: str
+    narrative: str
+    aftermath: str
+    state_changes: dict[str, int]
+    events_occurred: list[str]
+    npc_actions: list[str]
+    new_suggestions: list[str]
+    game_over: dict | None
+    faction_status: FactionStatus
+    year: int
+    season: str
+    turn: int
+    token_usage: TokenUsage
+
+
+class TokenUsage(TypedDict, total=False):
+    """LLM token consumption for a turn."""
+
+    command_tokens: int
+    plan_tokens: int
+    npc_tokens: int
+    sim_tokens: int
+
+
+class RestoreResult(TypedDict):
+    """Response from restore_game."""
+
+    game_id: str
+    scenario: str
+    faction: str
+    faction_status: FactionStatus
+    restored: bool
+    restored_turn: int
+    restored_year: int

histrategy_sdk-0.1.0/src/histrategy_sdk.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: histrategy-sdk
+Version: 0.1.0
+Summary: Python SDK for 三國志略 (Histrategy) — AI-powered Three Kingdoms strategy game engine
+Author: Emergence Science
+License-Expression: MIT
+Keywords: three-kingdoms,strategy-game,ai-game,llm,deepseek
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment :: Turn Based Strategy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: engine
+Requires-Dist: histrategy-engine>=0.1.0; extra == "engine"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+
+# histrategy-sdk
+
+Python SDK for [三國志略 (Histrategy)](https://emergence.science/play/histrategy) — AI-powered Three Kingdoms strategy game.
+
+```bash
+pip install histrategy-sdk
+```
+
+## Quick Start
+
+### Server Client (HTTP)
+
+```python
+from histrategy_sdk import ServerClient
+
+client = ServerClient()
+
+# Create a new game as Shu Han (刘备)
+game = client.create_game(faction="shu")
+print(game["narrative"])
+# → "建安十二年冬，刘备屯兵新野，寄居刘表麾下..."
+
+# Get strategic suggestions
+plan = client.get_plan(game["game_id"])
+for s in plan["suggestions"]:
+    print(f"  • {s}")
+
+# Execute a command
+result = client.execute_command(game["game_id"], "联吴抗曹，攻打襄阳")
+print(result["narrative"])
+print(f"Token usage: {result['token_usage']}")
+```
+
+### Direct Engine (In-Process)
+
+```bash
+pip install histrategy-sdk[engine]
+```
+
+```python
+from histrategy_sdk import DirectEngine
+
+engine = DirectEngine(faction="cao")  # Play as 曹操
+intro = engine.get_intro()
+result = engine.execute("南征刘备，先取新野")
+
+# Save game state
+save = engine.to_dict()
+
+# Restore later
+engine2 = DirectEngine.from_dict(save)
+```
+
+## API Reference
+
+### `ServerClient`
+
+| Method | Description |
+|--------|-------------|
+| `create_game(faction, scenario)` | Create new game → `GameIntro` |
+| `get_plan(game_id)` | Get advisor suggestions → `PlanData` |
+| `execute_command(game_id, decision)` | Process turn → `TurnResult` |
+| `get_status(game_id)` | Get faction resources → `FactionStatus` |
+| `restore_game(world_state)` | Restore from save → `RestoreResult` |
+| `health()` | Check server status |
+
+### `DirectEngine`
+
+| Method | Description |
+|--------|-------------|
+| `DirectEngine(faction, llm_api_key)` | Create new in-process engine |
+| `get_intro()` | Get intro scene → `GameIntro` |
+| `get_plan()` | Get suggestions → `PlanData` |
+| `execute(decision)` | Process turn → `TurnResult` |
+| `get_status()` | Get faction status → `FactionStatus` |
+| `to_dict()` | Serialize game state |
+| `DirectEngine.from_dict(data)` | Restore from saved state |
+
+### `TurnResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `narrative` | `str` | AI-generated historical chronicle |
+| `aftermath` | `str` | Resource changes summary |
+| `state_changes` | `dict` | Numerical state deltas |
+| `new_suggestions` | `list[str]` | Next-turn strategy suggestions |
+| `token_usage` | `TokenUsage` | LLM token consumption |
+| `game_over` | `dict \| None` | Victory/defeat message |
+| `faction_status` | `FactionStatus` | Current resources and territories |
+
+## License
+
+MIT — Emergence Science

histrategy_sdk-0.1.0/src/histrategy_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/histrategy_sdk/__init__.py
+src/histrategy_sdk/_client.py
+src/histrategy_sdk/_engine.py
+src/histrategy_sdk/exceptions.py
+src/histrategy_sdk/types.py
+src/histrategy_sdk.egg-info/PKG-INFO
+src/histrategy_sdk.egg-info/SOURCES.txt
+src/histrategy_sdk.egg-info/dependency_links.txt
+src/histrategy_sdk.egg-info/requires.txt
+src/histrategy_sdk.egg-info/top_level.txt

histrategy_sdk-0.1.0/src/histrategy_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

histrategy_sdk-0.1.0/src/histrategy_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx>=0.27
+
+[dev]
+pytest>=8
+pytest-cov>=5
+
+[engine]
+histrategy-engine>=0.1.0

histrategy_sdk-0.1.0/src/histrategy_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+histrategy_sdk