esimu-core 0.2.0b5__tar.gz

esimu_core-0.2.0b5/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 pirate-608
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

esimu_core-0.2.0b5/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: esimu-core
+Version: 0.2.0b5
+Summary: Theme-driven core and project tooling for the esimu simulator framework.
+Author: pirate-608
+License-Expression: MIT
+Project-URL: Homepage, https://esimu.67656.fun/
+Project-URL: Documentation, https://esimu.67656.fun/
+Project-URL: Repository, https://github.com/pirate-608/esimu
+Project-URL: Issues, https://github.com/pirate-608/esimu/issues
+Keywords: simulation,game,framework,theme-pack
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Provides-Extra: ai
+Requires-Dist: openai>=1.12; extra == "ai"
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == "dev"
+Requires-Dist: fastapi>=0.115; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff==0.16.2; extra == "dev"
+Dynamic: license-file
+
+# esimu-core
+
+`esimu-core` is the typed, I/O-independent core and project CLI for esimu.
+
+```powershell
+python -m pip install "esimu-core[ai]==0.2.0b5"
+esimu version
+esimu new D:\projects\my-simulator --theme-id my-simulator
+esimu validate --root D:\projects\my-simulator --theme my-simulator
+```
+
+The base dependency is Pydantic. The optional `ai` extra adds the OpenAI SDK
+transport. FastAPI, SQLite, WebSocket, and Vue live in the generated Starter,
+not in the core package.
+
+Core owns:
+
+- theme and world-data contracts;
+- stat, item, effect, semester, and lifecycle rules;
+- runtime timing, state, payload, cooldown, and task helpers;
+- neutral event, forum, and messenger content contracts;
+- optional AI configuration, parsing, generation, and fallback policy;
+- the self-contained `esimu new` scaffold bundle.
+
+See `https://esimu.67656.fun/` for the authoring and compatibility guides.

esimu_core-0.2.0b5/README.md

@@ -0,0 +1,25 @@
+# esimu-core
+
+`esimu-core` is the typed, I/O-independent core and project CLI for esimu.
+
+```powershell
+python -m pip install "esimu-core[ai]==0.2.0b5"
+esimu version
+esimu new D:\projects\my-simulator --theme-id my-simulator
+esimu validate --root D:\projects\my-simulator --theme my-simulator
+```
+
+The base dependency is Pydantic. The optional `ai` extra adds the OpenAI SDK
+transport. FastAPI, SQLite, WebSocket, and Vue live in the generated Starter,
+not in the core package.
+
+Core owns:
+
+- theme and world-data contracts;
+- stat, item, effect, semester, and lifecycle rules;
+- runtime timing, state, payload, cooldown, and task helpers;
+- neutral event, forum, and messenger content contracts;
+- optional AI configuration, parsing, generation, and fallback policy;
+- the self-contained `esimu new` scaffold bundle.
+
+See `https://esimu.67656.fun/` for the authoring and compatibility guides.

esimu_core-0.2.0b5/esimu_core/__init__.py

@@ -0,0 +1,17 @@
+"""Simulator framework backend core package.
+
+Copyright (c) 2026 pirate-608. Licensed under the MIT License.
+"""
+
+__version__ = "0.2.0b5"
+
+THEME_SCHEMA_VERSION = 1
+STATE_VERSION = 1
+PROTOCOL_VERSION = 1
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "STATE_VERSION",
+    "THEME_SCHEMA_VERSION",
+    "__version__",
+]

esimu_core-0.2.0b5/esimu_core/ai/__init__.py

@@ -0,0 +1,31 @@
+"""Optional AI integration for esimu simulator adapters.
+
+The package is safe to import without the OpenAI SDK. Constructing
+``OpenAICompatibleTransport`` requires the ``esimu-core[ai]`` extra.
+"""
+
+from esimu_core.ai.config import (
+    AIModelConfig,
+    generic_model_config_from_env,
+    roleplay_model_config_from_env,
+)
+from esimu_core.ai.policy import ContentMode, ResolvedContent, resolve_content
+from esimu_core.ai.service import AIContentService
+from esimu_core.ai.transport import (
+    ChatTransport,
+    OpenAICompatibleTransport,
+    OpenAITransportRegistry,
+)
+
+__all__ = [
+    "AIContentService",
+    "AIModelConfig",
+    "ChatTransport",
+    "ContentMode",
+    "OpenAICompatibleTransport",
+    "OpenAITransportRegistry",
+    "ResolvedContent",
+    "generic_model_config_from_env",
+    "resolve_content",
+    "roleplay_model_config_from_env",
+]

esimu_core-0.2.0b5/esimu_core/ai/config.py

@@ -0,0 +1,114 @@
+"""Model configuration for the optional esimu AI integration.
+
+Copyright (c) 2026 pirate-608. Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal, Mapping
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+PROVIDER_BASE_URLS: dict[str, str] = {
+    "openai": "https://api.openai.com/v1",
+    "deepseek": "https://api.deepseek.com",
+    "qwen": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "glm": "https://open.bigmodel.cn/api/paas/v4",
+    "moonshot": "https://api.moonshot.cn/v1",
+    "minimax": "https://api.minimaxi.com/v1",
+    "ollama": "http://127.0.0.1:11434/v1",
+}
+
+RoleProfile = Literal["generic", "minimax_m2her"]
+
+
+class AIModelConfig(BaseModel):
+    """One OpenAI-compatible model endpoint without application persistence."""
+
+    provider: str = "openai"
+    model: str = "gpt-4o-mini"
+    api_key: str | None = Field(default=None, repr=False)
+    base_url: str | None = None
+    timeout_seconds: float = Field(default=20.0, gt=0, le=300)
+    role_profile: RoleProfile = "generic"
+
+    @field_validator("provider", "model")
+    @classmethod
+    def strip_required_text(cls, value: str) -> str:
+        """Normalize required model identifiers."""
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("model provider/name cannot be empty")
+        return normalized
+
+    @field_validator("base_url")
+    @classmethod
+    def normalize_base_url(cls, value: str | None) -> str | None:
+        """Accept both SDK base URLs and older full completion endpoints."""
+        if value is None:
+            return None
+        normalized = value.strip().rstrip("/")
+        for suffix in ("/chat/completions", "/text/chatcompletion_v2"):
+            if normalized.endswith(suffix):
+                normalized = normalized[: -len(suffix)].rstrip("/")
+        return normalized or None
+
+    @model_validator(mode="after")
+    def fill_provider_url(self) -> "AIModelConfig":
+        """Use a known provider URL when the caller omitted an override."""
+        if self.base_url is None:
+            self.base_url = PROVIDER_BASE_URLS.get(self.provider.lower())
+        return self
+
+    @property
+    def is_configured(self) -> bool:
+        """Return whether the endpoint has enough information to be attempted."""
+        return bool(self.api_key or self.provider.lower() == "ollama")
+
+    @classmethod
+    def from_env(
+        cls,
+        prefix: str = "ESIMU_LLM",
+        *,
+        environ: Mapping[str, str] | None = None,
+        default_provider: str = "openai",
+        default_model: str = "gpt-4o-mini",
+        role_profile: RoleProfile = "generic",
+    ) -> "AIModelConfig":
+        """Load a model endpoint from a namespaced environment mapping."""
+        values = os.environ if environ is None else environ
+        provider = values.get(f"{prefix}_PROVIDER", default_provider)
+        timeout_raw = values.get(f"{prefix}_TIMEOUT_SECONDS", "20")
+        try:
+            timeout = float(timeout_raw)
+        except ValueError:
+            timeout = 20.0
+        return cls(
+            provider=provider,
+            model=values.get(f"{prefix}_MODEL", default_model),
+            api_key=values.get(f"{prefix}_API_KEY") or None,
+            base_url=values.get(f"{prefix}_BASE_URL") or None,
+            timeout_seconds=timeout,
+            role_profile=role_profile,
+        )
+
+
+def generic_model_config_from_env(
+    environ: Mapping[str, str] | None = None,
+) -> AIModelConfig:
+    """Load the framework's general content model configuration."""
+    return AIModelConfig.from_env("ESIMU_LLM", environ=environ)
+
+
+def roleplay_model_config_from_env(
+    environ: Mapping[str, str] | None = None,
+) -> AIModelConfig:
+    """Load the optional MiniMax M2-her role-play model configuration."""
+    return AIModelConfig.from_env(
+        "ESIMU_RP",
+        environ=environ,
+        default_provider="minimax",
+        default_model="M2-her",
+        role_profile="minimax_m2her",
+    )

esimu_core-0.2.0b5/esimu_core/ai/parsing.py

@@ -0,0 +1,45 @@
+"""Defensive parsing helpers for model-generated content."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def json_object_from_text(content: object) -> dict[str, Any]:
+    """Extract one JSON object from plain text or a fenced response."""
+    if not isinstance(content, str) or not content.strip():
+        return {}
+    text = content.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        if lines:
+            lines = lines[1:]
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    start = text.find("{")
+    end = text.rfind("}")
+    if start >= 0 and end >= start:
+        text = text[start : end + 1]
+    try:
+        value = json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def string_list(value: object, *, limit: int | None = None) -> list[str]:
+    """Return non-empty strings from an untrusted model value."""
+    if not isinstance(value, list):
+        return []
+    result = [item.strip() for item in value if isinstance(item, str) and item.strip()]
+    return result[:limit] if limit is not None else result
+
+
+def dict_list(value: object, *, limit: int | None = None) -> list[dict[str, Any]]:
+    """Return dictionary entries from an untrusted model value."""
+    if not isinstance(value, list):
+        return []
+    result = [item for item in value if isinstance(item, dict)]
+    return result[:limit] if limit is not None else result

esimu_core-0.2.0b5/esimu_core/ai/policy.py

@@ -0,0 +1,80 @@
+"""Content-mode fallback policy shared by simulator adapters."""
+
+from __future__ import annotations
+
+import inspect
+import random
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Generic, Literal, TypeVar
+
+ContentMode = Literal["library", "hybrid", "ai"]
+ContentSource = Literal["library", "ai", "fallback"]
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class ResolvedContent(Generic[T]):
+    """One resolved content value plus degradation metadata."""
+
+    value: T | None
+    source: ContentSource
+    degraded: bool = False
+    error: str | None = None
+
+
+async def _call(factory: Callable[[], T | Awaitable[T] | None]) -> T | None:
+    value = factory()
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+async def resolve_content(
+    mode: ContentMode,
+    *,
+    ai_factory: Callable[[], T | Awaitable[T] | None] | None,
+    library_factory: Callable[[], T | Awaitable[T] | None],
+    hybrid_ai_probability: float = 0.35,
+    random_value: Callable[[], float] = random.random,
+) -> ResolvedContent[T]:
+    """Resolve AI/library content with deterministic degradation semantics.
+
+    Library mode never calls a model. AI mode tries the model first and falls
+    back locally. Hybrid mode chooses AI with the configured probability and
+    otherwise prefers the library, still using the other source if needed.
+    """
+    if mode not in {"library", "hybrid", "ai"}:
+        raise ValueError(f"unsupported content mode: {mode}")
+    probability = max(0.0, min(1.0, hybrid_ai_probability))
+    ai_first = mode == "ai" or (
+        mode == "hybrid" and ai_factory is not None and random_value() < probability
+    )
+    if mode == "library" or ai_factory is None:
+        return ResolvedContent(await _call(library_factory), "library")
+
+    first_name: ContentSource = "ai" if ai_first else "library"
+    second_name: ContentSource = "library" if ai_first else "ai"
+    first = ai_factory if ai_first else library_factory
+    second = library_factory if ai_first else ai_factory
+    first_error: str | None = None
+    try:
+        value = await _call(first)
+        if value is not None:
+            return ResolvedContent(value, first_name)
+    except Exception as exc:  # adapters decide how to log/display degradation
+        first_error = str(exc)
+    try:
+        value = await _call(second)
+        return ResolvedContent(
+            value,
+            second_name if value is not None else "fallback",
+            degraded=first_name == "ai",
+            error=first_error,
+        )
+    except Exception as exc:
+        return ResolvedContent(
+            None,
+            "fallback",
+            degraded=first_name == "ai",
+            error=first_error or str(exc),
+        )