storyloom-engine 2.3.0__tar.gz

storyloom_engine-2.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Slev
+
+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.

storyloom_engine-2.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+graft src/storyloom/web/static
+graft src/storyloom/locale
+graft src/storyloom/content
+global-exclude *.mo

storyloom_engine-2.3.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: storyloom-engine
+Version: 2.3.0
+Summary: AI-powered real-time visual novel engine
+License: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Provides-Extra: bg
+Requires-Dist: onnxruntime>=1.18; extra == "bg"
+Requires-Dist: numpy>=1.24; extra == "bg"
+Requires-Dist: pillow>=10.0; extra == "bg"
+Provides-Extra: desktop
+Requires-Dist: pywebview>=5.0; extra == "desktop"
+Provides-Extra: test
+Requires-Dist: babel>=2.10; extra == "test"
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file

storyloom_engine-2.3.0/README.md

@@ -0,0 +1,194 @@
+<p align="center">
+  <img src="assets/icons/logo-lockup.png" alt="Storyloom logo" width="300">
+</p>
+
+# Storyloom
+
+> An AI-powered real-time visual novel engine.
+
+[![Python](https://img.shields.io/badge/python-%3E%3D10-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![Tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/SiriLee/e809f4fcaea1700560591c9867659fc0/raw/badge.json)](https://github.com/SiriLee/Storyloom/actions)
+
+<!-- TODO: screenshot or GIF demo -->
+
+---
+
+## Installation
+
+### Standalone binary
+
+*No Python required.*
+
+Download `storyloom-v{VERSION}-{platform}.zip` from
+[Releases](https://github.com/SiriLee/Storyloom/releases/latest), extract,
+and run `Storyloom`.
+
+### From PyPI
+
+*Requires Python ≥ 3.10.*
+
+```bash
+pip install storyloom-engine
+```
+
+Optional extras:
+
+```bash
+pip install "storyloom-engine[desktop,bg]"   # native window + background removal
+```
+
+| Extra | Adds |
+|-------|------|
+| `desktop` | Native desktop window via `pywebview` — falls back to browser if unavailable |
+| `bg` | Background removal for generated images (`onnxruntime`; model already bundled) |
+
+System media assets are not included in the wheel.  Download them via
+**Settings → Updates** on first launch.
+
+### From source
+
+```bash
+git clone https://github.com/SiriLee/Storyloom.git
+cd Storyloom
+pip install -e ".[desktop,bg]"
+```
+
+### Data directory & uninstall
+
+User data — `config.json`, `saves/`, `media/`, `system_media/` — lives
+outside the installed package:
+
+| Install | Data directory |
+|---------|----------------|
+| Standalone binary | Next to the `Storyloom` executable |
+| Wheel (pip) | `~/.local/share/Storyloom` (Linux), `~/Library/Application Support/Storyloom` (macOS), `%APPDATA%\Storyloom` (Windows) |
+| From source | The repository root |
+
+Override with the `STORYLOOM_APP_DIR` environment variable.
+
+`pip uninstall storyloom` removes only the package — **not** your data.
+Saves and media are kept.  To remove everything:
+
+```bash
+pip uninstall storyloom
+rm -rf ~/.local/share/Storyloom   # adjust path per the table above
+```
+
+---
+
+## Usage
+
+```bash
+storyloom-web                 # native desktop window (or browser fallback)
+storyloom-web --browser       # always open in browser
+storyloom-web --port 8080     # custom port (default: auto-assign)
+storyloom-web --help          # show all options
+
+# or
+python -m storyloom.web
+```
+
+First launch opens the Settings page.  Enter your API key, select a mode
+(**Text** or **Graph**), and start a new game.
+
+> **System media assets** (~267 MB of character portraits and background
+> images) are included in the standalone release zip alongside the binary.
+> Wheel and source users can download them via **Settings → Updates**
+> inside the app.
+
+---
+
+## Features
+
+| | |
+|---|---|
+| Streaming XML pipeline | `StreamParser → StateManager → EventDispatcher` — parsed line-by-line, no buffering |
+| Bridge pre-fetch | Next API call fires mid-paragraph; latency hidden behind reading time |
+| State validation | LLM *suggests* writes; engine type-checks before applying; rejected writes feed back |
+| Two-layer branching | In-scene choices + outline-level route forks at checkpoints |
+| Asset pipeline | O(1) catalog match → LLM fallback → AI generation; async, non-blocking |
+| Context management | Sliding window + Round 1 anchor + checkpoint compression; ~50K tokens |
+| Co-creation | AI interviews you about your idea before generating world, characters, and plot |
+| Save / load | Atomic JSON saves; mode-agnostic — switch text/graph any time |
+| i18n | English, 简体中文, 繁體中文 (gettext) |
+| Web UI | FastAPI + SSE + vanilla JS SPA |
+| CLI | Terminal client with debug observer |
+| Packaging | Standalone binary (PyInstaller) + pip wheel + system asset pack |
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    LLM[Director LLM]
+    Parser[Stream Parser]
+    State[State Manager]
+    Tasks[Task Generator + Pool]
+    Dispatcher[Event Dispatcher]
+    UI[UI]
+
+    LLM -- "token stream" --> Parser
+    Parser -- "event" --> State
+    Parser -. "asset trigger" .-> Tasks
+
+    State -- "processed event" --> Dispatcher
+    Tasks -- "completed task" --> Dispatcher
+
+    Dispatcher -- "bound event" --> UI
+    UI -. "choice" .-> State
+
+    State -. "pre-fetch" .-> LLM
+```
+
+Solid lines are streaming data flow.  Dotted lines are one-shot triggers.
+Graph-mode asset tags spawn tasks that resolve asynchronously, without
+blocking the text pipeline.
+
+---
+
+## Documentation
+
+| | |
+|---|---|
+| Theory | [First principles](docs/theory/first-principles.md) · [Bridge mechanism](docs/theory/bridge-mechanism.md) · [Streaming parse](docs/theory/streaming-parse.md) · [Asset generation](docs/theory/asset-generation.md) |
+| Spec | [Phase 1 pipeline](docs/spec/exec-flow.md) · [XML elements](docs/spec/block-spec.md) · [Prompts](docs/spec/prompt-design.md) · [Data model](docs/spec/data-model.md) |
+| Graph mode | [Design](docs/graph-mode-spec/design.md) |
+| API | [GameSession](docs/api/session.md) · [Co-create](docs/api/co-create.md) |
+| Log | [Engineering journal](docs/engineering-journal.md) |
+
+---
+
+## Development
+
+```bash
+# Clone and install (the `test` extra adds pytest + babel for the test suite)
+git clone https://github.com/SiriLee/Storyloom.git
+cd Storyloom
+pip install -e ".[desktop,bg,test]"
+
+# Tests (no API key needed)
+pytest
+
+# Build
+bash scripts/build.sh                # standalone binary + wheel
+bash scripts/pack_system_media.sh    # system asset pack for release
+
+# Generate system assets from source definitions (requires image API key)
+python scripts/sysgen/generate_system_assets.py
+python scripts/sysgen/generate_manifest.py
+```
+
+**Conventions:** Python ≥ 3.10 · stdlib-first · Conventional Commits ·
+English code & docs · mock tests (no real API calls).
+
+**AI context:** [`AGENTS.md`](AGENTS.md) is the single source of truth for
+coding-agent context (Claude Code, Cursor, Windsurf, Copilot, Gemini CLI, …).
+[`CLAUDE.md`](CLAUDE.md) and
+[`.github/copilot-instructions.md`](.github/copilot-instructions.md) are thin
+compatibility bridges — keep shared knowledge in `AGENTS.md` only.
+
+---
+
+[MIT](./LICENSE)

storyloom_engine-2.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=64", "babel>=2.10"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "storyloom-engine"
+version = "2.3.0"
+description = "AI-powered real-time visual novel engine"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.28.0",
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+]
+
+[project.optional-dependencies]
+bg = ["onnxruntime>=1.18", "numpy>=1.24", "pillow>=10.0"]
+desktop = ["pywebview>=5.0"]
+test = ["babel>=2.10", "pytest>=7.0"]
+
+[project.scripts]
+storyloom-web = "storyloom.web.server:main"
+
+[tool.setuptools.package-data]
+storyloom = ["web/static/**/*", "core/lang_meta/*.json", "models/*.onnx", "locale/**/*", "content/**/*"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "--ignore=tests/prompt_lab"

storyloom_engine-2.3.0/setup.cfg

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

storyloom_engine-2.3.0/setup.py

@@ -0,0 +1,139 @@
+"""Build hook — compile .po → .mo + download ONNX model during ``pip install``.
+
+Users never need ``msgfmt`` or any manual step.  Everything happens
+automatically inside the build phase.
+"""
+
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py as _build_py
+from setuptools.command.develop import develop as _develop
+from setuptools.command.editable_wheel import editable_wheel as _editable_wheel
+
+
+def _compile_mo_files() -> None:
+    """Compile all .po files under ``src/storyloom/locale/`` to .mo (Babel).
+
+    Frontend translations are a separate source (i18next JSON under
+    ``web/static/locales/``) and are not derived here.
+    """
+    project_root = Path(__file__).resolve().parent
+    src = project_root / "src"
+
+    # Load i18n_compile directly (avoids storyloom.__init__ → httpx import
+    # chain, which fails in isolated build environments like editable_wheel).
+    import importlib.util
+    spec = importlib.util.spec_from_file_location(
+        "storyloom.i18n_compile",
+        str(src / "storyloom" / "i18n_compile.py"),
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    compile_all = mod.compile_all
+
+    locale_dir = project_root / "src" / "storyloom" / "locale"
+    compiled = compile_all(str(locale_dir))
+    if compiled:
+        print(f"[i18n] compiled {len(compiled)} .mo file(s)")
+
+
+def _download_model() -> None:
+    """Download u2netp.onnx (~4.4 MB) into ``src/storyloom/models/``.
+
+    Idempotent — skips if already cached with the correct SHA256.
+    Network failures are warned, not fatal (the install continues).
+    """
+    import hashlib
+    import importlib.util
+    import urllib.request
+
+    project_root = Path(__file__).resolve().parent
+
+    # Load config.py standalone to read filename+SHA256 (avoids storyloom
+    # __init__ import chain, same pattern as _compile_mo_files above).
+    spec = importlib.util.spec_from_file_location(
+        "storyloom.config",
+        str(project_root / "src" / "storyloom" / "config.py"),
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    sha256 = mod.BG_REMOVAL_MODEL_SHA256
+    filename = mod.BG_REMOVAL_MODEL_FILENAME
+
+    # URL is build-time only; kept here, not in production config.
+    url = (
+        "https://github.com/danielgatis/rembg/releases/download/"
+        "v0.0.0/u2netp.onnx"
+    )
+
+    target = project_root / "src" / "storyloom" / "models" / filename
+
+    # --- skip if already cached ---
+    if target.exists():
+        h = hashlib.sha256()
+        with open(target, "rb") as f:
+            for chunk in iter(lambda: f.read(65536), b""):
+                h.update(chunk)
+        if h.hexdigest() == sha256:
+            print(f"[model] {filename} cached (SHA256 ok)")
+            return
+        print(f"[model] {filename} exists but SHA256 mismatch — re-downloading")
+
+    # --- download ---
+    target.parent.mkdir(parents=True, exist_ok=True)
+    print(f"[model] downloading {filename} (4.4 MB)...")
+    try:
+        urllib.request.urlretrieve(url, target)
+    except Exception as e:
+        print(f"[model] WARNING: download failed ({e})")
+        print(f"[model] run `pip install -e .` again or place {filename} manually")
+        return
+
+    # --- verify ---
+    h = hashlib.sha256()
+    with open(target, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    if h.hexdigest() != sha256:
+        target.unlink()
+        print(f"[model] WARNING: SHA256 mismatch — corrupt download removed")
+        print(f"[model] run `pip install -e .` again to retry")
+        return
+
+    print(f"[model] downloaded {target}")
+
+
+class build_py(_build_py):
+    """Custom build_py — compiles gettext catalogs + frontend JS dict
+    + downloads the background-removal model."""
+
+    def run(self) -> None:
+        _compile_mo_files()
+        _download_model()
+        super().run()
+
+
+class develop(_develop):
+    """Custom develop — same hook for editable installs (legacy path)."""
+
+    def run(self) -> None:
+        _compile_mo_files()
+        _download_model()
+        super().run()
+
+
+class editable_wheel(_editable_wheel):
+    """Custom editable_wheel — PEP 660 editable installs (pip install -e)."""
+
+    def run(self) -> None:
+        _compile_mo_files()
+        _download_model()
+        super().run()
+
+
+setup(cmdclass={
+    "build_py": build_py,
+    "develop": develop,
+    "editable_wheel": editable_wheel,
+})

storyloom_engine-2.3.0/src/storyloom/__init__.py

@@ -0,0 +1,46 @@
+"""Storyloom — AI-powered real-time visual novel engine."""
+
+__version__ = "2.3.0"
+
+from storyloom.io.api_client import ApiClient, ApiError, ApiResult
+from storyloom.config import WINDOW_SIZE, DEFAULT_MODEL
+from storyloom.core.context_manager import ContextManager
+from storyloom.core.game_loop import GameLoop, GameState, RoundResult, RoundRecord
+from storyloom.core.prompt_builder import PromptBuilder
+from storyloom.core.save_manager import SaveManager
+from storyloom.core.session import GameSession
+from storyloom.user_config import UserConfig
+
+from storyloom.assets import Asset, AssetItem, AssetLibrary, AssetType, GameAssetRoster
+from storyloom.parser import ParsedOutput, ParseError, Segment
+from storyloom.tasks import Task, TaskGenerator, TaskPool, TaskType
+
+__all__ = [
+    "ApiClient",
+    "ApiError",
+    "ApiResult",
+    "Asset",
+    "AssetItem",
+    "AssetLibrary",
+    "AssetType",
+    "ContextManager",
+    "DEFAULT_MODEL",
+    "GameAssetRoster",
+    "GameLoop",
+    "GameSession",
+    "GameState",
+    "ParsedOutput",
+    "ParseError",
+    "PromptBuilder",
+    "RoundRecord",
+    "RoundResult",
+    "SaveManager",
+    "Segment",
+    "Task",
+    "TaskGenerator",
+    "TaskPool",
+    "TaskType",
+    "UserConfig",
+
+    "WINDOW_SIZE",
+]

storyloom_engine-2.3.0/src/storyloom/assets/__init__.py

@@ -0,0 +1,19 @@
+"""Asset database layer — types, library, roster.
+
+Per design.md §2: Three-layer abstraction:
+  AssetType / Asset / AssetItem — core data types
+  AssetLibrary — global asset registry (media/_asset_lib.json)
+  GameAssetRoster — per-game asset mapping (saves/{id}/_asset_roster.json)
+"""
+
+from storyloom.assets._library import AssetLibrary
+from storyloom.assets._roster import GameAssetRoster
+from storyloom.assets._types import Asset, AssetItem, AssetType
+
+__all__ = [
+    "Asset",
+    "AssetItem",
+    "AssetLibrary",
+    "AssetType",
+    "GameAssetRoster",
+]