Deploy ZeroGPU Space snapshot

.gitignore

@@ -0,0 +1,237 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Telltale local artifacts
+/models/
+runs/
+.modal/
+
+docs/
+node_modules/
+*.tsbuildinfo
+!telltale/web/dist/
+!telltale/web/dist/**
+telltale/web/dist/dream.mp3
+
+.venv/
+__pycache__/
+.pytest_cache/
+*.py[cod]

LICENSE

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

README.md

@@ -0,0 +1,123 @@
+---
+title: Telltale
+sdk: gradio
+app_file: app.py
+python_version: "3.10"
+colorFrom: indigo
+colorTo: gray
+short_description: AI poker roguelike with table talk.
+models:
+  - nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16
+  - nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF
+tags:
+  - gradio
+  - zerogpu
+  - build-small
+  - thousand-token-wood
+  - off-brand
+  - best-agent
+  - tiny-titan
+  - nvidia-nemotron
+  - codex
+---
+
+# Telltale
+
+Telltale is a single-player Texas Hold'em roguelike about pressure, memory, and table talk. You climb five casino floors against fixed AI opponents who speak in character, remember the run, and make legal poker decisions from a solver-informed local model prompt.
+
+## Hackathon Fit
+
+- Track: Thousand Token Wood.
+- Deadline Space runtime: ZeroGPU with `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16`, because the hackathon org currently cannot upgrade paid GPU hardware.
+- Full standard-GPU runtime: actual `llama.cpp` through `llama-server`, not `llama-cpp-python`.
+- ZeroGPU model: `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16`, under the 32B cap, Tiny Titan-friendly, and NVIDIA sponsor-aligned.
+- Standard-GPU model target: `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF`, under the 32B cap and eligible for the Nemotron sponsor path.
+- Gradio: `app.py` exposes a `gr.Server` app with a custom React frontend instead of a stock Blocks UI.
+- Target badges/prizes: Off Brand, Best Agent, Tiny Titan, Best Demo, Nemotron Hardware Prize, and Best Use of Codex.
+
+## Local Development
+
+```bash
+uv sync
+uv run pytest
+cd telltale/web
+npm ci
+npm run build
+```
+
+Text-only mock mode is useful for fast local tests:
+
+```bash
+TELLTALE_MODEL_MODE=mock uv run python app.py
+```
+
+## Actual llama.cpp Runtime
+
+Run a local `llama-server` first:
+
+```bash
+llama-server \
+  --host 127.0.0.1 \
+  --port 8080 \
+  --hf-repo nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M \
+  --hf-file NVIDIA-Nemotron3-Nano-4B-Q4_K_M.gguf \
+  --alias telltale-agent \
+  --ctx-size 4096 \
+  --n-gpu-layers 999
+```
+
+Then launch Telltale:
+
+```bash
+TELLTALE_MODEL_MODE=llama_server \
+TELLTALE_LLAMA_SERVER_URL=http://127.0.0.1:8080 \
+uv run python app.py
+```
+
+The older `llama_cpp` mode string is accepted as a compatibility alias, but the runtime is now `llama_server`.
+
+## Hugging Face Space
+
+Create the Space under the `build-small-hackathon` organization with:
+
+- SDK: Gradio
+- Hardware: ZeroGPU
+- Visibility: Public
+
+The frontend build is committed under `telltale/web/dist` because Gradio Spaces do not run the Vite build automatically.
+
+On Hugging Face, the default runtime becomes `TELLTALE_MODEL_MODE=zero_gpu` automatically when `SPACE_ID` is present. If the model path has trouble close to submission, add this Space variable to force the emergency text-only demo:
+
+```text
+TELLTALE_MODEL_MODE=mock
+```
+
+When standard GPU hardware is available, switch to:
+
+```text
+TELLTALE_MODEL_MODE=llama_server
+```
+
+and run the actual `llama-server` setup described above.
+
+## Voice
+
+Voice is progressive enhancement. Text gameplay remains fully playable.
+
+- TTS target: OpenBMB VoxCPM2 for sponsor-aligned creative character voices, with a fallback to a lightweight local TTS if needed.
+- STT target: Cohere Transcribe or Nemotron 3 ASR for sponsor-aligned speech input.
+- Current API surface includes transcription and cached audio endpoints so the concrete model can be swapped without changing gameplay.
+
+## Traces
+
+Every model-driven agent decision records prompt, model output, solver recommendation, repairs, memory changes, and runtime metadata. Use the trace export button in the UI or call:
+
+```bash
+curl http://127.0.0.1:7860/api/trace/<run_id>
+```
+
+## Known Limitations
+
+- TTS/STT model implementations are intentionally behind wrappers so the final sponsor model can be selected without touching game state.
+- ZeroGPU mode is the deadline-compatible org deployment path; actual `llama.cpp` mode requires standard GPU hardware.
+- Demo video and social-post links must be added before final submission.

app.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import gradio as gr
+import uvicorn
+from fastapi import HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import FileResponse, JSONResponse, Response
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from telltale.server import api
+
+
+WEB_DIR = Path(__file__).parent / "telltale" / "web"
+DIST_DIR = WEB_DIR / "dist"
+ASSETS_DIR = DIST_DIR / "assets"
+SOURCE_INDEX = WEB_DIR / "index.html"
+ErrorCode = Literal["bad_request", "not_found", "illegal_action", "server_error"]
+
+
+class ErrorPayload(BaseModel):
+    code: ErrorCode
+    message: str
+
+
+class StartRequest(BaseModel):
+    seed: int | None = None
+    model_mode: Literal["mock", "zero_gpu", "llama_server", "llama_cpp"] | None = None
+    tts_enabled: bool = False
+    stt_enabled: bool = False
+
+
+class ActionRequest(BaseModel):
+    run_id: str = Field(min_length=1)
+    action: Literal["fold", "check", "call", "bet", "raise", "all_in"]
+    amount: int = Field(default=0, ge=0)
+    utterance: str = ""
+
+
+class RewardRequest(BaseModel):
+    run_id: str = Field(min_length=1)
+    perk_id: str = Field(min_length=1)
+
+
+class ContinueRequest(BaseModel):
+    run_id: str = Field(min_length=1)
+
+
+def create_gradio_app() -> gr.Blocks:
+    with gr.Blocks(title="Telltale API", fill_height=True) as demo:
+        gr.Markdown(
+            """
+            # Telltale backend
+
+            The player-facing game UI is served at `/`. This hidden Gradio mount exists for
+            Hugging Face/Gradio compatibility and lightweight backend inspection.
+            """
+        )
+        start = gr.Button("Start llama.cpp backend run", variant="primary")
+        state_json = gr.JSON(label="Public state")
+
+        def on_start() -> dict[str, Any]:
+            return api.start_run()
+
+        start.click(on_start, inputs=[], outputs=state_json)
+
+    return demo
+
+
+def create_app() -> gr.Server:
+    app = gr.Server(title="Telltale", docs_url="/api/docs", redoc_url=None)
+    app.add_exception_handler(HTTPException, _http_exception_handler)
+    app.add_exception_handler(RequestValidationError, _validation_exception_handler)
+    app.add_exception_handler(Exception, _unhandled_exception_handler)
+
+    @app.post("/api/start")
+    def start_run(request: StartRequest):
+        settings: dict[str, Any] = {
+            "tts_enabled": request.tts_enabled,
+            "stt_enabled": request.stt_enabled,
+        }
+        if request.model_mode is not None:
+            settings["model_mode"] = request.model_mode
+        return _api_call(
+            lambda: api.start_run(
+                seed=request.seed,
+                settings=settings,
+            )
+        )
+
+    @app.get("/api/floors")
+    def list_floors():
+        return _api_call(api.list_floors)
+
+    @app.get("/api/state/{run_id}")
+    def get_state(run_id: str):
+        return _api_call(lambda: api.get_state(run_id))
+
+    @app.post("/api/action")
+    def submit_action(request: ActionRequest):
+        return _api_call(
+            lambda: api.submit_player_action(
+                request.run_id,
+                request.action,
+                amount=request.amount,
+                utterance=request.utterance,
+            )
+        )
+
+    @app.post("/api/reward")
+    def choose_reward(request: RewardRequest):
+        return _api_call(lambda: api.choose_reward(request.run_id, request.perk_id))
+
+    @app.post("/api/continue")
+    def continue_run(request: ContinueRequest):
+        return _api_call(lambda: api.continue_until_player_turn(request.run_id))
+
+    @app.get("/api/trace/{run_id}")
+    def export_trace(run_id: str):
+        return _api_call(lambda: api.export_trace(run_id))
+
+    @app.post("/api/transcribe/{run_id}")
+    async def transcribe_audio(run_id: str, request: Request):
+        audio = await request.body()
+        return _api_call(lambda: api.transcribe_player_audio(run_id, audio))
+
+    @app.get("/api/audio/{audio_id}")
+    def get_audio(audio_id: str):
+        result = _api_call(lambda: api.get_tts_audio(audio_id))
+        if isinstance(result, JSONResponse):
+            return result
+        return FileResponse(result["path"], media_type=result["mime_type"])
+
+    if ASSETS_DIR.exists():
+        app.mount("/assets", StaticFiles(directory=ASSETS_DIR), name="assets")
+    public_assets = WEB_DIR / "public" / "assets"
+    if public_assets.exists():
+        app.mount("/game-assets", StaticFiles(directory=public_assets), name="game-assets")
+
+    @app.get("/")
+    def index() -> Response:
+        index_path = DIST_DIR / "index.html"
+        if index_path.exists():
+            return FileResponse(index_path)
+        if SOURCE_INDEX.exists():
+            return FileResponse(SOURCE_INDEX)
+        return JSONResponse({"message": "Build the React frontend with `cd telltale/web && npm run build`."})
+
+    gr.mount_gradio_app(app, create_gradio_app(), path="/gradio", footer_links=[])
+
+    @app.get("/{path:path}")
+    def spa_fallback(path: str) -> Response:
+        if path.startswith(("api/", "gradio/")):
+            raise HTTPException(status_code=404, detail=f"Unknown path: /{path}")
+        static_path = DIST_DIR / path
+        if static_path.is_file():
+            return FileResponse(static_path)
+        public_path = WEB_DIR / "public" / path
+        if public_path.is_file():
+            return FileResponse(public_path)
+        index_path = DIST_DIR / "index.html"
+        if index_path.exists():
+            return FileResponse(index_path)
+        raise HTTPException(status_code=404, detail="React frontend has not been built.")
+
+    return app
+
+
+def _error(code: ErrorCode, message: str, status_code: int) -> JSONResponse:
+    return JSONResponse(
+        status_code=status_code,
+        content={"error": ErrorPayload(code=code, message=message).model_dump()},
+    )
+
+
+def _api_call(callback: Any) -> dict[str, Any] | JSONResponse:
+    try:
+        return callback()
+    except KeyError as error:
+        return _error("not_found", _clean_message(error), 404)
+    except ValueError as error:
+        message = _clean_message(error)
+        code: ErrorCode = "illegal_action" if "not legal" in message else "bad_request"
+        return _error(code, message, 400)
+    except Exception as error:
+        return _error("server_error", _clean_message(error), 500)
+
+
+async def _http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    code: ErrorCode = "not_found" if exc.status_code == 404 else "bad_request"
+    return _error(code, str(exc.detail), exc.status_code)
+
+
+async def _validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    return _error("bad_request", "Request validation failed.", 422)
+
+
+async def _unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    if isinstance(exc, KeyError):
+        return _error("not_found", _clean_message(exc), 404)
+    if isinstance(exc, ValueError):
+        message = _clean_message(exc)
+        code: ErrorCode = "illegal_action" if "not legal" in message else "bad_request"
+        return _error(code, message, 400)
+    return _error("server_error", _clean_message(exc), 500)
+
+
+def _clean_message(error: Exception) -> str:
+    text = str(error)
+    if len(text) >= 2 and text[0] == text[-1] == "'":
+        return text[1:-1]
+    return text or error.__class__.__name__
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    uvicorn.run("app:app", host="0.0.0.0", port=7860, reload=False)

configs/model_candidates.comparison.json

@@ -0,0 +1,28 @@
+{
+  "candidates": [
+    {
+      "label": "nemotron_3_nano_4b_q4_k_m",
+      "hf_repo_id": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
+      "gguf_filename": "NVIDIA-Nemotron3-Nano-4B-Q4_K_M.gguf",
+      "quantization": "Q4_K_M"
+    },
+    {
+      "label": "qwen3_4b_q4_k_m",
+      "hf_repo_id": "Qwen/Qwen3-4B-GGUF",
+      "gguf_filename": "Qwen3-4B-Q4_K_M.gguf",
+      "quantization": "Q4_K_M"
+    },
+    {
+      "label": "minicpm41_8b_q4_k_m",
+      "hf_repo_id": "openbmb/MiniCPM4.1-8B-GGUF",
+      "gguf_filename": "MiniCPM4.1-8B-Q4_K_M.gguf",
+      "quantization": "Q4_K_M"
+    },
+    {
+      "label": "qwen3_8b_q4_k_m",
+      "hf_repo_id": "Qwen/Qwen3-8B-GGUF",
+      "gguf_filename": "Qwen3-8B-Q4_K_M.gguf",
+      "quantization": "Q4_K_M"
+    }
+  ]
+}

pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "telltale"
+version = "0.1.0"
+description = "A fun poker game"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi",
+    "gradio", 
+    "numpy",
+    "pydantic",
+    "uvicorn",
+]
+
+[dependency-groups]
+dev = [
+    "pytest",
+]
+
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["telltale*"]
+
+[tool.setuptools]
+py-modules = ["app"]

requirements.txt

@@ -0,0 +1,11 @@
+fastapi
+gradio
+numpy
+pydantic
+uvicorn
+spaces
+torch
+transformers>=4.48.3
+accelerate
+sentencepiece
+protobuf

scripts/evaluate_models.py

@@ -0,0 +1,5 @@
+from telltale.models.eval_cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/modal/evaluate_models.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import modal
+
+
+APP_NAME = "telltale-model-eval"
+PROJECT_ROOT = None
+
+
+def _find_project_root() -> Path:
+    current_file = Path(__file__).resolve()
+    for parent in current_file.parents:
+        if (parent / "telltale").is_dir():
+            return parent
+    return Path("/root")
+
+
+PROJECT_ROOT = _find_project_root()
+
+image = (
+    modal.Image.from_registry("nvidia/cuda:12.4.1-runtime-ubuntu22.04", add_python="3.11") 
+    .apt_install("curl") 
+    .env(
+        {
+            "HF_XET_HIGH_PERFORMANCE": "1",
+            "PYTHONPATH": "/root",
+        }
+    )
+    .pip_install("huggingface_hub[hf_transfer]", "pydantic", "numpy")
+    .run_commands(
+        "python -m pip install --upgrade pip",
+        "python -m pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124",
+    )
+    .add_local_dir(PROJECT_ROOT / "telltale", remote_path="/root/telltale")
+)
+
+app = modal.App(APP_NAME, image=image)
+hf_cache = modal.Volume.from_name("telltale-hf-cache", create_if_missing=True)
+
+@app.function(
+    gpu="L4",
+    cpu=4,
+    memory=24_576,
+    timeout=20 * 60,
+    secrets=[modal.Secret.from_name("huggingface-secret")],
+    volumes={"/root/.cache/huggingface": hf_cache},
+)
+def run_model_eval(
+    candidate_labels: list[str] | None = None,
+    candidate_file_json: str | None = None,
+    case_ids: list[str] | None = None,
+    max_cases: int | None = 3,
+    max_tokens: int = 320,
+    context_size: int = 2048,
+    temperature: float = 0.30,
+    seed: int = 17,
+    n_gpu_layers: int = -1,
+    speech_max_words: int = 16,
+    rationale_max_words: int = 24,
+) -> str:
+    from telltale.models.eval_prompts import (
+        COMPARISON_MODEL_CANDIDATES,
+        DEFAULT_MODEL_CANDIDATES,
+        EVAL_CASES_BY_ID,
+        MODEL_CANDIDATES_BY_LABEL,
+        ModelCandidate,
+        get_eval_case,
+    )
+    from telltale.models.eval_runner import (
+        EvalRunConfig,
+        build_runtime_for_candidate,
+        evaluate_candidate,
+        write_eval_bundle,
+    )
+
+    candidates_by_label = dict(MODEL_CANDIDATES_BY_LABEL)
+    if candidate_file_json:
+        data = json.loads(candidate_file_json)
+        if isinstance(data, dict):
+            data = data.get("candidates", [])
+        for item in data:
+            candidate = ModelCandidate.from_mapping(item)
+            candidates_by_label[candidate.label] = candidate
+
+    if candidate_labels and "all" in candidate_labels:
+        selected_candidates = list(COMPARISON_MODEL_CANDIDATES)
+    elif candidate_labels:
+        selected_candidates = []
+        for label in candidate_labels:
+            if label not in candidates_by_label:
+                known = ", ".join(sorted(candidates_by_label))
+                raise ValueError(f"unknown candidate {label!r}; known candidates: {known}")
+            selected_candidates.append(candidates_by_label[label])
+    else:
+        selected_candidates = list(DEFAULT_MODEL_CANDIDATES)
+
+    if case_ids:
+        selected_cases = tuple(get_eval_case(case_id) for case_id in case_ids)
+    else:
+        selected_cases = tuple(EVAL_CASES_BY_ID.values())
+    if max_cases is not None:
+        selected_cases = selected_cases[:max_cases]
+
+    config = EvalRunConfig(
+        context_size=context_size,
+        max_tokens=max_tokens,
+        temperature=temperature,
+        seed=seed,
+        output_dir="/tmp/telltale_model_evals",
+        hardware_profile="modal_l4",
+        n_gpu_layers=n_gpu_layers,
+        speech_max_words=speech_max_words,
+        rationale_max_words=rationale_max_words,
+    )
+    results_by_candidate = {}
+    for candidate in selected_candidates:
+        runtime = build_runtime_for_candidate(candidate, config)
+        results_by_candidate[candidate.label] = evaluate_candidate(
+            candidate,
+            runtime,
+            cases=selected_cases,
+            config=config,
+        )
+
+    bundle = write_eval_bundle(results_by_candidate, output_dir=config.output_dir)
+    return json.dumps(
+        {
+            "candidate_labels": [candidate.label for candidate in selected_candidates],
+            "case_ids": [case.case_id for case in selected_cases],
+            "bundle": bundle,
+            "results": {
+                label: [json.loads(result.to_json_line()) for result in results]
+                for label, results in results_by_candidate.items()
+            },
+        },
+        ensure_ascii=True,
+        indent=2,
+    )
+
+
+@app.local_entrypoint()
+def main(
+    candidates: str = "nemotron_3_nano_4b_q4_k_m",
+    candidate_file: str = "",
+    cases: str = "",
+    max_cases: int = 1,
+    max_tokens: int = 0,
+    context_size: int = 2048,
+    temperature: float = -1.0,
+    seed: int = 17,
+    n_gpu_layers: int = -1,
+    profile: str = "auto",
+) -> None:
+    candidate_labels = _split_csv(candidates)
+    case_ids = _split_csv(cases)
+    candidate_file_json = Path(candidate_file).read_text(encoding="utf-8") if candidate_file else None
+    if candidate_labels == ["all"]:
+        from telltale.models.eval_prompts import COMPARISON_MODEL_CANDIDATES
+
+        candidate_labels = [candidate.label for candidate in COMPARISON_MODEL_CANDIDATES]
+    resolved_profile = _resolve_profile(profile, candidate_labels)
+    if resolved_profile == "nemotron":
+        max_tokens = max_tokens if max_tokens > 0 else 520
+        temperature = temperature if temperature >= 0 else 0.55
+        speech_max_words = 36
+        rationale_max_words = 44
+    else:
+        max_tokens = max_tokens if max_tokens > 0 else 320
+        temperature = temperature if temperature >= 0 else 0.30
+        speech_max_words = 16
+        rationale_max_words = 24
+    outputs = []
+    for label in candidate_labels:
+        try:
+            output = run_model_eval.remote(
+                candidate_labels=[label],
+                candidate_file_json=candidate_file_json,
+                case_ids=case_ids,
+                max_cases=max_cases,
+                max_tokens=max_tokens,
+                context_size=context_size,
+                temperature=temperature,
+                seed=seed,
+                n_gpu_layers=n_gpu_layers,
+                speech_max_words=speech_max_words,
+                rationale_max_words=rationale_max_words,
+            )
+            outputs.append({"candidate": label, "ok": True, "output": json.loads(output)})
+        except Exception as error:  # noqa: BLE001 - keep comparing after native/model crashes
+            outputs.append(
+                {
+                    "candidate": label,
+                    "ok": False,
+                    "error": f"{type(error).__name__}: {error}",
+                }
+            )
+    print(json.dumps({"isolated_candidate_runs": outputs}, ensure_ascii=True, indent=2))
+
+
+def _split_csv(value: str) -> list[str]:
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def _resolve_profile(profile: str, candidate_labels: list[str]) -> str:
+    if profile != "auto":
+        return profile
+    if candidate_labels and all(label.startswith("nemotron") for label in candidate_labels):
+        return "nemotron"
+    return "default"

telltale/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

telltale/agents/__init__.py

@@ -0,0 +1,26 @@
+from telltale.agents.decision import AgentDecision, parse_agent_decision, validate_and_repair
+from telltale.agents.dialogue import PlayerUtterance
+from telltale.agents.memory import AgentMemory, MemoryDelta
+from telltale.agents.profiles import (
+    AGENT_PROFILES,
+    DEFAULT_FINAL_BOSS_ID,
+    AgentProfile,
+    get_agent_profile,
+    profiles_for_floor,
+)
+from telltale.agents.prompts import build_agent_prompt
+
+__all__ = [
+    "AGENT_PROFILES",
+    "DEFAULT_FINAL_BOSS_ID",
+    "AgentDecision",
+    "AgentMemory",
+    "AgentProfile",
+    "MemoryDelta",
+    "PlayerUtterance",
+    "build_agent_prompt",
+    "get_agent_profile",
+    "parse_agent_decision",
+    "profiles_for_floor",
+    "validate_and_repair",
+]

telltale/agents/decision.py

@@ -0,0 +1,218 @@
+"""Parse, validate, and repair agent decisions from model output."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+import json
+import re
+from typing import Any, Iterable
+
+from telltale.agents.dialogue import PlayerUtterance
+from telltale.agents.memory import MemoryDelta
+from telltale.agents.prompts import build_agent_prompt
+from telltale.game.holdem import ActionType
+
+
+@dataclass
+class AgentDecision:
+    """
+    Describes a decision made by the agent. This is the output from the 
+    model.  
+    """
+    action: ActionType | str # The action the agent is taking. 
+    amount: int
+    speech: str # the thing that the agent says when making this decision. 
+    honest_rationale: str # the reason the agent gives for making this decision. 
+    emotional_state: str
+    memory_delta: MemoryDelta
+    source: str = "model"
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["action"] = self.action.value if isinstance(self.action, ActionType) else self.action
+        return data
+
+
+def parse_agent_decision(raw_model_output: str) -> AgentDecision:
+    """
+    Parses the model output into an AgentDecision object. 
+    """
+    data = _loads_model_json(raw_model_output)
+    missing = [field for field in ("action", "speech", "honest_rationale") if not data.get(field)]
+    if missing:
+        raise ValueError(f"model decision missing required field(s): {', '.join(missing)}")
+    raw_action = str(data["action"])
+    try:
+        action: ActionType | str = ActionType(raw_action)
+    except ValueError:
+        action = raw_action
+    return AgentDecision(
+        action=action,
+        amount=max(0, int(data.get("amount") or 0)),
+        speech=str(data["speech"]),
+        honest_rationale=str(data["honest_rationale"]),
+        emotional_state=str(data.get("emotional_state") or "composed"),
+        memory_delta=MemoryDelta.from_mapping(_normalize_memory_delta(data.get("memory_delta") or data.get("memory_updates"))),
+        source="model",
+    )
+
+
+def _normalize_memory_delta(data: Any) -> dict[str, Any] | None:
+    if not isinstance(data, dict):
+        return data
+    normalized = dict(data)
+    aliases = {
+        "respect_delta": "respect_for_player",
+        "fear_delta": "fear_of_player",
+        "charm_delta": "charmed_by_player",
+        "grudge_delta": "grudge_against_player",
+        "note": "summary",
+    }
+    for source, target in aliases.items():
+        if source in normalized and target not in normalized:
+            normalized[target] = normalized[source]
+    return normalized
+
+
+def validate_and_repair(
+    decision: AgentDecision,
+    legal_actions: Iterable[ActionType | str],
+    solver_recommendation: Any,
+) -> AgentDecision:
+    """
+    Validates whether the decision made by the model is valid. 
+    If it is not, it will be repaired (check or the first legal action from the solver). 
+    """
+
+    if not decision.speech.strip() or not decision.honest_rationale.strip():
+        raise ValueError("model decision requires non-empty speech and honest_rationale")
+
+    legal = _normalize_legal_actions(legal_actions)
+    if not legal:
+        repaired_action = ActionType.CHECK
+    elif decision.action not in legal:
+        repaired_action = _solver_action_or_first_legal(solver_recommendation, legal)
+    else:
+        repaired_action = decision.action
+
+    amount = _repair_amount(decision.amount, repaired_action, solver_recommendation)
+
+    decision.action = repaired_action
+    decision.amount = amount
+    decision.source = "model"
+    return decision
+
+
+def _loads_model_json(raw_model_output: str) -> dict[str, Any]:
+    """
+    Loads the model output as a JSON object. 
+    """
+    try:
+        data = json.loads(raw_model_output)
+    except json.JSONDecodeError:
+        match = re.search(r"\{.*\}", raw_model_output, flags=re.DOTALL)
+        if not match:
+            raise
+        data = json.loads(match.group(0))
+    if not isinstance(data, dict):
+        raise ValueError("model output must be a JSON object")
+    return data
+
+
+def _normalize_legal_actions(legal_actions: Iterable[ActionType | str]) -> set[ActionType]:
+    """
+    Normalizes the legal actions to a set of ActionType objects. 
+    """
+    legal: set[ActionType] = set()
+    for action in legal_actions:
+        if isinstance(action, ActionType):
+            legal.add(action)
+        else:
+            legal.add(ActionType(str(action)))
+    return legal
+
+
+def _solver_action_or_first_legal(solver_recommendation: Any, legal: set[ActionType]) -> ActionType:
+    """
+    Returns the action from the solver if it is legal, otherwise returns the first legal action. 
+    """
+    solver_action = _action_from_solver(solver_recommendation)
+    if solver_action in legal:
+        return solver_action
+    preferred_order = (
+        ActionType.CHECK,
+        ActionType.CALL,
+        ActionType.FOLD,
+        ActionType.BET,
+        ActionType.RAISE,
+        ActionType.ALL_IN,
+    )
+    for action in preferred_order:
+        if action in legal:
+            return action
+    return sorted(legal, key=lambda item: item.value)[0]
+
+
+def _action_from_solver(solver_recommendation: Any) -> ActionType | None:
+    """
+    Returns the action from the solver. 
+    """
+    value = None
+    if isinstance(solver_recommendation, dict):
+        value = solver_recommendation.get("action") or solver_recommendation.get("suggested_action")
+    else:
+        value = getattr(solver_recommendation, "action", None) or getattr(
+            solver_recommendation,
+            "suggested_action",
+            None,
+        )
+    if isinstance(value, ActionType):
+        return value
+    if isinstance(value, Enum):
+        value = value.value
+    if value is None:
+        return None
+    try:
+        return ActionType(str(value))
+    except ValueError:
+        return None
+
+
+def _repair_amount(action_amount: int, action: ActionType, solver_recommendation: Any) -> int:
+    if action in {ActionType.FOLD, ActionType.CHECK, ActionType.CALL}:
+        return 0
+    if action == ActionType.ALL_IN:
+        solver_amount = _amount_from_solver(solver_recommendation)
+        return max(0, solver_amount if solver_amount is not None else action_amount)
+    solver_amount = _amount_from_solver(solver_recommendation)
+    if action_amount <= 0 and solver_amount is not None:
+        return max(0, solver_amount)
+    return max(0, action_amount)
+
+
+def _amount_from_solver(solver_recommendation: Any) -> int | None:
+    """
+    Returns the amount from the solver. 
+    """
+    if isinstance(solver_recommendation, dict):
+        value = solver_recommendation.get("amount") or solver_recommendation.get("suggested_amount")
+    else:
+        value = getattr(solver_recommendation, "amount", None)
+        if value is None:
+            value = getattr(solver_recommendation, "suggested_amount", None)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+__all__ = [
+    "AgentDecision",
+    "PlayerUtterance",
+    "build_agent_prompt",
+    "parse_agent_decision",
+    "validate_and_repair",
+]

telltale/agents/dialogue.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import json
+
+
+@dataclass(frozen=True)
+class PlayerUtterance:
+    raw_text: str = ""
+    target_agent_id: str | None = None
+
+    @property
+    def is_empty(self) -> bool:
+        return self.raw_text.strip() == ""
+
+    def to_dict(self) -> dict[str, str | None]:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())

telltale/agents/memory.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+import json
+from typing import Any
+
+
+MAX_RECENT_ITEMS = 5
+
+
+@dataclass
+class MemoryDelta:
+    """
+    Describes a change in the agent's memory. 
+    """
+    respect_for_player: float | None = None
+    fear_of_player: float | None = None
+    charmed_by_player: float | None = None
+    grudge_against_player: float | None = None
+    recent_player_patterns: list[str] = field(default_factory=list)
+    recent_dialogue_impressions: list[str] = field(default_factory=list)
+    summary: str | None = None
+
+    @classmethod
+    def from_mapping(cls, data: dict[str, Any] | None) -> "MemoryDelta":
+        if not data:
+            return cls()
+        return cls(
+            respect_for_player=_optional_float(data.get("respect_for_player")),
+            fear_of_player=_optional_float(data.get("fear_of_player")),
+            charmed_by_player=_optional_float(data.get("charmed_by_player")),
+            grudge_against_player=_optional_float(data.get("grudge_against_player")),
+            recent_player_patterns=_string_list(data.get("recent_player_patterns")),
+            recent_dialogue_impressions=_string_list(data.get("recent_dialogue_impressions")),
+            summary=_optional_string(data.get("summary")),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class AgentMemory:
+    """
+    Describes the memory of an agent. 
+    """
+    agent_id: str  
+    respect_for_player: float = 0.0 # how much the agent respects the player. 
+    fear_of_player: float = 0.0 # how much the agent fears the player. 
+    charmed_by_player: float = 0.0 # how much the agent is charmed by the player. 
+    grudge_against_player: float = 0.0 # how much the agent is grudge against the player. 
+    recent_player_patterns: list[str] = field(default_factory=list) # a list of recent patterns the player has exhibited. 
+    recent_dialogue_impressions: list[str] = field(default_factory=list) # a list of recent dialogue impressions the player has given. 
+    summary: str = "" # a summary of the agent's memory. 
+    max_recent_items: int = MAX_RECENT_ITEMS # the maximum number of recent items to store. 
+
+    def __post_init__(self) -> None:
+        self.respect_for_player = _clamp(self.respect_for_player, -1.0, 1.0)
+        self.fear_of_player = _clamp(self.fear_of_player, 0.0, 1.0)
+        self.charmed_by_player = _clamp(self.charmed_by_player, 0.0, 1.0)
+        self.grudge_against_player = _clamp(self.grudge_against_player, 0.0, 1.0)
+        self.recent_player_patterns = _bounded(_string_list(self.recent_player_patterns), self.max_recent_items)
+        self.recent_dialogue_impressions = _bounded(
+            _string_list(self.recent_dialogue_impressions),
+            self.max_recent_items,
+        )
+        self.summary = str(self.summary or "")
+
+    @classmethod
+    def neutral(cls, agent_id: str) -> "AgentMemory":
+        return cls(agent_id=agent_id)
+
+    @classmethod
+    def reset_for_run(cls, agent_id: str) -> "AgentMemory":
+        return cls.neutral(agent_id)
+
+    def apply_delta(self, delta: MemoryDelta | dict[str, Any] | None) -> None:
+        update = delta if isinstance(delta, MemoryDelta) else MemoryDelta.from_mapping(delta)
+        if update.respect_for_player is not None:
+            self.respect_for_player = _clamp(update.respect_for_player, -1.0, 1.0)
+        if update.fear_of_player is not None:
+            self.fear_of_player = _clamp(update.fear_of_player, 0.0, 1.0)
+        if update.charmed_by_player is not None:
+            self.charmed_by_player = _clamp(update.charmed_by_player, 0.0, 1.0)
+        if update.grudge_against_player is not None:
+            self.grudge_against_player = _clamp(update.grudge_against_player, 0.0, 1.0)
+        if update.recent_player_patterns:
+            self.recent_player_patterns = _bounded(
+                [*self.recent_player_patterns, *update.recent_player_patterns],
+                self.max_recent_items,
+            )
+        if update.recent_dialogue_impressions:
+            self.recent_dialogue_impressions = _bounded(
+                [*self.recent_dialogue_impressions, *update.recent_dialogue_impressions],
+                self.max_recent_items,
+            )
+        if update.summary is not None:
+            self.summary = update.summary
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+
+def _bounded(items: list[str], limit: int) -> list[str]:
+    return items[-limit:]
+
+
+def _clamp(value: float, lower: float, upper: float) -> float:
+    return max(lower, min(upper, float(value)))
+
+
+def _optional_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _optional_string(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _string_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        return [str(value)]
+    return [str(item) for item in value if item is not None]

telltale/agents/profiles.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+
+@dataclass(frozen=True)
+class AgentProfile:
+    agent_id: str
+    name: str
+    floor_min: int
+    floor_max: int
+    can_be_boss: bool
+    character_summary: str
+    poker_style: str
+    dialogue_style: str
+    honesty_style: str
+    speech_style: str
+    voice_id: str
+
+
+AGENT_PROFILES: tuple[AgentProfile, ...] = (
+    AgentProfile(
+        agent_id="mike_mcdermott",
+        name="Mike McDermott",
+        floor_min=1,
+        floor_max=4,
+        can_be_boss=False,
+        character_summary=(
+            "Mike is a Rounders-style grinder who learned the game in back rooms and law-school basements. "
+            "He treats every pot like a solved argument and believes discipline beats talent over enough hands. "
+            "He is not flashy, but he notices when someone is playing scared or telling a story that does not add up."
+        ),
+        poker_style=(
+            "He plays patient, bluff-aware poker and rarely forces action without a credible narrative behind it. "
+            "When the board and betting line make sense, he is comfortable applying pressure, but he will release marginal spots rather than gamble on ego."
+        ),
+        dialogue_style=(
+            "He listens closely for overconfidence and respects opponents who keep their table talk disciplined. "
+            "Cheap needles and empty bravado annoy him, and he is more likely to engage with players who sound like they are actually thinking."
+        ),
+        honesty_style=(
+            "He is usually candid about his reads and what the action is telling him, even when he is bluffing. "
+            "He keeps exact hand strength behind a half-smile and rarely volunteers more information than the hand requires."
+        ),
+        speech_style=(
+            "His lines are measured, read-heavy, and dry, often sounding like notes taken at the table rather than performance. "
+            "He favors short sentences and lets a pause do the work when he wants someone to talk themselves into a mistake."
+        ),
+        voice_id="mike_measured_grinder",
+    ),
+    AgentProfile(
+        agent_id="molly_bloom",
+        name="Molly Bloom",
+        floor_min=1,
+        floor_max=5,
+        can_be_boss=True,
+        character_summary=(
+            "Molly is a Molly's Game-style host who has watched every kind of ego lose money in the same chair. "
+            "She runs the room like a professional operation and reads people the way a host reads a guest list. "
+            "She is calm under pressure because she has already seen the expensive version of whatever you are trying."
+        ),
+        poker_style=(
+            "She plays patient, selective poker and waits for opponents to donate chips through loose play or emotional sizing. "
+            "She punishes weak lines without needing to be loud about it, and she rarely spews just to prove a point."
+        ),
+        dialogue_style=(
+            "She is hard to intimidate, largely charm-resistant, and quick to notice performative confidence. "
+            "Players who try to own the room with noise usually find her quieter and more dangerous than they expected."
+        ),
+        honesty_style=(
+            "She is polished and direct, telling the truth in a way that still protects her leverage at the table. "
+            "She will explain what she thinks you did wrong without handing you the full ledger of what she holds."
+        ),
+        speech_style=(
+            "Her speech is elegant, clipped, and observant, like a host settling a room with one well-placed line. "
+            "She sounds composed even when she is applying pressure, and she rarely wastes words on empty theater."
+        ),
+        voice_id="molly_polished_host",
+    ),
+    AgentProfile(
+        agent_id="worm",
+        name="Worm",
+        floor_min=1,
+        floor_max=3,
+        can_be_boss=False,
+        character_summary=(
+            "Worm is a Rounders-style opportunist who turns every hand into a side hustle and every table into a chance to get even. "
+            "He is likable until he is not, and his confidence often arrives a little faster than his math. "
+            "He survives on nerve, memory, and the hope that nobody at the table is paying close enough attention."
+        ),
+        poker_style=(
+            "His game is volatile and tricky, with sudden stabs at neglected pots and spite calls when he feels disrespected. "
+            "He can make strong plays when cornered, but he is just as likely to chase a feeling if the table gives him an opening."
+        ),
+        dialogue_style=(
+            "Needles get under his skin quickly, while sincere kindness can disarm him for a hand or two. "
+            "He treats bluffs like dares and will often talk himself into a bigger pot just to see if you meant it."
+        ),
+        honesty_style=(
+            "He is loose with the truth in speech and happy to sell a story that sounds better than his cards. "
+            "When he is cornered or annoyed, he becomes surprisingly honest about how much the hand has gotten under his skin."
+        ),
+        speech_style=(
+            "He talks fast, slangy, and needling, with jokes that arrive half a beat too early to be entirely safe. "
+            "His lines feel improvised and personal, like he is trying to win the hand and the conversation at the same time."
+        ),
+        voice_id="worm_fast_talker",
+    ),
+    AgentProfile(
+        agent_id="lancey_howard",
+        name="Lancey Howard",
+        floor_min=2,
+        floor_max=5,
+        can_be_boss=True,
+        character_summary=(
+            "Lancey is a Cincinnati Kid-style veteran who has outlasted whole rooms of hot streaks and louder reputations. "
+            "He carries the calm of someone who has seen the same trick dressed up in new clothes a dozen times. "
+            "He does not need to dominate the table to own it; patience and timing are enough."
+        ),
+        poker_style=(
+            "He plays composed, fundamentally sound poker and is comfortable making thin but disciplined decisions. "
+            "He does not chase drama, but he will pay attention when a younger player starts believing their own story too much."
+        ),
+        dialogue_style=(
+            "He is rarely rattled and treats table talk as another bet placed in the middle of the hand. "
+            "He listens for patterns, not volume, and he gives more weight to consistency than to one loud line."
+        ),
+        honesty_style=(
+            "He lies rarely, but he frames the truth like a lesson with one page deliberately missing. "
+            "He may tell you what kind of player you are being without telling you what he actually has."
+        ),
+        speech_style=(
+            "His speech is calm, old-school, and aphoristic, with a veteran's pause before the blade lands. "
+            "He sounds unhurried even in big pots, as if time is one more advantage he has already banked."
+        ),
+        voice_id="lancey_old_school",
+    ),
+    AgentProfile(
+        agent_id="ginger_mckenna",
+        name="Ginger McKenna",
+        floor_min=1,
+        floor_max=4,
+        can_be_boss=False,
+        character_summary=(
+            "Ginger is a Casino-style gambler who makes glamour feel like a pressure tactic and chaos feel like an invitation. "
+            "She can be magnetic at the table, but the performance is never entirely separate from the play. "
+            "When she is locked in, her confidence is real enough to make even disciplined opponents hesitate."
+        ),
+        poker_style=(
+            "She plays high-variance poker and becomes splashy when excitement takes over or a dramatic read clicks. "
+            "She is willing to overbet a story if the table has given her enough emotional room to sell it."
+        ),
+        dialogue_style=(
+            "Charm can move her, intimidation can bore her, and needles can light the fuse faster than most players expect. "
+            "She responds to energy at the table and is especially dangerous when she feels underestimated."
+        ),
+        honesty_style=(
+            "She is emotionally honest in the moment, even when her strategy is deliberately selective. "
+            "She knows she is performing and will admit what she is feeling long before she admits what she is holding."
+        ),
+        speech_style=(
+            "Her lines are bright, teasing, and theatrical, with sudden flashes of steel when the pot gets serious. "
+            "She can sound playful right up to the point where the table realizes the joke had a price attached."
+        ),
+        voice_id="ginger_bright_gambler",
+    ),
+    AgentProfile(
+        agent_id="ace_rothstein",
+        name="Ace Rothstein",
+        floor_min=2,
+        floor_max=5,
+        can_be_boss=True,
+        character_summary=(
+            "Ace is a Casino-style floor manager who sees the table as an operation to audit rather than a game to improvise. "
+            "He notices sloppy process the way other players notice missed draws, and he has little patience for emotional leakage. "
+            "He plays like someone who expects the numbers to matter in the end."
+        ),
+        poker_style=(
+            "He plays tight-aggressive, pot-odds-conscious poker and is allergic to lines that do not reconcile with the board. "
+            "He prefers clean decisions over heroic guesses and will punish opponents who donate chips through imprecision."
+        ),
+        dialogue_style=(
+            "He does not reward theatrics and respects opponents who speak with precision instead of volume. "
+            "Players who leak frustration, panic, or vanity usually find him colder and more exacting in response."
+        ),
+        honesty_style=(
+            "He is blunt when the math is obvious and guarded when the leverage is not. "
+            "He will tell you that your line was bad without necessarily telling you how he plans to collect on that mistake."
+        ),
+        speech_style=(
+            "His speech is minimal, controlled, and managerial, as if every sentence has already been reconciled. "
+            "He rarely raises his voice, but his quiet lines can feel more final than another player's whole monologue."
+        ),
+        voice_id="ace_controlled_manager",
+    ),
+    AgentProfile(
+        agent_id="teddy_kgb",
+        name="Teddy KGB",
+        floor_min=5,
+        floor_max=5,
+        can_be_boss=True,
+        character_summary=(
+            "Teddy is a Rounders-style final boss who treats every hand as a confession and every opponent as a story waiting to break. "
+            "He is theatrical on purpose, because pressure is part of his game as much as cards and chips. "
+            "By the time he is across from you, he has already decided that the hand is about more than equity."
+        ),
+        poker_style=(
+            "He plays adaptive, theatrical poker and looks for repeated patterns he can punish once fear enters the pot. "
+            "He is comfortable turning a small edge into a psychological ordeal, especially against scared money."
+        ),
+        dialogue_style=(
+            "He remembers emotional pressure, mocks repeated tactics, and turns fear into a price you have to pay to continue. "
+            "Players who show the same tell twice should expect him to name it out loud and make the next decision harder."
+        ),
+        honesty_style=(
+            "He is honest in riddles and reveals enough reasoning to make the player sweat without giving away the hand. "
+            "He enjoys letting you think you understand him right up until the moment you realize you were being studied."
+        ),
+        speech_style=(
+            "His speech is grand, amused, and predatory, with short flourishes and heavy pauses that feel deliberately staged. "
+            "He sounds like he is enjoying the hand even when he is not, which makes it harder to tell when he actually is."
+        ),
+        voice_id="teddy_theatrical_boss",
+    ),
+    AgentProfile(
+        agent_id="ben_campbell",
+        name="Ben Campbell",
+        floor_min=1,
+        floor_max=4,
+        can_be_boss=False,
+        character_summary=(
+            "Ben is a 21-style table guide who is still deciding whether caution is courage or just another way to stay alive. "
+            "He is sharp with patterns and uncomfortable with chaos, which makes him dangerous in the right spot and brittle in the wrong one. "
+            "He plays like someone who understands the math but is still learning what the math costs emotionally."
+        ),
+        poker_style=(
+            "He plays measured, pattern-oriented poker and prefers clean spots with explainable pressure behind them. "
+            "He avoids unnecessary gambles, but he can become surprisingly firm when he thinks he has read the table correctly."
+        ),
+        dialogue_style=(
+            "He responds well to reasoned talk, grows wary of chaos, and notices repeated emotional plays faster than he admits. "
+            "Players who try to rush or rattle him often get a quieter, more careful version of him instead of a fold."
+        ),
+        honesty_style=(
+            "He is often candid, especially when explaining rhythm, timing, or what the betting line suggests. "
+            "He is less willing to discuss exact holdings and will redirect toward process when the question gets too direct."
+        ),
+        speech_style=(
+            "His speech is quiet, analytical, and slightly self-conscious, like a calculation spoken aloud before he commits to it. "
+            "He sounds young in the best sense: observant, careful, and still surprised when the table turns personal."
+        ),
+        voice_id="ben_quiet_counter",
+    ),
+    AgentProfile(
+        agent_id="rusty_ryan",
+        name="Rusty Ryan",
+        floor_min=2,
+        floor_max=5,
+        can_be_boss=True,
+        character_summary=(
+            "Rusty is an Ocean's Eleven-style closer who makes pressure look like leisure and big pots look like errands he has run before. "
+            "He is at ease in uncomfortable spots because discomfort is usually someone else's problem. "
+            "He gives the impression that he is barely trying, which is often the most expensive impression at the table."
+        ),
+        poker_style=(
+            "He stays cool under fire, plays opportunistically in position, and likes sudden tempo changes in high-stakes spots. "
+            "He is willing to let a hand breathe before striking, and he rarely looks as committed as he actually is."
+        ),
+        dialogue_style=(
+            "Intimidation backfires on him, charm becomes sport, and bluffs often invite a cleaner bluff in return. "
+            "He enjoys verbal sparring and will treat table talk like a side game he is already winning."
+        ),
+        honesty_style=(
+            "He is casually honest when it amuses him and evasive when the hand still has a punchline left. "
+            "He may tell you the truth in a way that sounds like a joke, which makes it harder to know what to believe."
+        ),
+        speech_style=(
+            "His speech is laid-back, witty, and concise, like he already knows where the exit is and is in no hurry to reach it. "
+            "He can deflate tension with one line and then raise the pot on the next without changing expression."
+        ),
+        voice_id="rusty_cool_closer",
+    ),
+    AgentProfile(
+        agent_id="sydney",
+        name="Sydney",
+        floor_min=3,
+        floor_max=5,
+        can_be_boss=True,
+        character_summary=(
+            "Sydney is a Hard Eight-style veteran who understands the cost of every favor, every debt, and every bad night at the table. "
+            "She has seen enough desperation to distrust charm on sight and enough quiet competence to respect it immediately. "
+            "She does not play for applause; she plays to still be standing when the room gets honest."
+        ),
+        poker_style=(
+            "She plays disciplined, observant poker and is especially strong against obvious charm, panic, or sloppy heroics. "
+            "She waits for players to reveal who they are under pressure, then makes them pay for the revelation."
+        ),
+        dialogue_style=(
+            "She reads speech aggressively, distrusts charm, and respects opponents who stay consistent when the pot grows. "
+            "Players who perform for the table usually get less patience from her than players who simply keep their word."
+        ),
+        honesty_style=(
+            "She is plainspoken and morally direct, though never careless with live information at the table. "
+            "She will tell you what she thinks of your line without turning the hand into a confession booth."
+        ),
+        speech_style=(
+            "Her speech is sparse, grave, and humane, with lines that land like advice, warning, or both at once. "
+            "She does not fill silence for sport, so when she speaks in a big pot, the table tends to listen."
+        ),
+        voice_id="sydney_sparse_veteran",
+    ),
+)
+
+DEFAULT_FINAL_BOSS_ID = "teddy_kgb"
+
+
+def get_agent_profile(agent_id: str) -> AgentProfile:
+    for profile in AGENT_PROFILES:
+        if profile.agent_id == agent_id:
+            return profile
+    raise KeyError(f"unknown agent profile: {agent_id}")
+
+
+def profiles_for_floor(floor_number: int, *, include_bosses: bool = True) -> tuple[AgentProfile, ...]:
+    return tuple(
+        profile
+        for profile in AGENT_PROFILES
+        if profile.floor_min <= floor_number <= profile.floor_max
+        and (include_bosses or not profile.can_be_boss)
+    )
+
+
+def profile_field_names() -> set[str]:
+    return {field.name for field in fields(AgentProfile)}

telltale/agents/prompts.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from enum import Enum
+import json
+from typing import Any, Iterable
+
+from telltale.agents.dialogue import PlayerUtterance
+from telltale.agents.memory import AgentMemory
+from telltale.agents.profiles import AgentProfile
+
+
+def build_agent_prompt(
+    agent_profile: AgentProfile,
+    memory: AgentMemory,
+    public_state: Any,
+    private_agent_state: Any,
+    solver_recommendation: Any,
+    player_utterance: PlayerUtterance | None,
+    legal_actions: Iterable[Any],
+    *,
+    speech_max_words: int = 28,
+    rationale_max_words: int = 36,
+) -> str:
+    """
+    Builds the prompt for the agent. 
+    """
+    legal_action_values = [_stringify(action) for action in legal_actions]
+    payload = {
+        "profile": {
+            "name": agent_profile.name,
+            "character_summary": agent_profile.character_summary,
+            "poker_style": agent_profile.poker_style,
+            "dialogue_style": agent_profile.dialogue_style,
+            "honesty_style": agent_profile.honesty_style,
+            "speech_style": agent_profile.speech_style,
+        },
+        "memory": {
+            "respect_for_player": memory.respect_for_player,
+            "fear_of_player": memory.fear_of_player,
+            "charmed_by_player": memory.charmed_by_player,
+            "grudge_against_player": memory.grudge_against_player,
+            "recent_player_patterns": memory.recent_player_patterns,
+            "recent_dialogue_impressions": memory.recent_dialogue_impressions,
+            "summary": memory.summary,
+        },
+        "public_state": _compact(public_state),
+        "private_agent_state": _compact(private_agent_state),
+        "solver_recommendation": _compact(solver_recommendation),
+        "legal_actions": legal_action_values,
+        "legal_amount_guidance": (
+            "Use amount 0 for fold/check/call. For bet/raise/all_in only, choose a non-negative chip amount."
+        ),
+        "required_output": {
+            "exact_keys_only": [
+                "action",
+                "amount",
+                "speech",
+                "honest_rationale",
+                "emotional_state",
+                "memory_delta",
+            ],
+            "action": "one of legal_actions",
+            "amount": "0 for fold/check/call; integer chips for bet/raise/all_in",
+            "speech": f"in-character table line, max {speech_max_words} words",
+            "honest_rationale": f"brief honest reason, max {rationale_max_words} words",
+            "emotional_state": "short phrase",
+            "memory_delta": "object with only changed fields; allowed fields are respect_for_player, fear_of_player, charmed_by_player, grudge_against_player, recent_player_patterns, recent_dialogue_impressions, summary",
+        },
+    }
+    if player_utterance is not None and not player_utterance.is_empty:
+        payload["player_utterance"] = player_utterance.to_dict()
+
+    return "\n".join(
+        [
+            "You are choosing one Texas Hold'em action for a fixed Telltale AI opponent.",
+            "Return only valid JSON matching the required schema.",
+            "Do not include markdown, comments, trailing prose, or keys outside required_output.exact_keys_only.",
+            "The solver recommendation is advisory context, not a command.",
+            "Your rationale should be honest. Your speech should sound like the character at the table.",
+            "You may play suboptimally when personality, memory, or player dialogue justify it.",
+            json.dumps(payload, default=_json_default, ensure_ascii=True, separators=(",", ":")),
+            "Return one complete JSON object now. Do not add any key after memory_delta.",
+        ]
+    )
+
+
+def _compact(value: Any) -> Any:
+    if value is None:
+        return None
+    if is_dataclass(value):
+        return asdict(value)
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    if isinstance(value, dict):
+        return {str(key): _compact(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_compact(item) for item in value]
+    if isinstance(value, Enum):
+        return value.value
+    return value
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    if is_dataclass(value):
+        return asdict(value)
+    return str(value)
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, Enum):
+        return str(value.value)
+    return str(value)

telltale/agents/trace.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+from typing import Any
+
+
+class TraceLogger:
+    def __init__(self, run_id: str, root_dir: str | Path = "runs"):
+        self.run_id = run_id
+        self.run_dir = Path(root_dir) / run_id
+        self.path = self.run_dir / "trace.jsonl"
+        self.records: list[dict[str, Any]] = []
+
+    def record(self, **fields: Any) -> dict[str, Any]:
+        record = {
+            "trace_version": 1,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "run_id": self.run_id,
+            **fields,
+        }
+        self.records.append(record)
+        self.run_dir.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as file:
+            file.write(json.dumps(record, default=_json_default, ensure_ascii=True) + "\n")
+        return record
+
+    def export_text(self) -> str:
+        if self.path.exists():
+            return self.path.read_text(encoding="utf-8")
+        return "\n".join(json.dumps(record, default=_json_default) for record in self.records)
+
+
+def _json_default(value: Any) -> Any:
+    if is_dataclass(value):
+        return asdict(value)
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    if hasattr(value, "value"):
+        return value.value
+    return str(value)

telltale/game/__init__.py

@@ -0,0 +1,23 @@
+# Public API for the game resources
+
+from telltale.game.cards import Card, Deck
+from telltale.game.economy import RunState, RunStatus
+from telltale.game.engine import HoldemEngine
+from telltale.game.floors import FLOOR_CONFIGS, FloorConfig
+from telltale.game.holdem import HandState, PlayerState, Street
+from telltale.game.perks import ActivePerk, PerkDefinition
+
+__all__ = [
+    "ActivePerk",
+    "Card",
+    "Deck",
+    "FLOOR_CONFIGS",
+    "FloorConfig",
+    "HoldemEngine",
+    "HandState",
+    "PerkDefinition",
+    "PlayerState",
+    "RunState",
+    "RunStatus",
+    "Street",
+]

telltale/game/cards.py

@@ -0,0 +1,100 @@
+"""
+This file contains the Card and Deck classes for the game of poker.
+
+Cards are represented as a string of two characters, the rank and the suit. 
+For example, "Ah" is the ace of hearts.
+
+Deck is a collection of 52 unique cards.
+It can be shuffled and drawn from.
+
+CardError is raised when card or deck operations are invalid.
+"""
+
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import random
+
+
+RANKS = "23456789TJQKA"
+SUITS = "cdhs"
+
+
+class CardError(ValueError):
+    """Raised when card or deck operations are invalid."""
+
+'''   
+Note for self regarding dataclasses:
+
+The order=true argument will add things like __lt__, __gt__, __le__, __ge__
+, __eq__, and __ne__ methods to the class. These will be useful for sorting 
+and comparing cards.
+
+The frozen=True argument adds __setattr__ and __delattr__ methods to the class. 
+These methods will prevent the card from being modified after it is created.
+'''
+@dataclass(frozen=True, order=True)
+class Card:
+    rank: str
+    suit: str
+
+    @classmethod
+    def parse(cls, value: str) -> "Card":
+        """ 
+        Parse a string representation of a card into a Card object.
+        """
+        if len(value) != 2:
+            raise CardError(f"card must be two characters like 'Ah': {value!r}")
+        rank = value[0]
+        suit = value[1]
+        if rank not in RANKS:
+            raise CardError(f"invalid rank {rank!r} in {value!r}")
+        if suit not in SUITS:
+            raise CardError(f"invalid suit {suit!r} in {value!r}")
+        return cls(rank=rank, suit=suit)
+
+    def __str__(self) -> str:
+        return f"{self.rank}{self.suit}"
+
+
+class Deck:
+    def __init__(self, seed: int | str | bytes | None = None, cards: list[Card] | None = None):
+        # note to self: [:] is a shallow copy of the list
+        if cards is not None:
+            self.cards = cards[:]
+        else:
+            self.cards = _standard_deck()
+        if cards is None and seed is not None:
+            random.Random(seed).shuffle(self.cards)
+
+    @classmethod
+    def shuffled(cls, seed: int | str | bytes | None = None) -> "Deck":
+        return cls(seed=seed)
+
+    def draw(self, count: int = 1) -> Card | list[Card]:
+        if count < 1:
+            raise CardError("draw count must be at least 1")
+        if count > len(self.cards):
+            raise CardError(f"cannot draw {count} cards from deck with {len(self.cards)} cards")
+        drawn: list[Card] = []
+        for _ in range(count):
+            drawn.append(self.cards.pop())
+        return drawn[0] if count == 1 else drawn
+
+    def to_strings(self) -> list[str]:
+        strings: list[str] = []
+        for card in self.cards:
+            strings.append(str(card))
+        return strings
+
+    def __len__(self) -> int:
+        return len(self.cards)
+
+
+def _standard_deck() -> list[Card]:
+    cards: list[Card] = []
+    for suit in SUITS:
+        for rank in RANKS:
+            cards.append(Card(rank, suit))
+    return cards

telltale/game/economy.py

@@ -0,0 +1,329 @@
+"""
+"""
+
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from hashlib import sha256
+from random import Random
+from uuid import uuid5, NAMESPACE_URL
+
+from telltale.game.floors import FloorConfig, get_floor_config
+from telltale.game.holdem import HandState
+from telltale.game.perks import ActivePerk, PERK_DEFINITIONS, PerkEffectContext, TriggerTiming, get_perk
+
+
+STARTING_BANKROLL = 250
+MAX_CONTINUES = 2
+
+
+class RunStatus(str, Enum):
+    ACTIVE = "active"
+    WON = "won"
+    LOST = "lost"
+
+
+@dataclass
+class TableState:
+    """
+    Represents the state of the table for a given floor. 
+    A table is created when a player enters a floor and is destroyed when the floor is won or lost.
+    """
+    floor_number: int
+    seed: str
+    player_stack: int # number of chips the player has available to bet
+    opponent_stacks: list[int]
+    small_blind: int
+    big_blind: int
+    hand_index: int = 0 # index of the current hand being played
+    pending_metadata: dict = field(default_factory=dict)
+
+    def serialize(self) -> dict:
+        return {
+            "floor_number": self.floor_number,
+            "seed": self.seed,
+            "player_stack": self.player_stack,
+            "opponent_stacks": list(self.opponent_stacks),
+            "small_blind": self.small_blind,
+            "big_blind": self.big_blind,
+            "hand_index": self.hand_index,
+            "pending_metadata": dict(self.pending_metadata),
+        }
+
+
+@dataclass
+class RunState:
+    """
+    A run is a sequence of floors that a player plays.
+    Losing a floor ends the run unless the player uses a continue.
+    Winning a floor advances to the next floor and rewards the player with perks.
+    RunState manages the state of the run and provides methods to interact with the game.
+    """
+    run_id: str
+    seed: str
+    floor_index: int # index of the current floor being played
+    # bankroll is the number of chips the player has available to bet. 
+    bankroll: int 
+    # continues track how many times the player has bailed out to keep the run alive.
+    # each continue increases the cost of the next floor's buy-in.
+    # the player starts with 0 continues and can use up to MAX_CONTINUES per run.
+    continues: int = 0
+    # perks are special abilities that can be used to gain an advantage over the house. 
+    # the player starts with no active perks and can earn them by winning floors. 
+    active_perks: list[ActivePerk] = field(default_factory=list)
+    completed_floors: list[int] = field(default_factory=list)
+    status: RunStatus = RunStatus.ACTIVE
+    current_hand: HandState | None = None
+    current_table: TableState | None = None
+    event_log: list[dict] = field(default_factory=list)
+    available_rewards: list[str] = field(default_factory=list)
+    awaiting_reward: bool = False
+
+    @classmethod
+    def start(cls, seed: int | str | bytes | None = None, bankroll: int = STARTING_BANKROLL) -> "RunState":
+        normalized_seed = _normalize_seed(seed)
+        run = cls(
+            run_id=str(uuid5(NAMESPACE_URL, f"telltale-run:{normalized_seed}")),
+            seed=normalized_seed,
+            floor_index=0,
+            bankroll=bankroll,
+        )
+        run._log("run_started", bankroll=bankroll)
+        return run
+
+    @property
+    def current_floor(self) -> FloorConfig:
+        return get_floor_config(self.floor_index)
+
+    def floor_seed(self, floor_index: int | None = None) -> str:
+        index = self.floor_index if floor_index is None else floor_index
+        return derive_seed(self.seed, "floor", index)
+
+    def hand_seed(self, floor_index: int | None = None, hand_index: int = 0) -> str:
+        index = self.floor_index if floor_index is None else floor_index
+        return derive_seed(self.seed, "hand", index, hand_index)
+
+    def buy_in_for_floor(self, floor: FloorConfig | None = None) -> int:
+        """
+        Calculates the buy-in for the current floor. The buy-in is the amount of chips the player must pay to enter the floor.
+        The buy-in is affected by the player's continues and active perks.
+        - If the player has 1 continue, the buy-in is increased by 15%.
+        - If the player has 2 or more continues, the buy-in is increased by 30%.
+        - If the player has the Buy-In Discount perk, the buy-in is reduced by 15%.
+        - If the player has the Continue Waiver perk, one of the used continues is waived for buy-in penalty calculations, which will 
+        reduce the buy-in by the amount of the waived continue.
+        """
+        floor = self.current_floor if floor is None else floor
+        amount = floor.buy_in
+        effective_continues = self.effective_continues()
+        if effective_continues == 1:
+            amount = round(amount * 1.15)
+        elif effective_continues >= 2:
+            amount = round(amount * 1.30)
+
+        for perk in list(self.active_perks):
+            definition = get_perk(perk.perk_id)
+            if definition.trigger_timing != TriggerTiming.NEXT_FLOOR_BUY_IN:
+                continue
+            result = definition.effect(PerkEffectContext(amount=amount))
+            if result.amount is not None:
+                amount = result.amount
+        return max(0, amount)
+
+    def effective_continues(self) -> int:
+        count = self.continues
+        for perk in self.active_perks:
+            definition = get_perk(perk.perk_id)
+            if definition.trigger_timing == TriggerTiming.CONTINUE_PENALTY:
+                result = definition.effect(PerkEffectContext(continues=count))
+                if result.continues is not None:
+                    count = result.continues
+        return max(0, count)
+
+    def enter_current_floor(self, use_continue: bool = True) -> bool:
+        if self.status != RunStatus.ACTIVE:
+            return False
+        if self.awaiting_reward:
+            raise ValueError("choose a reward before entering the next floor")
+        if self.current_table is not None:
+            return True
+
+        floor = self.current_floor
+        buy_in = self.buy_in_for_floor(floor)
+        if self.bankroll < buy_in:
+            if not self._use_continue_if_allowed(buy_in, use_continue):
+                self.status = RunStatus.LOST
+                self._log("run_lost", reason="insufficient_bankroll", floor_number=floor.floor_number)
+                return False
+
+        self.bankroll -= buy_in
+        if self.bankroll < 0:
+            raise ValueError("bankroll cannot be negative")
+        self._consume_perks(TriggerTiming.NEXT_FLOOR_BUY_IN)
+        self.current_table = self._create_table(floor)
+        self._log("floor_entered", floor_number=floor.floor_number, buy_in=buy_in, bankroll=self.bankroll)
+        return True
+
+    def win_current_floor(self, ending_stack: int | None = None) -> None:
+        if self.current_table is None:
+            self.enter_current_floor()
+        if self.current_table is None or self.status != RunStatus.ACTIVE:
+            return
+        floor = self.current_floor
+        stack = self.current_table.player_stack if ending_stack is None else ending_stack
+        stack = max(0, stack)
+        self.bankroll += stack
+        self.completed_floors.append(floor.floor_number)
+        self.current_table = None
+        self.current_hand = None
+        self._log("floor_won", floor_number=floor.floor_number, returned_stack=stack, bankroll=self.bankroll)
+
+        if floor.is_boss:
+            self.status = RunStatus.WON
+            self.available_rewards = []
+            self.awaiting_reward = False
+            self._log("run_won")
+            return
+
+        self.available_rewards = self._reward_choices(floor)
+        self.awaiting_reward = True
+
+    def lose_current_floor(self, all_in_loss: bool = False) -> None:
+        if self.current_table is None:
+            return
+        floor = self.current_floor
+        recovered = 0
+        if all_in_loss:
+            recovered = self._trigger_insurance(self.current_table.player_stack)
+            self.bankroll += recovered
+        self.current_table = None
+        self.current_hand = None
+        self._log("floor_lost", floor_number=floor.floor_number, recovered_stack=recovered, bankroll=self.bankroll)
+        if floor.is_boss:
+            self.status = RunStatus.LOST
+            self._log("run_lost", reason="boss_floor_loss")
+            return
+        if not self._use_continue_if_allowed(self.current_floor.buy_in, use_continue=True):
+            self.status = RunStatus.LOST
+            self._log("run_lost", reason="max_continues")
+
+    def choose_reward(self, perk_id: str) -> None:
+        if not self.awaiting_reward:
+            raise ValueError("there is no reward to choose")
+        if perk_id not in self.available_rewards:
+            raise ValueError(f"{perk_id} is not an available reward")
+        definition = get_perk(perk_id)
+        self.active_perks.append(ActivePerk.from_definition(definition))
+        self.available_rewards = []
+        self.awaiting_reward = False
+        self.floor_index += 1
+        self._log("reward_chosen", perk_id=perk_id)
+
+    def serialize_public(self) -> dict:
+        return {
+            "run_id": self.run_id,
+            "seed": self.seed,
+            "floor_index": self.floor_index,
+            "floor_number": self.current_floor.floor_number if self.status == RunStatus.ACTIVE else None,
+            "bankroll": self.bankroll,
+            "continues": self.continues,
+            "active_perks": [perk.serialize() for perk in self.active_perks],
+            "completed_floors": list(self.completed_floors),
+            "status": self.status.value,
+            "current_table": self.current_table.serialize() if self.current_table else None,
+            "available_rewards": list(self.available_rewards),
+            "awaiting_reward": self.awaiting_reward,
+            "event_log": list(self.event_log),
+        }
+
+    def _create_table(self, floor: FloorConfig) -> TableState:
+        rng = Random(self.floor_seed())
+        opponent_count = rng.randint(floor.opponent_count_min, floor.opponent_count_max)
+        opponent_stacks = [floor.player_starting_stack for _ in range(opponent_count)]
+        metadata = self._apply_floor_start_perks()
+        return TableState(
+            floor_number=floor.floor_number,
+            seed=self.floor_seed(),
+            player_stack=floor.player_starting_stack,
+            opponent_stacks=opponent_stacks,
+            small_blind=floor.blinds.small_blind,
+            big_blind=floor.blinds.big_blind,
+            pending_metadata=metadata,
+        )
+
+    def _reward_choices(self, floor: FloorConfig) -> list[str]:
+        count = floor.reward_choices_count
+        if self.effective_continues() >= 2:
+            count = max(1, count - 1)
+        rng = Random(derive_seed(self.seed, "reward", floor.floor_number))
+        available = [perk.perk_id for perk in PERK_DEFINITIONS]
+        rng.shuffle(available)
+        return available[:count]
+
+    def _use_continue_if_allowed(self, needed_bankroll: int, use_continue: bool) -> bool:
+        floor = self.current_floor
+        if not use_continue or floor.is_boss or self.continues >= MAX_CONTINUES:
+            return False
+        self.continues += 1
+        if self.bankroll < needed_bankroll:
+            self.bankroll = needed_bankroll
+        self._log("continue_used", continues=self.continues, bankroll=self.bankroll)
+        return True
+
+    def _consume_perks(self, timing: TriggerTiming) -> None:
+        kept: list[ActivePerk] = []
+        for perk in self.active_perks:
+            definition = get_perk(perk.perk_id)
+            if definition.trigger_timing == timing and perk.remaining_uses is not None:
+                perk.remaining_uses -= 1
+            if perk.remaining_uses is None or perk.remaining_uses > 0:
+                kept.append(perk)
+        self.active_perks = kept
+
+    def _apply_floor_start_perks(self) -> dict:
+        metadata: dict = {}
+        kept: list[ActivePerk] = []
+        for perk in self.active_perks:
+            definition = get_perk(perk.perk_id)
+            if definition.trigger_timing == TriggerTiming.NEXT_FLOOR_START:
+                result = definition.effect(PerkEffectContext(metadata=perk.metadata))
+                metadata.update(result.metadata)
+                if perk.remaining_uses is not None:
+                    perk.remaining_uses -= 1
+            if perk.remaining_uses is None or perk.remaining_uses > 0:
+                kept.append(perk)
+        self.active_perks = kept
+        return metadata
+
+    def _trigger_insurance(self, table_stack: int) -> int:
+        kept: list[ActivePerk] = []
+        recovered = 0
+        for perk in self.active_perks:
+            definition = get_perk(perk.perk_id)
+            if definition.trigger_timing == TriggerTiming.ALL_IN_LOSS and recovered == 0:
+                result = definition.effect(PerkEffectContext(table_stack=table_stack))
+                recovered = result.recovered_stack
+                if perk.remaining_uses is not None:
+                    perk.remaining_uses -= 1
+            if perk.remaining_uses is None or perk.remaining_uses > 0:
+                kept.append(perk)
+        self.active_perks = kept
+        return recovered
+
+    def _log(self, event: str, **payload: object) -> None:
+        self.event_log.append({"event": event, **payload})
+
+
+def derive_seed(run_seed: str, *parts: object) -> str:
+    payload = ":".join([run_seed, *(str(part) for part in parts)])
+    return sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def _normalize_seed(seed: int | str | bytes | None) -> str:
+    if seed is None:
+        return "default"
+    if isinstance(seed, bytes):
+        return seed.hex()
+    return str(seed)

telltale/game/engine.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from telltale.game.economy import RunState
+from telltale.game.holdem import ActionType, HandState, PlayerState
+
+
+class HoldemEngine:
+    def start_hand(
+        self,
+        players: list[PlayerState],
+        seed: int | str | bytes | None = None,
+        dealer_button_index: int = 0,
+        small_blind: int = 5,
+        big_blind: int = 10,
+    ) -> HandState:
+        return HandState.start(
+            players=players,
+            seed=seed,
+            dealer_button_index=dealer_button_index,
+            small_blind=small_blind,
+            big_blind=big_blind,
+        )
+
+    def legal_actions(self, hand: HandState, player_id: str | None = None) -> set[ActionType]:
+        return hand.legal_actions(player_id)
+
+    def apply_action(
+        self,
+        hand: HandState,
+        action: ActionType | str,
+        amount: int = 0,
+        player_id: str | None = None,
+    ) -> HandState:
+        hand.apply_action(action, amount=amount, player_id=player_id)
+        return hand
+
+    def start_run(self, seed: int | str | bytes | None = None, bankroll: int = 250) -> RunState:
+        return RunState.start(seed=seed, bankroll=bankroll)
+
+    def enter_floor(self, run: RunState, use_continue: bool = True) -> RunState:
+        run.enter_current_floor(use_continue=use_continue)
+        return run
+
+    def win_floor(self, run: RunState, ending_stack: int | None = None) -> RunState:
+        run.win_current_floor(ending_stack=ending_stack)
+        return run
+
+    def lose_floor(self, run: RunState, all_in_loss: bool = False) -> RunState:
+        run.lose_current_floor(all_in_loss=all_in_loss)
+        return run
+
+    def choose_reward(self, run: RunState, perk_id: str) -> RunState:
+        run.choose_reward(perk_id)
+        return run

telltale/game/floors.py

@@ -0,0 +1,112 @@
+"""
+This module defines the floors that can be played in the game.
+
+Floors are the different levels of the game.
+Each floor has a name, a buy-in, a starting stack, a number of opponents, and a number of rewards.
+The floors are ordered from level 1 to level 5 (inclusive).
+Level 5 is the final level and is the boss fight.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BlindStructure:
+    """
+    Defines the blind structure (the amount of chips that each player must 
+    post as the small blind and big blind) for a given floor.
+    """
+    small_blind: int
+    big_blind: int
+    # escalation interval is the number of hands that must pass before the blinds are increased.
+    # this is used to create a dynamic blind structure that increases over time. 
+    escalation_interval_hands: int = 0 
+
+
+@dataclass(frozen=True)
+class FloorConfig:
+    floor_number: int
+    name: str
+    buy_in: int
+    player_starting_stack: int # the number of chips the player starts with at the beginning of the floor
+    opponent_count_min: int
+    opponent_count_max: int
+    blinds: BlindStructure
+    win_target: int # the number of chips the player must have at the end of the floor to win the floor
+    reward_choices_count: int 
+    is_boss: bool = False
+
+    @property
+    def total_players_min(self) -> int:
+        return self.opponent_count_min + 1
+
+    @property
+    def total_players_max(self) -> int:
+        return self.opponent_count_max + 1
+
+
+FLOOR_CONFIGS: tuple[FloorConfig, ...] = (
+    FloorConfig(
+        floor_number=1,
+        name="Level 1 (Tutorial)",
+        buy_in=40,
+        player_starting_stack=100,
+        opponent_count_min=2,
+        opponent_count_max=2,
+        blinds=BlindStructure(small_blind=2, big_blind=4),
+        win_target=160,
+        reward_choices_count=3,
+    ),
+    FloorConfig(
+        floor_number=2,
+        name="Level 2",
+        buy_in=70,
+        player_starting_stack=140,
+        opponent_count_min=2,
+        opponent_count_max=3,
+        blinds=BlindStructure(small_blind=3, big_blind=6),
+        win_target=225,
+        reward_choices_count=3,
+    ),
+    FloorConfig(
+        floor_number=3,
+        name="Level 3",
+        buy_in=110,
+        player_starting_stack=180,
+        opponent_count_min=3,
+        opponent_count_max=3,
+        blinds=BlindStructure(small_blind=5, big_blind=10, escalation_interval_hands=8),
+        win_target=300,
+        reward_choices_count=3,
+    ),
+    FloorConfig(
+        floor_number=4,
+        name="Level 4",
+        buy_in=160,
+        player_starting_stack=230,
+        opponent_count_min=3,
+        opponent_count_max=4,
+        blinds=BlindStructure(small_blind=8, big_blind=16, escalation_interval_hands=6),
+        win_target=390,
+        reward_choices_count=3,
+    ),
+    FloorConfig(
+        floor_number=5,
+        name="Level 5 (Final)",
+        buy_in=240,
+        player_starting_stack=320,
+        opponent_count_min=4,
+        opponent_count_max=4,
+        blinds=BlindStructure(small_blind=12, big_blind=24, escalation_interval_hands=5),
+        win_target=560,
+        reward_choices_count=0,
+        is_boss=True,
+    ),
+)
+
+def get_floor_config(floor_index: int) -> FloorConfig:
+    if floor_index < 0 or floor_index >= len(FLOOR_CONFIGS):
+        raise ValueError(f"invalid floor index: {floor_index}")
+    return FLOOR_CONFIGS[floor_index]

telltale/game/holdem.py

@@ -0,0 +1,626 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from enum import Enum
+from itertools import combinations
+from uuid import uuid4
+
+from telltale.game.cards import Card, Deck
+
+
+class PokerError(ValueError):
+    """Raised when a poker action or state transition is invalid."""
+
+
+class Street(str, Enum):
+    """Defines the different stages of the poker game."""
+    PREFLOP = "preflop" 
+    FLOP = "flop"
+    TURN = "turn"
+    RIVER = "river"
+    SHOWDOWN = "showdown"
+    COMPLETE = "complete"
+
+
+class ActionType(str, Enum):
+    """Defines the different actions a player can take in the poker game."""
+    FOLD = "fold"
+    CHECK = "check"
+    CALL = "call"
+    BET = "bet"
+    RAISE = "raise"
+    ALL_IN = "all_in"
+
+
+@dataclass
+class PlayerState:
+    """Represents the state of a player in the poker game."""
+    player_id: str 
+    name: str
+    seat_index: int
+    stack: int # number of chips the player has available to bet
+    hole_cards: list[Card] = field(default_factory=list) # the cards the player has in their hand
+    current_bet: int = 0 # the amount of chips the player has bet in the current round
+    has_folded: bool = False
+    is_all_in: bool = False
+    is_human: bool = False
+
+
+@dataclass(frozen=True)
+class ActionRecord:
+    """Represents a record of an action taken by a player in the poker game."""
+    player_id: str
+    action: ActionType
+    amount: int
+    street: Street
+
+
+@dataclass(frozen=True)
+class Pot:
+    amount: int
+    eligible_player_ids: tuple[str, ...] # the ids of the players who are eligible to win the pot
+
+
+@dataclass
+class HandState:
+    hand_id: str 
+    deck: Deck
+    players: list[PlayerState]
+    dealer_button_index: int # note this is the index of the player who is the dealer, not the player id. 
+    small_blind_index: int 
+    big_blind_index: int
+    current_actor_index: int | None # the index of the player who is currently allowed to act
+    street: Street = Street.PREFLOP # the current street of the game
+    board_cards: list[Card] = field(default_factory=list) # the cards on the table
+    pot_contributions: dict[str, int] = field(default_factory=dict) # the amount of chips each player has contributed to the pot
+    minimum_call_amount: int = 0
+    minimum_raise_amount: int = 0
+    action_history: list[ActionRecord] = field(default_factory=list) # the history of actions taken by the players
+    street_acted_player_ids: set[str] = field(default_factory=set) # the ids of the players who have acted on the current street
+
+    @classmethod
+    def start(
+        cls,
+        players: list[PlayerState],
+        seed: int | str | bytes | None = None,
+        dealer_button_index: int = 0,
+        small_blind: int = 5,
+        big_blind: int = 10,
+        hand_id: str | None = None,
+    ) -> "HandState":
+        """Starts a new hand of poker."""
+        if len(players) < 2:
+            raise PokerError("at least two players are required") 
+        if small_blind < 0 or big_blind <= 0:
+            raise PokerError("blind amounts must be positive")
+
+        ordered = sorted(players, key=lambda player: player.seat_index)
+        deck = Deck.shuffled(seed)
+        dealer_pos = dealer_button_index % len(ordered)
+        small_blind_pos = _next_seat(ordered, dealer_pos)
+        # the index of the player in the players list who is the big blind
+        big_blind_pos = _next_seat(ordered, small_blind_pos) 
+        pot_contributions: dict[str, int] = {}
+        for player in ordered:
+            pot_contributions[player.player_id] = 0
+        hand = cls(
+            hand_id=hand_id or str(uuid4()),
+            deck=deck,
+            players=ordered,
+            dealer_button_index=dealer_pos,
+            small_blind_index=small_blind_pos,
+            big_blind_index=big_blind_pos,
+            current_actor_index=_next_seat(ordered, big_blind_pos),
+            pot_contributions=pot_contributions,
+            minimum_raise_amount=big_blind,
+        )
+        for _ in range(2):
+            for player in ordered:
+                player.hole_cards.append(deck.draw())
+        hand._post_blind(small_blind_pos, small_blind) # the small blind player posts the small blind amount
+        hand._post_blind(big_blind_pos, big_blind) # the big blind player posts the big blind amount
+        hand.minimum_call_amount = hand.current_max_bet()
+        hand._skip_unavailable_actor()
+        return hand
+
+    def legal_actions(self, player_id: str | None = None) -> set[ActionType]:
+        player = self._actor_or_player(player_id)
+        if self.street == Street.COMPLETE:
+            return set[ActionType]()
+        if player.has_folded or player.is_all_in or player.stack <= 0:
+            return set[ActionType]()
+
+        # the amount of chips the player needs to call to match the current maximum bet
+        outstanding = self.current_max_bet() - player.current_bet 
+        actions = {ActionType.ALL_IN}
+        # if the player has no outstanding amount to call, they can check or bet
+        if outstanding == 0:
+            actions.add(ActionType.CHECK)
+            # if the current maximum bet is 0, the player can bet
+            if self.current_max_bet() == 0:
+                actions.add(ActionType.BET)
+        else:
+            # if the player has an outstanding amount to call, they can fold or call
+            actions.update({ActionType.FOLD, ActionType.CALL})
+            # if the player has more chips than the outstanding amount, they can raise
+            if player.stack > outstanding:
+                actions.add(ActionType.RAISE)
+        return actions
+
+    def apply_action(self, action: ActionType | str, amount: int = 0, player_id: str | None = None) -> None:
+        if self.street == Street.COMPLETE:
+            raise PokerError("hand is already complete")
+        player = self._actor_or_player(player_id)
+        if player_id is not None and self.current_actor_index is not None:
+            actor = self.players[self.current_actor_index]
+            if actor.player_id != player_id:
+                raise PokerError(f"it is {actor.player_id}'s turn, not {player_id}")
+
+        action_type = ActionType(action) 
+        self._validate_action(player, action_type, amount)
+        paid = self._apply_payment(player, action_type, amount)
+        self.action_history.append(ActionRecord(player.player_id, action_type, paid, self.street))
+        self.street_acted_player_ids.add(player.player_id)
+
+        # if the action is a bet or a raise,
+        # OR (all-in AND player's current bet is greater than the min. call amount):
+        #   update the minimum call amount and minimum raise amount
+        if action_type in {ActionType.BET, ActionType.RAISE} or (
+            action_type == ActionType.ALL_IN and player.current_bet > self.minimum_call_amount
+        ):
+            previous_call = self.minimum_call_amount
+            self.minimum_call_amount = self.current_max_bet()
+            raise_size = self.minimum_call_amount - previous_call 
+            if raise_size >= self.minimum_raise_amount:
+                self.minimum_raise_amount = raise_size
+                self.street_acted_player_ids = {player.player_id}
+
+        self._settle_or_advance() 
+
+    def to_private_state(self) -> dict:
+        """Returns the private state of the hand. This is internal to the game and not visible to the viewer."""
+        board_cards = _card_strings(self.board_cards)
+        players = []
+        for player in self.players:
+            players.append(self._serialize_player(player, reveal_hole_cards=True))
+        action_history = []
+        for record in self.action_history:
+            action_history.append(_serialize_action_record(record))
+        return {
+            "hand_id": self.hand_id,
+            "street": self.street.value,
+            "deck": self.deck.to_strings(),
+            "board_cards": board_cards,
+            "players": players,
+            "pot_contributions": dict(self.pot_contributions),
+            "current_actor_index": self.current_actor_index,
+            "action_history": action_history,
+        }
+
+    def to_public_state(self, viewer_player_id: str) -> dict:
+        """Returns the public state of the hand. This is what is visble to the viewer."""
+        # if the street is showdown or complete, the hole cards are visible to the viewer
+        showdown_visible = self.street in {Street.SHOWDOWN, Street.COMPLETE}
+        board_cards = _card_strings(self.board_cards)
+        players = []
+        for player in self.players:
+            reveal_hole_cards = showdown_visible or player.player_id == viewer_player_id
+            players.append(self._serialize_player(player, reveal_hole_cards=reveal_hole_cards))
+        legal_actions = []
+        for action in sorted(self.legal_actions(viewer_player_id), key=lambda item: item.value):
+            legal_actions.append(action.value)
+        action_history = []
+        for record in self.action_history:
+            action_history.append(_serialize_action_record(record))
+        return {
+            "hand_id": self.hand_id,
+            "street": self.street.value,
+            "board_cards": board_cards,
+            "players": players,
+            "pot_contributions": dict(self.pot_contributions),
+            "current_actor_index": self.current_actor_index,
+            "legal_actions": legal_actions,
+            "action_history": action_history,
+        }
+
+    def _validate_action(self, player: PlayerState, action: ActionType, amount: int) -> None:
+        """Validates the action taken by the player."""
+        if player.has_folded:
+            raise PokerError("folded players cannot act")
+        if player.is_all_in:
+            raise PokerError("all-in players cannot act")
+        if player.stack <= 0:
+            raise PokerError("players with no chips cannot act")
+        if action not in self.legal_actions(player.player_id):
+            raise PokerError(f"{action.value} is not legal for player {player.player_id}")
+        if amount < 0:
+            raise PokerError("action amount cannot be negative")
+
+        outstanding = self.current_max_bet() - player.current_bet
+        if action == ActionType.BET:
+            if amount <= 0:
+                raise PokerError("bet amount must be positive")
+            if amount > player.stack:
+                raise PokerError("bet amount exceeds stack")
+            if amount < self.minimum_raise_amount and amount < player.stack:
+                raise PokerError("bet amount is below the minimum bet")
+        elif action == ActionType.RAISE:
+            target = player.current_bet + amount
+            minimum_target = self.current_max_bet() + self.minimum_raise_amount
+            if amount <= outstanding:
+                raise PokerError("raise amount must exceed the call amount")
+            if amount > player.stack:
+                raise PokerError("raise amount exceeds stack")
+            if target < minimum_target and amount < player.stack:
+                raise PokerError("raise amount is below the minimum raise")
+
+    def _apply_payment(self, player: PlayerState, action: ActionType, amount: int) -> int:
+        """
+        Applies the payment for the action taken by the player.
+        Returns the amount of chips paid by the player.
+        """
+        paid = 0
+        if action == ActionType.FOLD:
+            player.has_folded = True
+        elif action == ActionType.CHECK:
+            paid = 0
+        elif action == ActionType.CALL:
+            # current max bet - player's current bet = the amount of chips the player needs to call to match the current maximum bet
+            paid = self._pay(player, min(player.stack, self.current_max_bet() - player.current_bet))
+        elif action in {ActionType.BET, ActionType.RAISE}:
+            paid = self._pay(player, amount)
+        elif action == ActionType.ALL_IN:
+            paid = self._pay(player, player.stack)
+        return paid
+
+    def _pay(self, player: PlayerState, amount: int) -> int:
+        """Pays the player the specified amount of chips."""
+        paid = min(amount, player.stack)
+        player.stack -= paid
+        player.current_bet += paid
+        self.pot_contributions[player.player_id] += paid
+        if player.stack == 0:
+            player.is_all_in = True
+        return paid
+
+    def _post_blind(self, player_index: int, amount: int) -> None:
+        """Posts the blind for the player at the specified index."""
+        player = self.players[player_index]
+        self._pay(player, amount)
+
+    def _settle_or_advance(self) -> None:
+        """Setstles the pot or advances the street."""
+        active = _players_not_folded(self.players)
+        # if there is only one active player, award the pot to them
+        if len(active) == 1:
+            self._award_uncontested(active[0])
+            return
+
+        # if all remaining players are all-in, showdown
+        if self._all_remaining_all_in():
+            self._deal_remaining_board() # deal the remaining board cards
+            self._showdown() # showdown
+            return
+
+        if self._street_is_complete():
+            self._advance_street() # advance the street
+        else:
+            self.current_actor_index = self._next_actionable_index(self.current_actor_index) # set the current actor index to the next actionable index
+
+    def _advance_street(self) -> None:
+        """Advances the street."""
+        for player in self.players:
+            player.current_bet = 0
+        self.street_acted_player_ids.clear()
+        self.minimum_call_amount = 0 # reset the minimum call amount
+
+        if self.street == Street.PREFLOP:
+            self.street = Street.FLOP 
+            self._burn()
+            self.board_cards.extend(self.deck.draw(3))
+        elif self.street == Street.FLOP:
+            self.street = Street.TURN
+            self._burn()
+            self.board_cards.append(self.deck.draw())
+        elif self.street == Street.TURN:
+            self.street = Street.RIVER
+            self._burn()
+            self.board_cards.append(self.deck.draw())
+        elif self.street == Street.RIVER:
+            self._showdown()
+            return
+
+        self.current_actor_index = self._next_actionable_index(self.dealer_button_index) # set the current actor index to the next actionable index
+        if self.current_actor_index is None:
+            self._deal_remaining_board()
+            self._showdown()
+
+    def _showdown(self) -> None:
+        """
+        Shows down the hand.
+
+        We will build the side pots. Each side pot will be a Pot(amount, eligible_player_ids).
+        For all pots, we will find the winners and award the pot to them.
+        """
+        self.street = Street.SHOWDOWN # set the street to the showdown
+        for pot in build_side_pots(self.pot_contributions, self.players):
+            winners = self._best_players(pot.eligible_player_ids)
+            share, remainder = divmod(pot.amount, len(winners))
+            for player in winners:
+                player.stack += share
+            for player in self._clockwise_players_from_dealer(winners)[:remainder]:
+                player.stack += 1
+        self.street = Street.COMPLETE
+        self.current_actor_index = None
+
+    def _award_uncontested(self, winner: PlayerState) -> None:
+        """Awards the pot to the winner."""
+        winner.stack += sum(self.pot_contributions.values())
+        self.street = Street.COMPLETE
+        self.current_actor_index = None
+
+    def _deal_remaining_board(self) -> None:
+        while len(self.board_cards) < 5:
+            self._burn()
+            draw_count = 3 if len(self.board_cards) == 0 else 1
+            drawn = self.deck.draw(draw_count)
+            self.board_cards.extend(drawn if isinstance(drawn, list) else [drawn])
+
+    def _street_is_complete(self) -> bool:
+        actionable = _actionable_players(self.players)
+        if len(actionable) <= 1:
+            return True
+        max_bet = self.current_max_bet()
+        for player in actionable:
+            if player.current_bet != max_bet:
+                return False
+            if player.player_id not in self.street_acted_player_ids:
+                return False
+        return True
+
+    def _all_remaining_all_in(self) -> bool:
+        active = _players_not_folded(self.players)
+        if len(active) <= 1:
+            return False
+        for player in active:
+            if not player.is_all_in:
+                return False
+        return True
+
+    def _next_actionable_index(self, start_index: int | None) -> int | None:
+        if start_index is None:
+            return None
+        for offset in range(1, len(self.players) + 1):
+            index = (start_index + offset) % len(self.players)
+            player = self.players[index]
+            if not player.has_folded and not player.is_all_in and player.stack > 0:
+                return index
+        return None
+
+    def _skip_unavailable_actor(self) -> None:
+        if self.current_actor_index is None:
+            return
+        actor = self.players[self.current_actor_index]
+        if actor.has_folded or actor.is_all_in or actor.stack <= 0:
+            self.current_actor_index = self._next_actionable_index(self.current_actor_index)
+
+    def _actor_or_player(self, player_id: str | None) -> PlayerState:
+        """
+        Gets the player state for the given player id.
+        If the player id is None, it returns the player state for the current actor.
+        If the player id is not None, it returns the player state for the given player id.
+        """
+        if player_id is None:
+            if self.current_actor_index is None:
+                raise PokerError("there is no current actor")
+            else:
+                return self.players[self.current_actor_index]
+        return self._player_by_id(player_id)
+
+    def _player_by_id(self, player_id: str) -> PlayerState:
+        """Returns the player state for the given player id."""
+        for player in self.players:
+            if player.player_id == player_id:
+                return player
+        raise PokerError(f"unknown player id: {player_id}")
+
+    def _serialize_player(self, player: PlayerState, reveal_hole_cards: bool) -> dict:
+        hole_cards: list[str] = []
+        if reveal_hole_cards:
+            hole_cards = _card_strings(player.hole_cards)
+        return {
+            "player_id": player.player_id,
+            "name": player.name,
+            "seat_index": player.seat_index,
+            "stack": player.stack,
+            "hole_cards": hole_cards,
+            "current_bet": player.current_bet,
+            "has_folded": player.has_folded,
+            "is_all_in": player.is_all_in,
+            "is_human": player.is_human,
+        }
+
+    def _burn(self) -> None:
+        self.deck.draw()
+
+    def current_max_bet(self) -> int:
+        max_bet = 0
+        for player in self.players:
+            if player.current_bet > max_bet:
+                max_bet = player.current_bet
+        return max_bet
+
+    def _clockwise_players_from_dealer(self, players: list[PlayerState]) -> list[PlayerState]:
+        """Returns the players in the clockwise order from the dealer."""
+        ids: set[str] = set()
+        for player in players:
+            ids.add(player.player_id)
+        ordered = []
+        for offset in range(1, len(self.players) + 1):
+            player = self.players[(self.dealer_button_index + offset) % len(self.players)]
+            if player.player_id in ids:
+                ordered.append(player)
+        return ordered
+
+    def _best_players(self, eligible_player_ids: tuple[str, ...]) -> list[PlayerState]:
+        """Returns all eligible players tied for the best hand on the current board."""
+        best_rank: tuple[int, ...] | None = None
+        winners: list[PlayerState] = []
+        for player in self.players:
+            if player.player_id not in eligible_player_ids:
+                continue
+            rank = evaluate_7(player.hole_cards + self.board_cards)
+            if best_rank is None or rank > best_rank:
+                best_rank = rank
+                winners = [player]
+            elif rank == best_rank:
+                winners.append(player)
+        return winners
+
+
+def evaluate_7(cards: list[Card]) -> tuple[int, ...]:
+    """Returns the best five-card Hold'em rank from seven cards."""
+    best_rank: tuple[int, ...] | None = None
+    for hand in combinations(cards, 5):
+        rank = evaluate_5(list(hand))
+        if best_rank is None or rank > best_rank:
+            best_rank = rank
+    if best_rank is None:
+        raise PokerError("evaluate_7 requires at least seven cards")
+    return best_rank
+
+def evaluate_5(cards: list[Card]) -> tuple[int, ...]:
+    """
+    Returns the best five-card Hold'em rank from five cards.    
+    """
+    values: list[int] = [] # for all cards, convert the rank to value
+    for card in cards:
+        values.append(_rank_value(card.rank))
+    values.sort(reverse=True) # sort the values in descending order
+
+    suits: set[str] = set() # get the suits of the cards
+    for card in cards:
+        suits.add(card.suit)
+    is_flush = len(suits) == 1 # check if the cards are a flush. 
+
+    unique_values = sorted(set(values), reverse=True) # get the unique values of the cards
+    is_straight = False
+    straight_high = 0
+    if len(unique_values) == 5:
+        if unique_values[0] - unique_values[4] == 4:
+            is_straight = True
+            straight_high = unique_values[0]
+        elif unique_values == [14, 5, 4, 3, 2]:
+            is_straight = True
+            straight_high = 5
+
+    counts = Counter()
+    for card in cards:
+        counts[_rank_value(card.rank)] += 1
+    by_count = sorted(counts.items(), key=lambda item: (item[1], item[0]), reverse=True)
+
+    if is_straight and is_flush:
+        return (8, straight_high)
+    if by_count[0][1] == 4:
+        return (7, by_count[0][0], by_count[1][0])
+    if by_count[0][1] == 3 and by_count[1][1] == 2:
+        return (6, by_count[0][0], by_count[1][0])
+    if is_flush:
+        return (5, *values)
+    if is_straight:
+        return (4, straight_high)
+    if by_count[0][1] == 3:
+        kickers = _ranks_with_count_other_than(counts, 3)
+        return (3, by_count[0][0], *kickers)
+    if by_count[0][1] == 2 and by_count[1][1] == 2:
+        high_pair, low_pair = sorted((by_count[0][0], by_count[1][0]), reverse=True)
+        return (2, high_pair, low_pair, by_count[2][0])
+    if by_count[0][1] == 2:
+        kickers = _ranks_with_count_other_than(counts, 2)
+        return (1, by_count[0][0], *kickers)
+    return (0, *values)
+
+
+def _rank_value(rank: str) -> int:
+    """Returns the value of a rank in the game of poker.
+    For example, the value of "2" is 2, the value of "T" is 10, the value of "J" is 11, etc.
+    """
+    return "23456789TJQKA".index(rank) + 2
+
+
+def _card_strings(cards: list[Card]) -> list[str]:
+    strings: list[str] = []
+    for card in cards:
+        strings.append(str(card))
+    return strings
+
+
+def _serialize_action_record(record: ActionRecord) -> dict:
+    return record.__dict__ | {"action": record.action.value, "street": record.street.value}
+
+
+def _players_not_folded(players: list[PlayerState]) -> list[PlayerState]:
+    active: list[PlayerState] = []
+    for player in players:
+        if not player.has_folded:
+            active.append(player)
+    return active
+
+
+def _actionable_players(players: list[PlayerState]) -> list[PlayerState]:
+    actionable: list[PlayerState] = []
+    for player in players:
+        if not player.has_folded and not player.is_all_in:
+            actionable.append(player)
+    return actionable
+
+
+def _ranks_with_count_other_than(counts: Counter, excluded_count: int) -> list[int]:
+    ranks: list[int] = []
+    for rank, count in counts.items():
+        if count != excluded_count:
+            ranks.append(rank)
+    ranks.sort(reverse=True)
+    return ranks
+
+
+def build_side_pots(contributions: dict[str, int], players: list[PlayerState]) -> list[Pot]:
+    """
+    Builds the side pots for the hands.
+
+    Side pots are built when a player goes all-in and there are other players who have not folded.
+    For example, if Alice puts in 50 chips all-in, Bob puts in 200, and Carol puts in 200, Alice 
+    can only win 150 (50x3); Bob and Carol contest the remaining 300 between themselves.
+    """
+    levels: set[int] = set()
+    for amount in contributions.values():
+        if amount > 0:
+            levels.add(amount)
+    levels = sorted(levels)
+    pots: list[Pot] = []
+    previous = 0
+    for level in levels:
+        contributors: list[PlayerState] = []
+        for player in players:
+            if contributions[player.player_id] >= level:
+                contributors.append(player)
+        amount = (level - previous) * len(contributors)
+        eligible_ids: list[str] = []
+        for player in contributors:
+            if not player.has_folded:
+                eligible_ids.append(player.player_id)
+        eligible = tuple(eligible_ids)
+        if amount > 0 and eligible:
+            pots.append(Pot(amount=amount, eligible_player_ids=eligible))
+        previous = level
+    return pots
+
+
+def _next_seat(players: list[PlayerState], start_index: int) -> int:
+    """
+    Returns the index of the next player in the list of players. 
+    This is a circular list, so if the start_index is the last player, 
+    the next player is the first player.
+    """
+    return (start_index + 1) % len(players)

telltale/game/perks.py

@@ -0,0 +1,178 @@
+"""
+This module defines the perks that can be used by the player in the game.
+
+Perks are effects that can be applied to the player's game state.
+They are triggered by certain events in the game and can have a variety of effects.
+
+The perks defined here are:
+- Buy-In Discount: The next floor buy-in is reduced by 15%.
+- Continue Waiver: One used continue is waived for buy-in penalty calculations.
+- Spotlight Seat: Act last on the first hand of the next floor when permitted.
+- Stack Recovery: Recover 20% of the table stack once after an all-in loss.
+
+You can get these perks by winning floors. When you win a floor, you are rewarded with a random perk.
+
+Perks are defined by a trigger timing, which determines when the perk is triggered,
+and an effect, which is a function that is called when the perk is triggered.
+
+The perk can be triggered at the following times:
+- Next floor buy-in: The perk is triggered when the player buys in for the next floor.
+- Continue penalty: The perk is triggered when the player uses a continue.
+- Next floor start: The perk is triggered when the player starts the next floor.
+- All-in loss: The perk is triggered when the player loses an all-in.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+
+class TriggerTiming(str, Enum):
+    NEXT_FLOOR_BUY_IN = "next_floor_buy_in"
+    CONTINUE_PENALTY = "continue_penalty"
+    NEXT_FLOOR_START = "next_floor_start"
+    ALL_IN_LOSS = "all_in_loss"
+
+
+@dataclass(frozen=True)
+class PerkEffectContext:
+    amount: int = 0
+    continues: int = 0
+    table_stack: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PerkEffectResult:
+    amount: int | None = None
+    continues: int | None = None
+    recovered_stack: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    consumed: bool = False
+
+# define a type alias for the effect function
+EffectFunction = Callable[[PerkEffectContext], PerkEffectResult] 
+
+@dataclass(frozen=True)
+class PerkDefinition:
+    perk_id: str
+    name: str
+    description: str
+    trigger_timing: TriggerTiming
+    effect: EffectFunction
+    max_uses: int | None = None
+    active_duration_floors: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def serialize(self) -> dict[str, Any]:
+        return {
+            "perk_id": self.perk_id,
+            "name": self.name,
+            "description": self.description,
+            "trigger_timing": self.trigger_timing.value,
+            "max_uses": self.max_uses,
+            "active_duration_floors": self.active_duration_floors,
+            "metadata": dict(self.metadata),
+        }
+
+
+@dataclass
+class ActivePerk:
+    perk_id: str
+    remaining_uses: int | None = None
+    remaining_floors: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_definition(cls, definition: PerkDefinition) -> "ActivePerk":
+        return cls(
+            perk_id=definition.perk_id,
+            remaining_uses=definition.max_uses,
+            remaining_floors=definition.active_duration_floors,
+            metadata=dict(definition.metadata),
+        )
+
+    def serialize(self) -> dict[str, Any]:
+        definition = get_perk(self.perk_id)
+        return definition.serialize() | {
+            "remaining_uses": self.remaining_uses,
+            "remaining_floors": self.remaining_floors,
+            "metadata": dict(self.metadata),
+        }
+
+
+def _buy_in_discount_effect(context: PerkEffectContext) -> PerkEffectResult:
+    return PerkEffectResult(amount=max(0, round(context.amount * 0.85)), consumed=True)
+
+
+def _continue_waiver_effect(context: PerkEffectContext) -> PerkEffectResult:
+    return PerkEffectResult(continues=max(0, context.continues - 1))
+
+
+def _spotlight_seat_effect(context: PerkEffectContext) -> PerkEffectResult:
+    return PerkEffectResult(metadata={"player_acts_last_first_hand": True}, consumed=True)
+
+
+def _stack_recovery_effect(context: PerkEffectContext) -> PerkEffectResult:
+    return PerkEffectResult(recovered_stack=max(0, context.table_stack // 5), consumed=True)
+
+
+PERK_DEFINITIONS: tuple[PerkDefinition, ...] = (
+    PerkDefinition(
+        perk_id="buy_in_discount",
+        name="Buy-In Discount",
+        description="Next floor buy-in reduced by 15%.",
+        trigger_timing=TriggerTiming.NEXT_FLOOR_BUY_IN,
+        effect=_buy_in_discount_effect,
+        max_uses=1,
+    ),
+    PerkDefinition(
+        perk_id="continue_waiver",
+        name="Continue Waiver",
+        description="One used continue is waived for buy-in penalty calculations.",
+        trigger_timing=TriggerTiming.CONTINUE_PENALTY,
+        effect=_continue_waiver_effect, 
+        # there is no max uses for this perk because it is only used once per continue
+        # and it is only triggered when the player uses a continue
+        # so it is not possible to use it more than once
+    ),
+    PerkDefinition(
+        perk_id="spotlight_seat",
+        name="Spotlight Seat",
+        description="Act last on the first hand of the next floor when permitted.",
+        trigger_timing=TriggerTiming.NEXT_FLOOR_START,
+        effect=_spotlight_seat_effect,
+        max_uses=1,
+    ),
+    PerkDefinition(
+        perk_id="stack_recovery",
+        name="Stack Recovery",
+        description="Recover 20% of your table stack once after an all-in loss.",
+        trigger_timing=TriggerTiming.ALL_IN_LOSS,
+        effect=_stack_recovery_effect,
+        max_uses=1,
+    ),
+)
+
+def get_perk(perk_id: str) -> PerkDefinition:
+    for perk in PERK_DEFINITIONS:
+        if perk.perk_id == perk_id:
+            return perk
+    raise ValueError(f"unknown perk id: {perk_id}")
+
+
+def apply_buy_in_discount(amount: int) -> int:
+    return _buy_in_discount_effect(PerkEffectContext(amount=amount)).amount or 0
+
+
+def apply_continue_waiver(continues: int) -> int:
+    result = _continue_waiver_effect(PerkEffectContext(continues=continues))
+    return result.continues if result.continues is not None else continues
+
+def trigger_stack_recovery(table_stack: int, already_used: bool = False) -> tuple[int, bool]:
+    if already_used:
+        return 0, True
+    result = _stack_recovery_effect(PerkEffectContext(table_stack=table_stack))
+    return result.recovered_stack, result.consumed

telltale/models/__init__.py

@@ -0,0 +1,9 @@
+"""Local model, speech, and transcription runtimes for Telltale."""
+
+from telltale.models.llama_runtime import (
+    DEFAULT_NEMOTRON_MODEL_NAME,
+    LocalTextRuntime,
+    RuntimeSettings,
+)
+
+__all__ = ["DEFAULT_NEMOTRON_MODEL_NAME", "LocalTextRuntime", "RuntimeSettings"]

telltale/models/eval_cli.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Iterable
+
+from telltale.models.eval_prompts import (
+    COMPARISON_MODEL_CANDIDATES,
+    DEFAULT_MODEL_CANDIDATES,
+    EVAL_CASES_BY_ID,
+    MODEL_CANDIDATES_BY_LABEL,
+    AgentEvalCase,
+    ModelCandidate,
+    get_eval_case,
+    load_candidates_from_json,
+)
+from telltale.models.eval_runner import (
+    EvalRunConfig,
+    build_runtime_for_candidate,
+    evaluate_candidate,
+    write_eval_bundle,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    candidates = _candidate_pool(args.candidate_file)
+    if args.list_candidates:
+        _print_candidates(candidates)
+        return 0
+    if args.list_cases:
+        _print_cases(EVAL_CASES_BY_ID.values())
+        return 0
+
+    selected_candidates = _select_candidates(candidates, args.candidate)
+    selected_cases = _select_cases(args.case, args.case_set, args.max_cases)
+    profile_defaults = _profile_defaults(args.profile)
+    config = EvalRunConfig(
+        max_tokens=args.max_tokens if args.max_tokens is not None else profile_defaults["max_tokens"],
+        context_size=args.context_size,
+        temperature=args.temperature if args.temperature is not None else profile_defaults["temperature"],
+        seed=args.seed,
+        output_dir=args.output_dir,
+        hardware_profile=args.hardware_profile,
+        server_url=args.server_url,
+        n_gpu_layers=args.n_gpu_layers,
+        speech_max_words=args.speech_max_words
+        if args.speech_max_words is not None
+        else profile_defaults["speech_max_words"],
+        rationale_max_words=args.rationale_max_words
+        if args.rationale_max_words is not None
+        else profile_defaults["rationale_max_words"],
+    )
+
+    results_by_candidate = {}
+    for candidate in selected_candidates:
+        model_path = _model_path_for_candidate(candidate, args.model_path)
+        runtime = build_runtime_for_candidate(candidate, config, model_path=model_path)
+        results_by_candidate[candidate.label] = evaluate_candidate(
+            candidate,
+            runtime,
+            cases=selected_cases,
+            config=config,
+        )
+
+    bundle = write_eval_bundle(results_by_candidate, output_dir=args.output_dir)
+    print(json.dumps(bundle, ensure_ascii=True, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Evaluate GGUF models on Telltale agent prompts.")
+    parser.add_argument(
+        "--candidate",
+        action="append",
+        help="Candidate label to evaluate. Repeat for multiple. Defaults to built-in defaults.",
+    )
+    parser.add_argument(
+        "--candidate-file",
+        help="JSON list/object of extra candidates with label, hf_repo_id, and gguf_filename.",
+    )
+    parser.add_argument(
+        "--case",
+        action="append",
+        help="Eval case id to run. Repeat for multiple.",
+    )
+    parser.add_argument(
+        "--case-set",
+        choices=["smoke"],
+        default="smoke",
+        help="Named case set to run when --case is omitted.",
+    )
+    parser.add_argument("--max-cases", type=int, default=None, help="Cap selected cases for budget control.")
+    parser.add_argument("--model-path", action="append", help="Map candidate to local GGUF: label=/path/model.gguf.")
+    parser.add_argument("--output-dir", default="runs/model_evals", help="Directory for JSONL and summary artifacts.")
+    parser.add_argument("--profile", choices=["default", "nemotron"], default="default")
+    parser.add_argument("--max-tokens", type=int, default=None)
+    parser.add_argument("--context-size", type=int, default=2048)
+    parser.add_argument("--temperature", type=float, default=None)
+    parser.add_argument("--speech-max-words", type=int, default=None)
+    parser.add_argument("--rationale-max-words", type=int, default=None)
+    parser.add_argument("--seed", type=int, default=17)
+    parser.add_argument("--hardware-profile", default="local")
+    parser.add_argument("--server-url", default="http://127.0.0.1:8080")
+    parser.add_argument("--n-gpu-layers", type=int, default=0)
+    parser.add_argument("--list-candidates", action="store_true")
+    parser.add_argument("--list-cases", action="store_true")
+    return parser
+
+
+def _profile_defaults(profile: str) -> dict[str, float | int]:
+    if profile == "nemotron":
+        return {
+            "max_tokens": 520,
+            "temperature": 0.55,
+            "speech_max_words": 36,
+            "rationale_max_words": 44,
+        }
+    return {
+        "max_tokens": 320,
+        "temperature": 0.30,
+        "speech_max_words": 16,
+        "rationale_max_words": 24,
+    }
+
+
+def _candidate_pool(candidate_file: str | None) -> dict[str, ModelCandidate]:
+    candidates = dict(MODEL_CANDIDATES_BY_LABEL)
+    if candidate_file:
+        for candidate in load_candidates_from_json(candidate_file):
+            candidates[candidate.label] = candidate
+    return candidates
+
+
+def _select_candidates(
+    candidates: dict[str, ModelCandidate],
+    labels: list[str] | None,
+) -> tuple[ModelCandidate, ...]:
+    if not labels:
+        return DEFAULT_MODEL_CANDIDATES
+    if "all" in labels:
+        return COMPARISON_MODEL_CANDIDATES
+    selected = []
+    for label in labels:
+        if label not in candidates:
+            known = ", ".join(sorted(candidates))
+            raise SystemExit(f"unknown candidate {label!r}; known candidates: {known}")
+        selected.append(candidates[label])
+    return tuple(selected)
+
+
+def _select_cases(
+    case_ids: list[str] | None,
+    case_set: str,
+    max_cases: int | None,
+) -> tuple[AgentEvalCase, ...]:
+    if case_ids:
+        cases = tuple(get_eval_case(case_id) for case_id in case_ids)
+    elif case_set == "smoke":
+        cases = tuple(EVAL_CASES_BY_ID.values())
+    else:
+        raise SystemExit(f"unknown case set: {case_set}")
+    if max_cases is not None:
+        if max_cases <= 0:
+            raise SystemExit("--max-cases must be positive")
+        cases = cases[:max_cases]
+    return cases
+
+
+def _model_path_for_candidate(candidate: ModelCandidate, model_path_args: list[str] | None) -> str | None:
+    paths = _parse_model_paths(model_path_args or [])
+    return paths.get(candidate.label)
+
+
+def _parse_model_paths(values: Iterable[str]) -> dict[str, str]:
+    paths: dict[str, str] = {}
+    for value in values:
+        if "=" not in value:
+            raise SystemExit("--model-path must use label=/path/model.gguf")
+        label, path = value.split("=", 1)
+        if not label or not path:
+            raise SystemExit("--model-path must use label=/path/model.gguf")
+        if not Path(path).exists():
+            raise SystemExit(f"local GGUF path does not exist for {label}: {path}")
+        paths[label] = path
+    return paths
+
+
+def _print_candidates(candidates: dict[str, ModelCandidate]) -> None:
+    for candidate in sorted(candidates.values(), key=lambda item: item.label):
+        print(
+            json.dumps(
+                {
+                    "label": candidate.label,
+                    "hf_repo_id": candidate.hf_repo_id,
+                    "gguf_filename": candidate.gguf_filename,
+                    "quantization": candidate.quantization,
+                },
+                ensure_ascii=True,
+            )
+        )
+
+
+def _print_cases(cases: Iterable[AgentEvalCase]) -> None:
+    for case in cases:
+        print(
+            json.dumps(
+                {
+                    "case_id": case.case_id,
+                    "agent_id": case.agent_id,
+                    "legal_actions": [action.value for action in case.legal_actions],
+                    "expected_pressure": case.expected_pressure,
+                },
+                ensure_ascii=True,
+            )
+        )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

telltale/models/eval_prompts.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from telltale.agents.dialogue import PlayerUtterance
+from telltale.agents.memory import AgentMemory
+from telltale.agents.profiles import get_agent_profile
+from telltale.agents.prompts import build_agent_prompt
+from telltale.game.holdem import ActionType
+from telltale.poker.policy import PokerDecision
+
+
+@dataclass(frozen=True)
+class ModelCandidate:
+    label: str
+    hf_repo_id: str
+    gguf_filename: str
+    quantization: str
+
+    @classmethod
+    def from_mapping(cls, data: dict[str, Any]) -> "ModelCandidate":
+        return cls(
+            label=str(data["label"]),
+            hf_repo_id=str(data["hf_repo_id"]),
+            gguf_filename=str(data["gguf_filename"]),
+            quantization=str(data.get("quantization") or ""),
+        )
+
+
+@dataclass(frozen=True)
+class AgentEvalCase:
+    case_id: str
+    agent_id: str
+    memory_summary: str
+    public_state: dict[str, Any]
+    private_agent_state: dict[str, Any]
+    solver_recommendation: PokerDecision
+    player_utterance: PlayerUtterance | None
+    legal_actions: tuple[ActionType, ...]
+    expected_pressure: str
+
+    def build_prompt(self, *, speech_max_words: int = 28, rationale_max_words: int = 36) -> str:
+        profile = get_agent_profile(self.agent_id)
+        memory = AgentMemory.neutral(self.agent_id)
+        memory.summary = self.memory_summary
+        return build_agent_prompt(
+            profile,
+            memory,
+            self.public_state,
+            self.private_agent_state,
+            self.solver_recommendation,
+            self.player_utterance,
+            self.legal_actions,
+            speech_max_words=speech_max_words,
+            rationale_max_words=rationale_max_words,
+        )
+
+
+NEMOTRON_3_NANO_4B_Q4_K_M = ModelCandidate(
+    label="nemotron_3_nano_4b_q4_k_m",
+    hf_repo_id="nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
+    gguf_filename="NVIDIA-Nemotron3-Nano-4B-Q4_K_M.gguf",
+    quantization="Q4_K_M",
+)
+
+QWEN3_4B_Q4_K_M = ModelCandidate(
+    label="qwen3_4b_q4_k_m",
+    hf_repo_id="Qwen/Qwen3-4B-GGUF",
+    gguf_filename="Qwen3-4B-Q4_K_M.gguf",
+    quantization="Q4_K_M",
+)
+
+MINICPM41_8B_Q4_K_M = ModelCandidate(
+    label="minicpm41_8b_q4_k_m",
+    hf_repo_id="openbmb/MiniCPM4.1-8B-GGUF",
+    gguf_filename="MiniCPM4.1-8B-Q4_K_M.gguf",
+    quantization="Q4_K_M",
+)
+
+QWEN3_8B_Q4_K_M = ModelCandidate(
+    label="qwen3_8b_q4_k_m",
+    hf_repo_id="Qwen/Qwen3-8B-GGUF",
+    gguf_filename="Qwen3-8B-Q4_K_M.gguf",
+    quantization="Q4_K_M",
+)
+
+
+DEFAULT_MODEL_CANDIDATES: tuple[ModelCandidate, ...] = (NEMOTRON_3_NANO_4B_Q4_K_M,)
+COMPARISON_MODEL_CANDIDATES: tuple[ModelCandidate, ...] = (
+    NEMOTRON_3_NANO_4B_Q4_K_M,
+    QWEN3_4B_Q4_K_M,
+    MINICPM41_8B_Q4_K_M,
+    QWEN3_8B_Q4_K_M,
+)
+MODEL_CANDIDATES_BY_LABEL: dict[str, ModelCandidate] = {
+    candidate.label: candidate for candidate in COMPARISON_MODEL_CANDIDATES
+}
+
+
+SMOKE_EVAL_CASES: tuple[AgentEvalCase, ...] = (
+    AgentEvalCase(
+        case_id="worm_needle_facing_call",
+        agent_id="worm",
+        memory_summary="Player needled Worm after winning a small pot and Worm has been talking faster since.",
+        public_state={
+            "street": "turn",
+            "board_cards": ["Ah", "7d", "7s", "2c"],
+            "pot": 140,
+            "amount_to_call": 45,
+            "stacks": {"player": 310, "worm": 220},
+            "recent_actions": ["player bet 45 into 140"],
+        },
+        private_agent_state={
+            "hole_cards": ["Ks", "Qs"],
+            "stack": 220,
+            "position": "button",
+        },
+        solver_recommendation=PokerDecision(
+            ActionType.FOLD,
+            amount=0,
+            equity=0.18,
+            pot_odds=0.24,
+            reason="equity trails pot odds and paired ace board favors the bettor",
+        ),
+        player_utterance=PlayerUtterance("You always pay me off when you're tilted.", target_agent_id="worm"),
+        legal_actions=(ActionType.FOLD, ActionType.CALL, ActionType.RAISE, ActionType.ALL_IN),
+        expected_pressure="Tests whether table talk can tempt a volatile agent without breaking legality.",
+    ),
+    AgentEvalCase(
+        case_id="molly_bluff_catcher",
+        agent_id="molly_bloom",
+        memory_summary="Player has shown one river bluff and one disciplined fold this floor.",
+        public_state={
+            "street": "river",
+            "board_cards": ["Kh", "Jd", "8d", "3s", "2c"],
+            "pot": 260,
+            "amount_to_call": 80,
+            "stacks": {"player": 520, "molly": 430},
+            "recent_actions": ["player bet 80 into 260"],
+        },
+        private_agent_state={
+            "hole_cards": ["Kc", "Tc"],
+            "stack": 430,
+            "position": "field",
+        },
+        solver_recommendation=PokerDecision(
+            ActionType.CALL,
+            amount=0,
+            equity=0.46,
+            pot_odds=0.235,
+            reason="top pair has enough showdown value for this price",
+        ),
+        player_utterance=PlayerUtterance("You know I would not fire river without it.", target_agent_id="molly_bloom"),
+        legal_actions=(ActionType.FOLD, ActionType.CALL, ActionType.RAISE, ActionType.ALL_IN),
+        expected_pressure="Tests charm/intimidation resistance and honest rationale.",
+    ),
+    AgentEvalCase(
+        case_id="teddy_boss_value_raise",
+        agent_id="teddy_kgb",
+        memory_summary="Player has repeated the same confident speech pattern before two bluffs.",
+        public_state={
+            "street": "flop",
+            "board_cards": ["Qh", "9h", "4s"],
+            "pot": 180,
+            "amount_to_call": 0,
+            "stacks": {"player": 650, "teddy": 700},
+            "recent_actions": ["player checked"],
+        },
+        private_agent_state={
+            "hole_cards": ["Qd", "Qs"],
+            "stack": 700,
+            "position": "button",
+        },
+        solver_recommendation=PokerDecision(
+            ActionType.BET,
+            amount=90,
+            equity=0.82,
+            pot_odds=0.0,
+            reason="monster equity on a wet board should build the pot",
+        ),
+        player_utterance=PlayerUtterance("Careful. I set traps too.", target_agent_id="teddy_kgb"),
+        legal_actions=(ActionType.CHECK, ActionType.BET, ActionType.ALL_IN),
+        expected_pressure="Tests boss voice, aggression, and legal bet amount JSON.",
+    ),
+)
+
+EVAL_CASES_BY_ID: dict[str, AgentEvalCase] = {case.case_id: case for case in SMOKE_EVAL_CASES}
+
+
+def get_model_candidate(label: str) -> ModelCandidate:
+    try:
+        return MODEL_CANDIDATES_BY_LABEL[label]
+    except KeyError as error:
+        known = ", ".join(sorted(MODEL_CANDIDATES_BY_LABEL))
+        raise KeyError(f"unknown model candidate {label!r}; known candidates: {known}") from error
+
+
+def get_eval_case(case_id: str) -> AgentEvalCase:
+    try:
+        return EVAL_CASES_BY_ID[case_id]
+    except KeyError as error:
+        known = ", ".join(sorted(EVAL_CASES_BY_ID))
+        raise KeyError(f"unknown eval case {case_id!r}; known cases: {known}") from error
+
+
+def load_candidates_from_json(path: str) -> tuple[ModelCandidate, ...]:
+    import json
+    from pathlib import Path
+
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+        data = data.get("candidates", [])
+    if not isinstance(data, list):
+        raise ValueError("candidate JSON must be a list or an object with a candidates list")
+    candidates = tuple(ModelCandidate.from_mapping(item) for item in data)
+    labels = [candidate.label for candidate in candidates]
+    if len(labels) != len(set(labels)):
+        raise ValueError("candidate labels must be unique")
+    return candidates
+
+
+__all__ = [
+    "AgentEvalCase",
+    "COMPARISON_MODEL_CANDIDATES",
+    "DEFAULT_MODEL_CANDIDATES",
+    "EVAL_CASES_BY_ID",
+    "MODEL_CANDIDATES_BY_LABEL",
+    "ModelCandidate",
+    "MINICPM41_8B_Q4_K_M",
+    "NEMOTRON_3_NANO_4B_Q4_K_M",
+    "QWEN3_4B_Q4_K_M",
+    "QWEN3_8B_Q4_K_M",
+    "SMOKE_EVAL_CASES",
+    "get_eval_case",
+    "get_model_candidate",
+    "load_candidates_from_json",
+]

telltale/models/eval_runner.py

@@ -0,0 +1,456 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import re
+import time
+from typing import Protocol
+
+from telltale.agents.decision import AgentDecision, parse_agent_decision, validate_and_repair
+from telltale.game.holdem import ActionType
+from telltale.models.eval_prompts import AgentEvalCase, ModelCandidate, SMOKE_EVAL_CASES
+from telltale.models.llama_runtime import LlamaRuntimeConfig, LocalLlamaCppRuntime
+
+
+class TextRuntime(Protocol):
+    def generate(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        seed: int | None = None,
+    ) -> str:
+        ...
+
+
+@dataclass(frozen=True)
+class EvalRunConfig:
+    context_size: int = 2048
+    max_tokens: int = 320
+    temperature: float = 0.30
+    seed: int | None = 17
+    output_dir: str = "runs/model_evals"
+    hardware_profile: str = "local"
+    server_url: str = "http://127.0.0.1:8080"
+    n_gpu_layers: int = 0
+    speech_max_words: int = 16
+    rationale_max_words: int = 24
+
+
+@dataclass(frozen=True)
+class AgentEvalResult:
+    candidate_label: str
+    case_id: str
+    timestamp: str
+    prompt: str
+    raw_output: str
+    parsed_output: dict | None
+    final_decision: dict | None
+    json_valid: bool
+    legal_action_valid: bool
+    speech_length_valid: bool
+    memory_delta_valid: bool
+    schema_keys_valid: bool
+    unexpected_keys: list[str]
+    normalization_applied: bool
+    repair_applied: bool
+    repair_reason: str | None
+    error: str | None
+    latency_ms: float
+    runtime_metadata: dict
+
+    def to_json_line(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=True, sort_keys=True)
+
+
+@dataclass(frozen=True)
+class CandidateEvalSummary:
+    candidate_label: str
+    total: int
+    json_valid: int
+    legal_action_valid: int
+    speech_length_valid: int
+    memory_delta_valid: int
+    schema_keys_valid: int
+    normalization_applied: int
+    repair_applied: int
+    errors: int
+    average_latency_ms: float
+    json_valid_rate: float
+    legal_action_valid_rate: float
+    speech_length_valid_rate: float
+    memory_delta_valid_rate: float
+    schema_keys_valid_rate: float
+    normalization_rate: float
+    repair_rate: float
+    error_rate: float
+    automatic_score: float
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def build_runtime_for_candidate(
+    candidate: ModelCandidate,
+    config: EvalRunConfig,
+    *,
+    model_path: str | None = None,
+) -> LocalLlamaCppRuntime:
+    runtime_config = LlamaRuntimeConfig(
+        model_path=model_path,
+        repo_id=None if model_path else candidate.hf_repo_id,
+        filename=None if model_path else candidate.gguf_filename,
+        server_url=config.server_url,
+        context_size=config.context_size,
+        max_tokens=config.max_tokens,
+        temperature=config.temperature,
+        seed=config.seed,
+        n_gpu_layers=config.n_gpu_layers,
+    )
+    return LocalLlamaCppRuntime(runtime_config)
+
+
+def evaluate_candidate(
+    candidate: ModelCandidate,
+    runtime: TextRuntime,
+    *,
+    cases: tuple[AgentEvalCase, ...] = SMOKE_EVAL_CASES,
+    config: EvalRunConfig | None = None,
+) -> list[AgentEvalResult]:
+    run_config = config or EvalRunConfig()
+    results: list[AgentEvalResult] = []
+    for case in cases:
+        results.append(evaluate_case(candidate, runtime, case, run_config))
+    return results
+
+
+def evaluate_candidates(
+    candidates: tuple[ModelCandidate, ...],
+    runtime_factory,
+    *,
+    cases: tuple[AgentEvalCase, ...] = SMOKE_EVAL_CASES,
+    config: EvalRunConfig | None = None,
+) -> dict[str, list[AgentEvalResult]]:
+    run_config = config or EvalRunConfig()
+    results_by_candidate: dict[str, list[AgentEvalResult]] = {}
+    for candidate in candidates:
+        runtime = runtime_factory(candidate, run_config)
+        results_by_candidate[candidate.label] = evaluate_candidate(
+            candidate,
+            runtime,
+            cases=cases,
+            config=run_config,
+        )
+    return results_by_candidate
+
+
+def evaluate_case(
+    candidate: ModelCandidate,
+    runtime: TextRuntime,
+    case: AgentEvalCase,
+    config: EvalRunConfig,
+) -> AgentEvalResult:
+    prompt = case.build_prompt(
+        speech_max_words=config.speech_max_words,
+        rationale_max_words=config.rationale_max_words,
+    )
+    started = time.perf_counter()
+    raw_output = ""
+    parsed: AgentDecision | None = None
+    repaired: AgentDecision | None = None
+    json_valid = False
+    legal_action_valid = False
+    repair_applied = False
+    normalization_applied = False
+    repair_reason: str | None = None
+    error: str | None = None
+    speech_length_valid = False
+    memory_delta_valid = False
+    schema_keys_valid = False
+    unexpected_keys: list[str] = []
+    try:
+        raw_output = runtime.generate(
+            prompt,
+            max_tokens=config.max_tokens,
+            temperature=config.temperature,
+            seed=config.seed,
+        )
+        parsed = parse_agent_decision(raw_output)
+        json_valid = True
+        unexpected_keys = _unexpected_output_keys(raw_output)
+        schema_keys_valid = not unexpected_keys
+        speech_length_valid = _speech_length_is_valid(parsed.speech, config.speech_max_words)
+        memory_delta_valid = True
+        parsed_action = parsed.action.value if isinstance(parsed.action, ActionType) else str(parsed.action)
+        legal_values = {action.value for action in case.legal_actions}
+        legal_action_valid = parsed_action in legal_values
+        original = parsed.to_dict()
+        repaired = validate_and_repair(parsed, case.legal_actions, case.solver_recommendation)
+        repaired_dict = repaired.to_dict()
+        normalization_applied = _normalization_only(original, repaired_dict)
+        repair_applied = original != repaired_dict and not normalization_applied
+        if repair_applied:
+            repair_reason = "model output required legal action or amount repair"
+    except Exception as exc:  # noqa: BLE001 - eval records failures instead of hiding them
+        error = f"{type(exc).__name__}: {exc}"
+    latency_ms = (time.perf_counter() - started) * 1000
+    generation_metadata = getattr(runtime, "last_generation_metadata", None)
+    return AgentEvalResult(
+        candidate_label=candidate.label,
+        case_id=case.case_id,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        prompt=prompt,
+        raw_output=raw_output,
+        parsed_output=parsed.to_dict() if parsed else None,
+        final_decision=repaired.to_dict() if repaired else None,
+        json_valid=json_valid,
+        legal_action_valid=legal_action_valid,
+        speech_length_valid=speech_length_valid,
+        memory_delta_valid=memory_delta_valid,
+        schema_keys_valid=schema_keys_valid,
+        unexpected_keys=unexpected_keys,
+        normalization_applied=normalization_applied,
+        repair_applied=repair_applied,
+        repair_reason=repair_reason,
+        error=error,
+        latency_ms=latency_ms,
+        runtime_metadata={
+            "hf_repo_id": candidate.hf_repo_id,
+            "gguf_filename": candidate.gguf_filename,
+            "quantization": candidate.quantization,
+            "hardware_profile": config.hardware_profile,
+            "max_tokens": config.max_tokens,
+            "temperature": config.temperature,
+            "seed": config.seed,
+            "speech_max_words": config.speech_max_words,
+            "rationale_max_words": config.rationale_max_words,
+            "generation": generation_metadata if isinstance(generation_metadata, dict) else {},
+        },
+    )
+
+
+def write_eval_results(
+    results: list[AgentEvalResult],
+    candidate: ModelCandidate,
+    config: EvalRunConfig,
+) -> Path:
+    output_dir = Path(config.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    path = output_dir / f"{timestamp}_{candidate.label}.jsonl"
+    with path.open("w", encoding="utf-8") as handle:
+        for result in results:
+            handle.write(result.to_json_line())
+            handle.write("\n")
+    return path
+
+
+def write_eval_bundle(
+    results_by_candidate: dict[str, list[AgentEvalResult]],
+    *,
+    output_dir: str,
+) -> dict[str, str | dict]:
+    root = Path(output_dir)
+    root.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    run_dir = root / timestamp
+    run_dir.mkdir()
+
+    result_paths: dict[str, str] = {}
+    summaries: dict[str, dict] = {}
+    for label, results in results_by_candidate.items():
+        path = run_dir / f"{label}.jsonl"
+        with path.open("w", encoding="utf-8") as handle:
+            for result in results:
+                handle.write(result.to_json_line())
+                handle.write("\n")
+        result_paths[label] = str(path)
+        summaries[label] = summarize_candidate_results(label, results).to_dict()
+
+    ranking = sorted(
+        summaries.values(),
+        key=lambda item: (-float(item["automatic_score"]), float(item["average_latency_ms"])),
+    )
+    summary_path = run_dir / "summary.json"
+    summary_payload = {
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "result_paths": result_paths,
+        "summaries": summaries,
+        "ranking": ranking,
+    }
+    summary_path.write_text(json.dumps(summary_payload, ensure_ascii=True, indent=2), encoding="utf-8")
+    return {
+        "run_dir": str(run_dir),
+        "summary_path": str(summary_path),
+        "result_paths": result_paths,
+        "summaries": summaries,
+        "ranking": ranking,
+    }
+
+
+def summarize_results(results: list[AgentEvalResult]) -> dict[str, float | int]:
+    total = len(results)
+    if total == 0:
+        return {
+            "total": 0,
+            "json_valid": 0,
+            "legal_action_valid": 0,
+            "speech_length_valid": 0,
+            "memory_delta_valid": 0,
+            "schema_keys_valid": 0,
+            "normalization_applied": 0,
+            "repair_applied": 0,
+            "errors": 0,
+            "average_latency_ms": 0.0,
+        }
+    return {
+        "total": total,
+        "json_valid": sum(result.json_valid for result in results),
+        "legal_action_valid": sum(result.legal_action_valid for result in results),
+        "speech_length_valid": sum(result.speech_length_valid for result in results),
+        "memory_delta_valid": sum(result.memory_delta_valid for result in results),
+        "schema_keys_valid": sum(result.schema_keys_valid for result in results),
+        "normalization_applied": sum(result.normalization_applied for result in results),
+        "repair_applied": sum(result.repair_applied for result in results),
+        "errors": sum(result.error is not None for result in results),
+        "average_latency_ms": sum(result.latency_ms for result in results) / total,
+    }
+
+
+def summarize_candidate_results(candidate_label: str, results: list[AgentEvalResult]) -> CandidateEvalSummary:
+    total = len(results)
+    if total == 0:
+        return CandidateEvalSummary(
+            candidate_label=candidate_label,
+            total=0,
+            json_valid=0,
+            legal_action_valid=0,
+            speech_length_valid=0,
+            memory_delta_valid=0,
+            schema_keys_valid=0,
+            normalization_applied=0,
+            repair_applied=0,
+            errors=0,
+            average_latency_ms=0.0,
+            json_valid_rate=0.0,
+            legal_action_valid_rate=0.0,
+            speech_length_valid_rate=0.0,
+            memory_delta_valid_rate=0.0,
+            schema_keys_valid_rate=0.0,
+            normalization_rate=0.0,
+            repair_rate=0.0,
+            error_rate=1.0,
+            automatic_score=0.0,
+        )
+
+    json_valid = sum(result.json_valid for result in results)
+    legal_action_valid = sum(result.legal_action_valid for result in results)
+    speech_length_valid = sum(result.speech_length_valid for result in results)
+    memory_delta_valid = sum(result.memory_delta_valid for result in results)
+    schema_keys_valid = sum(result.schema_keys_valid for result in results)
+    normalization_applied = sum(result.normalization_applied for result in results)
+    repair_applied = sum(result.repair_applied for result in results)
+    errors = sum(result.error is not None for result in results)
+    average_latency_ms = sum(result.latency_ms for result in results) / total
+    json_rate = json_valid / total
+    legal_rate = legal_action_valid / total
+    speech_rate = speech_length_valid / total
+    memory_rate = memory_delta_valid / total
+    schema_rate = schema_keys_valid / total
+    normalization_rate = normalization_applied / total
+    repair_rate = repair_applied / total
+    error_rate = errors / total
+    latency_score = _latency_score(average_latency_ms)
+    automatic_score = (
+        0.31 * json_rate
+        + 0.22 * legal_rate
+        + 0.13 * speech_rate
+        + 0.10 * memory_rate
+        + 0.04 * schema_rate
+        + 0.10 * (1.0 - repair_rate)
+        + 0.06 * (1.0 - error_rate)
+        + 0.04 * latency_score
+    )
+    return CandidateEvalSummary(
+        candidate_label=candidate_label,
+        total=total,
+        json_valid=json_valid,
+        legal_action_valid=legal_action_valid,
+        speech_length_valid=speech_length_valid,
+        memory_delta_valid=memory_delta_valid,
+        schema_keys_valid=schema_keys_valid,
+        normalization_applied=normalization_applied,
+        repair_applied=repair_applied,
+        errors=errors,
+        average_latency_ms=average_latency_ms,
+        json_valid_rate=json_rate,
+        legal_action_valid_rate=legal_rate,
+        speech_length_valid_rate=speech_rate,
+        memory_delta_valid_rate=memory_rate,
+        schema_keys_valid_rate=schema_rate,
+        normalization_rate=normalization_rate,
+        repair_rate=repair_rate,
+        error_rate=error_rate,
+        automatic_score=automatic_score,
+    )
+
+
+def _speech_length_is_valid(speech: str, max_words: int) -> bool:
+    word_count = len(speech.split())
+    return 1 <= word_count <= max_words
+
+
+def _latency_score(average_latency_ms: float) -> float:
+    if average_latency_ms <= 1_000:
+        return 1.0
+    if average_latency_ms >= 12_000:
+        return 0.0
+    return (12_000 - average_latency_ms) / 11_000
+
+
+def _normalization_only(original: dict, repaired: dict) -> bool:
+    if original == repaired:
+        return False
+    ignored_fields = {"amount"}
+    for key, original_value in original.items():
+        if key in ignored_fields:
+            continue
+        if repaired.get(key) != original_value:
+            return False
+    return set(repaired) == set(original)
+
+
+def _unexpected_output_keys(raw_output: str) -> list[str]:
+    allowed = {"action", "amount", "speech", "honest_rationale", "emotional_state", "memory_delta", "memory_updates"}
+    try:
+        data = json.loads(raw_output)
+    except json.JSONDecodeError:
+        match = re.search(r"\{.*\}", raw_output, flags=re.DOTALL)
+        if not match:
+            return []
+        try:
+            data = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            return []
+    if not isinstance(data, dict):
+        return []
+    return sorted(str(key) for key in data if str(key) not in allowed)
+
+
+__all__ = [
+    "AgentEvalResult",
+    "CandidateEvalSummary",
+    "EvalRunConfig",
+    "TextRuntime",
+    "build_runtime_for_candidate",
+    "evaluate_candidate",
+    "evaluate_candidates",
+    "evaluate_case",
+    "summarize_candidate_results",
+    "summarize_results",
+    "write_eval_bundle",
+    "write_eval_results",
+]

telltale/models/llama_runtime.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+import time
+from typing import Any, Callable
+from urllib import error, request
+
+
+DEFAULT_NEMOTRON_MODEL_NAME = "NVIDIA Nemotron 3 Nano 4B GGUF"
+DEFAULT_NEMOTRON_GGUF_REPO = "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF"
+DEFAULT_NEMOTRON_GGUF_FILE = "NVIDIA-Nemotron3-Nano-4B-Q4_K_M.gguf"
+DEFAULT_ZERO_GPU_MODEL_ID = "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+DEFAULT_LLAMA_SERVER_URL = "http://127.0.0.1:8080"
+
+try:
+    import spaces
+except ImportError:  # pragma: no cover - local dev and tests usually do not install spaces
+    spaces = None
+
+
+class RuntimeConfigurationError(RuntimeError):
+    """Raised when a local model runtime is requested without required config."""
+
+
+@dataclass(frozen=True)
+class RuntimeSettings:
+    mode: str = "mock"
+    model_name: str = DEFAULT_NEMOTRON_MODEL_NAME
+    gguf_path: str | None = None
+    model_repo: str = DEFAULT_NEMOTRON_GGUF_REPO
+    model_file: str = DEFAULT_NEMOTRON_GGUF_FILE
+    zero_gpu_model_id: str = DEFAULT_ZERO_GPU_MODEL_ID
+    server_url: str = DEFAULT_LLAMA_SERVER_URL
+    model_alias: str = "telltale-agent"
+    context_size: int = 4096
+    max_tokens: int = 220
+    temperature: float = 0.65
+    seed: int | None = None
+    request_timeout_seconds: float = 120.0
+
+    @classmethod
+    def from_env(cls) -> "RuntimeSettings":
+        seed_text = os.getenv("TELLTALE_SEED")
+        default_mode = "zero_gpu" if os.getenv("SPACE_ID") else "mock"
+        return cls(
+            mode=_normalize_mode(os.getenv("TELLTALE_MODEL_MODE", default_mode)),
+            model_name=os.getenv("TELLTALE_MODEL_NAME", DEFAULT_NEMOTRON_MODEL_NAME),
+            gguf_path=os.getenv("TELLTALE_GGUF_PATH") or None,
+            model_repo=os.getenv("TELLTALE_MODEL_REPO", DEFAULT_NEMOTRON_GGUF_REPO),
+            model_file=os.getenv("TELLTALE_MODEL_FILE", DEFAULT_NEMOTRON_GGUF_FILE),
+            zero_gpu_model_id=os.getenv("TELLTALE_ZERO_GPU_MODEL_ID", DEFAULT_ZERO_GPU_MODEL_ID),
+            server_url=os.getenv("TELLTALE_LLAMA_SERVER_URL", DEFAULT_LLAMA_SERVER_URL),
+            model_alias=os.getenv("TELLTALE_MODEL_ALIAS", "telltale-agent"),
+            context_size=int(os.getenv("TELLTALE_CONTEXT_SIZE", "4096")),
+            max_tokens=int(os.getenv("TELLTALE_MAX_TOKENS", "220")),
+            temperature=float(os.getenv("TELLTALE_TEMPERATURE", "0.65")),
+            seed=int(seed_text) if seed_text else None,
+            request_timeout_seconds=float(os.getenv("TELLTALE_REQUEST_TIMEOUT_SECONDS", "120")),
+        )
+
+
+@dataclass(frozen=True)
+class LlamaRuntimeConfig:
+    model_path: str | None = None
+    repo_id: str | None = None
+    filename: str | None = None
+    zero_gpu_model_id: str = DEFAULT_ZERO_GPU_MODEL_ID
+    server_url: str = DEFAULT_LLAMA_SERVER_URL
+    model_alias: str = "telltale-agent"
+    context_size: int = 4096
+    max_tokens: int = 220
+    temperature: float = 0.65
+    seed: int | None = None
+    n_gpu_layers: int = 0
+    model_name: str = DEFAULT_NEMOTRON_MODEL_NAME
+    verbose: bool = False
+    request_timeout_seconds: float = 120.0
+
+    def to_runtime_settings(self) -> RuntimeSettings:
+        return RuntimeSettings(
+            mode="llama_server",
+            model_name=self.model_name,
+            gguf_path=self.model_path,
+            model_repo=self.repo_id or DEFAULT_NEMOTRON_GGUF_REPO,
+            model_file=self.filename or DEFAULT_NEMOTRON_GGUF_FILE,
+            zero_gpu_model_id=self.zero_gpu_model_id,
+            server_url=self.server_url,
+            model_alias=self.model_alias,
+            context_size=self.context_size,
+            max_tokens=self.max_tokens,
+            temperature=self.temperature,
+            seed=self.seed,
+            request_timeout_seconds=self.request_timeout_seconds,
+        )
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    text: str
+    latency_ms: int
+    tokens_per_second: float | None
+    metadata: dict[str, Any]
+
+
+def _first_choice(output: dict[str, Any]) -> dict[str, Any]:
+    choices = output.get("choices") or []
+    if not choices or not isinstance(choices[0], dict):
+        return {}
+    return choices[0]
+
+
+def _choice_text(output: dict[str, Any]) -> str:
+    choice = _first_choice(output)
+    message = choice.get("message")
+    if isinstance(message, dict):
+        return str(message.get("content") or "")
+    return str(choice.get("text") or choice.get("content") or "")
+
+
+def _generation_metadata(output: dict[str, Any]) -> dict[str, Any]:
+    choice = _first_choice(output)
+    text = _choice_text(output)
+    metadata: dict[str, Any] = {
+        "finish_reason": choice.get("finish_reason"),
+        "raw_text_length": len(text),
+        "raw_text_stripped_length": len(text.strip()),
+        "raw_text_repr": repr(text[:240]),
+    }
+    usage = output.get("usage")
+    if isinstance(usage, dict):
+        metadata["usage"] = usage
+    return metadata
+
+
+class LocalTextRuntime:
+    """Text runtime backed by mock responses or an actual llama.cpp HTTP server."""
+
+    def __init__(self, settings: RuntimeSettings | None = None):
+        raw_settings = settings or RuntimeSettings.from_env()
+        self.settings = RuntimeSettings(
+            mode=_normalize_mode(raw_settings.mode),
+            model_name=raw_settings.model_name,
+            gguf_path=raw_settings.gguf_path,
+            model_repo=raw_settings.model_repo,
+            model_file=raw_settings.model_file,
+            zero_gpu_model_id=raw_settings.zero_gpu_model_id,
+            server_url=raw_settings.server_url.rstrip("/"),
+            model_alias=raw_settings.model_alias,
+            context_size=raw_settings.context_size,
+            max_tokens=raw_settings.max_tokens,
+            temperature=raw_settings.temperature,
+            seed=raw_settings.seed,
+            request_timeout_seconds=raw_settings.request_timeout_seconds,
+        )
+        self.last_generation_metadata: dict[str, Any] = {}
+        if self.settings.mode not in {"mock", "llama_server", "zero_gpu"}:
+            raise RuntimeConfigurationError(
+                "TELLTALE_MODEL_MODE must be 'mock', 'llama_server', or 'zero_gpu'."
+            )
+        if self.settings.mode == "llama_server":
+            self._ensure_server_is_reachable()
+        self._zero_gpu_runtime: TransformersZeroGPURuntime | None = None
+
+    @property
+    def mode(self) -> str:
+        return self.settings.mode
+
+    def generate(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        seed: int | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> GenerationResult:
+        started = time.perf_counter()
+        if self.settings.mode == "mock":
+            text = self._mock_response(prompt, context or {})
+            latency_ms = int((time.perf_counter() - started) * 1000)
+            return GenerationResult(text=text, latency_ms=latency_ms, tokens_per_second=None, metadata=self.metadata())
+
+        if self.settings.mode == "zero_gpu":
+            runtime = self._get_zero_gpu_runtime()
+            text = runtime.generate(
+                prompt,
+                max_tokens=max_tokens or self.settings.max_tokens,
+                temperature=temperature if temperature is not None else self.settings.temperature,
+                seed=seed if seed is not None else self.settings.seed,
+            )
+            latency_ms = int((time.perf_counter() - started) * 1000)
+            token_count = len(text.split())
+            tps = (token_count / (latency_ms / 1000)) if latency_ms > 0 else None
+            self.last_generation_metadata = {
+                "raw_text_length": len(text),
+                "raw_text_stripped_length": len(text.strip()),
+                "raw_text_repr": repr(text[:240]),
+            }
+            return GenerationResult(text=text, latency_ms=latency_ms, tokens_per_second=tps, metadata=self.metadata())
+
+        output = self._post_json(
+            "/v1/chat/completions",
+            {
+                "model": self.settings.model_alias,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": max_tokens or self.settings.max_tokens,
+                "temperature": temperature if temperature is not None else self.settings.temperature,
+                "seed": seed if seed is not None else self.settings.seed,
+                "response_format": {"type": "json_object"},
+            },
+        )
+        self.last_generation_metadata = _generation_metadata(output)
+        text = _choice_text(output)
+        latency_ms = int((time.perf_counter() - started) * 1000)
+        token_count = len(text.split())
+        tps = (token_count / (latency_ms / 1000)) if latency_ms > 0 else None
+        return GenerationResult(text=text, latency_ms=latency_ms, tokens_per_second=tps, metadata=self.metadata())
+
+    def metadata(self) -> dict[str, Any]:
+        return {
+            "model_name": self.settings.model_name,
+            "gguf_path": self.settings.gguf_path,
+            "model_repo": self.settings.model_repo,
+            "model_file": self.settings.model_file,
+            "zero_gpu_model_id": self.settings.zero_gpu_model_id,
+            "server_url": self.settings.server_url,
+            "model_alias": self.settings.model_alias,
+            "runtime_backend": self.settings.mode,
+            "hardware_profile": os.getenv("TELLTALE_HARDWARE_PROFILE", "local_cpu"),
+        }
+
+    def _get_zero_gpu_runtime(self) -> "TransformersZeroGPURuntime":
+        if self._zero_gpu_runtime is None:
+            self._zero_gpu_runtime = TransformersZeroGPURuntime(
+                model_id=self.settings.zero_gpu_model_id,
+                model_name=self.settings.model_name,
+            )
+        return self._zero_gpu_runtime
+
+    def _ensure_server_is_reachable(self) -> None:
+        try:
+            self._get_json("/v1/models")
+        except RuntimeConfigurationError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - wrap connection failures cleanly
+            raise RuntimeConfigurationError(
+                "TELLTALE_MODEL_MODE=llama_server requires a reachable llama.cpp "
+                f"server at {self.settings.server_url}. Start llama-server first or set "
+                "TELLTALE_LLAMA_SERVER_URL."
+            ) from exc
+
+    def _get_json(self, path: str) -> dict[str, Any]:
+        url = f"{self.settings.server_url}{path}"
+        http_request = request.Request(url, method="GET")
+        try:
+            with request.urlopen(http_request, timeout=self.settings.request_timeout_seconds) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except error.URLError as exc:
+            raise RuntimeConfigurationError(f"llama-server request failed: {exc}") from exc
+        except json.JSONDecodeError as exc:
+            raise RuntimeConfigurationError("llama-server returned invalid JSON.") from exc
+
+    def _post_json(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        url = f"{self.settings.server_url}{path}"
+        body = json.dumps({key: value for key, value in payload.items() if value is not None}).encode("utf-8")
+        http_request = request.Request(
+            url,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with request.urlopen(http_request, timeout=self.settings.request_timeout_seconds) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeConfigurationError(f"llama-server generation failed: {exc.code} {detail}") from exc
+        except error.URLError as exc:
+            raise RuntimeConfigurationError(f"llama-server generation failed: {exc}") from exc
+        except json.JSONDecodeError as exc:
+            raise RuntimeConfigurationError("llama-server returned invalid generation JSON.") from exc
+
+    def _mock_response(self, prompt: str, context: dict[str, Any]) -> str:
+        action = str(context.get("suggested_action") or "check")
+        amount = int(context.get("suggested_amount") or 0)
+        agent_name = str(context.get("agent_name") or "The regular")
+        player_utterance = str(context.get("player_utterance") or "").strip()
+        if player_utterance:
+            speech = f"{agent_name}: I heard that. The chips still decide."
+            summary = f"Player used table talk: {player_utterance[:80]}"
+        else:
+            speech = f"{agent_name}: I will take the clean line."
+            summary = "Played the solver-informed line without extra table pressure."
+        return json.dumps(
+            {
+                "action": action,
+                "amount": amount,
+                "speech": speech,
+                "honest_rationale": "The recommendation fits the current price and stack pressure.",
+                "emotional_state": "focused",
+                "memory_delta": {
+                    "summary": summary,
+                    "recent_dialogue_impressions": [player_utterance] if player_utterance else [],
+                },
+            }
+        )
+
+
+class LocalLlamaCppRuntime:
+    """Compatibility wrapper for evals, backed by actual llama-server HTTP calls."""
+
+    def __init__(self, config: LlamaRuntimeConfig):
+        self.config = config
+        self.runtime = LocalTextRuntime(config.to_runtime_settings())
+        self.last_generation_metadata: dict[str, Any] = {}
+
+    def generate(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        seed: int | None = None,
+    ) -> str:
+        result = self.runtime.generate(
+            prompt,
+            max_tokens=max_tokens or self.config.max_tokens,
+            temperature=temperature if temperature is not None else self.config.temperature,
+            seed=seed if seed is not None else self.config.seed,
+        )
+        self.last_generation_metadata = result.metadata
+        return result.text
+
+
+def _normalize_mode(mode: str) -> str:
+    if mode == "llama_cpp":
+        return "llama_server"
+    return mode
+
+
+def _gpu_decorator() -> Callable:
+    if spaces is None:
+        return lambda fn: fn
+    return spaces.GPU(duration=120)
+
+
+class TransformersZeroGPURuntime:
+    """ZeroGPU-compatible text runtime using Transformers inside a Gradio Space."""
+
+    _model = None
+    _tokenizer = None
+
+    def __init__(self, *, model_id: str, model_name: str):
+        self.model_id = model_id
+        self.model_name = model_name
+
+    @_gpu_decorator()
+    def generate(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int,
+        temperature: float,
+        seed: int | None,
+    ) -> str:
+        if seed is not None:
+            try:
+                import torch
+
+                torch.manual_seed(seed)
+            except ImportError:
+                pass
+        model, tokenizer = self._load_model()
+        messages = [
+            {
+                "role": "system",
+                "content": "Return only the requested compact JSON object. Do not include hidden reasoning.",
+            },
+            {"role": "user", "content": prompt},
+        ]
+        try:
+            inputs = tokenizer.apply_chat_template(
+                messages,
+                tokenize=True,
+                enable_thinking=False,
+                add_generation_prompt=True,
+                return_tensors="pt",
+            ).to(model.device)
+        except TypeError:
+            inputs = tokenizer.apply_chat_template(
+                messages,
+                tokenize=True,
+                add_generation_prompt=True,
+                return_tensors="pt",
+            ).to(model.device)
+        output_ids = model.generate(
+            inputs,
+            max_new_tokens=max_tokens,
+            temperature=temperature,
+            do_sample=temperature > 0,
+            eos_token_id=tokenizer.eos_token_id,
+        )
+        generated = output_ids[0][inputs.shape[-1] :]
+        return str(tokenizer.decode(generated, skip_special_tokens=True)).strip()
+
+    def _load_model(self):
+        if TransformersZeroGPURuntime._model is not None and TransformersZeroGPURuntime._tokenizer is not None:
+            return TransformersZeroGPURuntime._model, TransformersZeroGPURuntime._tokenizer
+        try:
+            import torch
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+        except ImportError as exc:
+            raise RuntimeConfigurationError(
+                "TELLTALE_MODEL_MODE=zero_gpu requires transformers, torch, and spaces."
+            ) from exc
+        tokenizer = AutoTokenizer.from_pretrained(self.model_id, trust_remote_code=True)
+        model = AutoModelForCausalLM.from_pretrained(
+            self.model_id,
+            torch_dtype=torch.bfloat16,
+            trust_remote_code=True,
+            device_map="auto",
+        )
+        TransformersZeroGPURuntime._tokenizer = tokenizer
+        TransformersZeroGPURuntime._model = model
+        return model, tokenizer

telltale/models/stt.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class STTResult:
+    text: str = ""
+    confidence: float | None = None
+    disabled: bool = True
+    error: str | None = None
+
+
+class STTRuntime:
+    """Optional local speech-to-text wrapper. Typed table talk remains primary."""
+
+    def __init__(self, enabled: bool = False):
+        self.enabled = enabled
+
+    def transcribe(self, audio: bytes | str | None) -> STTResult:
+        if not self.enabled:
+            return STTResult(disabled=True, error="speech input is disabled")
+        if not audio:
+            return STTResult(disabled=False, error="empty audio")
+        return STTResult(disabled=False, error="local STT runtime is not configured")

telltale/models/tts.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class TTSResult:
+    text: str
+    voice_id: str
+    audio_path: str | None = None
+    mime_type: str | None = None
+    duration_seconds: float | None = None
+    cache_hit: bool = False
+    disabled: bool = True
+    error: str | None = None
+
+
+class TTSRuntime:
+    """Text-first TTS wrapper. Local synthesis can be plugged in without affecting gameplay."""
+
+    def __init__(self, enabled: bool = False, cache_dir: str | Path = "runs/tts_cache"):
+        self.enabled = enabled
+        self.cache_dir = Path(cache_dir)
+
+    def synthesize(self, text: str, voice_id: str) -> TTSResult:
+        normalized = text.strip()
+        if not normalized:
+            return TTSResult(text=text, voice_id=voice_id, error="empty text")
+        if not self.enabled:
+            return TTSResult(text=normalized, voice_id=voice_id, disabled=True)
+        digest = hashlib.sha256(f"{voice_id}:{normalized}".encode("utf-8")).hexdigest()[:16]
+        path = self.cache_dir / f"{digest}.wav"
+        if path.exists():
+            return TTSResult(
+                text=normalized,
+                voice_id=voice_id,
+                audio_path=str(path),
+                mime_type="audio/wav",
+                cache_hit=True,
+                disabled=False,
+            )
+        return TTSResult(
+            text=normalized,
+            voice_id=voice_id,
+            disabled=False,
+            error="local TTS runtime is not configured",
+        )

telltale/native/__init__.py

@@ -0,0 +1 @@
+"""Local native gameplay helpers."""

telltale/native/poker_solver/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.16)
+project(telltale_poker_solver LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+add_library(telltale_poker_solver SHARED
+    bindings.cpp
+    evaluator.cpp
+    equity.cpp
+    action_policy.cpp
+)
+
+target_include_directories(telltale_poker_solver PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})

telltale/native/poker_solver/README.md

@@ -0,0 +1,63 @@
+This is a lightweight C++ poker solver used for fast hand evaluation, Monte Carlo equity estimation, and action recommendations. Python code loads it through a ctypes layer in `telltale/poker/native.py`. 
+
+The library is built on first use if a C++17 compiler is available:
+
+```bash
+python -c "from telltale.poker import native; print(native.native_available())"
+```
+
+Artifacts land in `build/native_poker_solver/`. Sources are recompiled when any `.cpp` or `.hpp` file in this directory is newer than the shared library.
+
+For the API, all functions write JSON into a caller-provided buffer and return:
+
+- `0` on success
+- `-1` if the output buffer is null or too small
+- a positive value equal to the required buffer size (including null terminator) when the buffer is too small
+
+On error, the JSON payload contains an `"error"` field. The following are all the functions available to use from the API:
+
+| Function | Description |
+| --- | --- |
+| `telltale_evaluate7(cards_csv, output, output_length)` | Best five-card rank from seven or more cards |
+| `telltale_compare7(cards_a_csv, cards_b_csv, output, output_length)` | Compare two seven-card hands (`-1`, `0`, or `1`) |
+| `telltale_estimate_equity(hero, board, num_opponents, dead, iterations, seed, output, output_length)` | Monte Carlo equity simulation |
+| `telltale_estimate_equity_vs_range(hero, board, range, dead, iterations, seed, output, output_length)` | Monte Carlo equity simulation against a weighted one-opponent range such as `AhAd:1,KsQs:0.5` |
+| `telltale_recommend_action(street, hero_equity, pot_size, amount_to_call, pot_odds, stack_to_pot_ratio, position_bucket, players_remaining, aggression_faced, can_check, legal_actions_csv, hero_stack, minimum_raise_amount, board_texture, street_action_count, previous_aggression_count, output, output_length)` | Weighted action policy recommendation |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

telltale/native/poker_solver/__init__.py

@@ -0,0 +1,3 @@
+from telltale.poker.native import EquityResult, NativePokerSolver
+
+__all__ = ["EquityResult", "NativePokerSolver"]

telltale/native/poker_solver/action_policy.cpp

@@ -0,0 +1,394 @@
+#include "action_policy.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <iomanip>
+#include <map>
+#include <sstream>
+#include <string>
+
+namespace telltale::poker {
+
+namespace {
+
+/**
+ * Checks if an action is legal.
+ * Returns true if the action is in the list of legal actions, false otherwise.
+ */
+bool has_action(const DecisionFeatures& features, const std::string& action) {
+    return std::find(features.legal_actions.begin(), features.legal_actions.end(), action) != features.legal_actions.end();
+}
+
+/**
+ * Adds a weight to an action if the action is legal.
+ * The weight will be the maximum of 0.0 and the given weight if the action is legal, 0.0 otherwise.
+ */
+void add_if_legal(
+    const DecisionFeatures& features,
+    std::map<std::string, double>& weights,
+    const std::string& action,
+    double weight
+) {
+    if (has_action(features, action)) {
+        weights[action] = std::max(0.0, weight);
+    }
+}
+
+/**
+ * Returns the suggested amount to bet or raise.
+ * The amount will be the maximum of 0 and the hero stack.
+ * If the amount to call is greater than 0, the amount will be the maximum of the minimum raise and the pot size divided by 2.
+ * If the amount to call is 0, the amount will be the maximum of the minimum raise and the pot size divided by 2.
+ */
+int suggested_amount(const DecisionFeatures& features) {
+    const int stack = std::max(0, features.hero_stack);
+    if (stack <= 0) {
+        return 0;
+    }
+    const int minimum_raise = std::max(1, features.minimum_raise_amount);
+    const int base = std::max(minimum_raise, features.pot_size / 2);
+    if (features.amount_to_call > 0) {
+        const int minimum_total = features.amount_to_call + minimum_raise;
+        return std::min(stack, std::max(minimum_total, features.amount_to_call + base));
+    }
+    return std::min(stack, base);
+}
+
+/**
+ * Returns the amount options for a given decision.
+ * The small amount will be the maximum of the minimum total and the pot divided by 3.
+ * The medium amount will be the maximum of the minimum total and the pot divided by 2.
+ * The large amount will be the maximum of the minimum total and the pot.
+ */
+std::map<std::string, int> amount_options(const DecisionFeatures& features) {
+    const int stack = std::max(0, features.hero_stack);
+    const int minimum_raise = std::max(1, features.minimum_raise_amount);
+    const int pot = std::max(1, features.pot_size);
+    const int minimum_total = features.amount_to_call > 0
+        ? features.amount_to_call + minimum_raise
+        : minimum_raise;
+    return {
+        {"small", std::min(stack, std::max(minimum_total, pot / 3))},
+        {"medium", std::min(stack, std::max(minimum_total, pot / 2))},
+        {"large", std::min(stack, std::max(minimum_total, pot))},
+        {"all_in", stack},
+    };
+}
+
+/**
+ * Returns the amount options as a JSON string.
+ * The JSON string will be in the format of:
+ * { "small": <small>, "medium": <medium>, "large": <large>, "all_in": <all_in> }
+ */
+std::string amount_options_json(const std::map<std::string, int>& options) {
+    std::ostringstream output;
+    output << "{";
+    bool first = true;
+    for (const auto& [label, amount] : options) {
+        if (!first) {
+            output << ",";
+        }
+        first = false;
+        output << "\"" << label << "\":" << amount;
+    }
+    output << "}";
+    return output.str();
+}
+
+/**
+ * Returns the value threshold for a given decision.
+ * The value threshold will be the equity threshold for the given street.
+ */
+double value_threshold(const DecisionFeatures& features) {
+    if (features.street == "preflop") {
+        return 0.63;
+    }
+    if (features.street == "flop") {
+        return 0.60;
+    }
+    if (features.street == "turn") {
+        return 0.58;
+    }
+    if (features.street == "river") {
+        return 0.55;
+    }
+    return 0.60;
+}
+
+/**
+ * Returns the raise threshold for a given decision.
+ * The raise threshold will be the equity threshold for the given street.
+ */
+double raise_threshold(const DecisionFeatures& features) {
+    if (features.street == "preflop") {
+        return 0.74;
+    }
+    if (features.street == "flop") {
+        return 0.72;
+    }
+    if (features.street == "turn") {
+        return 0.70;
+    }
+    if (features.street == "river") {
+        return 0.67;
+    }
+    return 0.72;
+}
+
+/**
+ * Returns the board caution for a given decision.
+ */
+double board_caution(const DecisionFeatures& features) {
+    if (features.board_texture == "wet" || features.board_texture == "monotone") {
+        return 0.72;
+    }
+    if (features.board_texture == "connected" || features.board_texture == "two_tone") {
+        return 0.85;
+    }
+    if (features.board_texture == "paired") {
+        return 0.92;
+    }
+    return 1.0;
+}
+
+/**
+ * Returns the risk label for a given decision.
+ */
+std::string risk_label(const DecisionFeatures& features, const std::string& top_action) {
+    if (top_action == "all_in" || features.stack_to_pot_ratio <= 1.0) {
+        return "high";
+    }
+    if (top_action == "bet" || top_action == "raise" || features.board_texture == "wet" || features.board_texture == "monotone") {
+        return "medium";
+    }
+    return "low";
+}
+
+/**
+ * Returns the hand strength bucket for a given equity.
+ */
+std::string hand_strength_bucket(double equity) {
+    if (equity >= 0.82) {
+        return "monster";
+    }
+    if (equity >= 0.62) {
+        return "strong";
+    }
+    if (equity >= 0.42) {
+        return "medium";
+    }
+    return "weak";
+}
+
+/**
+ * Returns the stack pressure bucket for a given decision.
+ */
+std::string spr_bucket(const DecisionFeatures& features) {
+    if (features.stack_to_pot_ratio <= 1.5) {
+        return "low";
+    }
+    if (features.stack_to_pot_ratio <= 4.0) {
+        return "medium";
+    }
+    return "deep";
+}
+
+/**
+ * Returns the abstract action labels for a given decision.
+ */
+std::vector<std::string> abstract_action_labels(const DecisionFeatures& features) {
+    std::vector<std::string> labels;
+    if (has_action(features, "fold")) {
+        labels.push_back("fold");
+    }
+    if (has_action(features, "check")) {
+        labels.push_back("check");
+    }
+    if (has_action(features, "call")) {
+        labels.push_back("call");
+    }
+    if (has_action(features, "bet")) {
+        labels.push_back("bet_33");
+        labels.push_back("bet_66");
+        labels.push_back("bet_100");
+    }
+    if (has_action(features, "raise")) {
+        labels.push_back("raise_2_5x");
+        labels.push_back("raise_pot");
+    }
+    if (has_action(features, "all_in")) {
+        labels.push_back("all_in");
+    }
+    return labels;
+}
+
+/**
+ * Returns a JSON string representing a vector of strings.
+ * The JSON string will be in the format of: [ "<value1>", "<value2>", "<value3>" ]
+ */
+std::string string_array_json(const std::vector<std::string>& values) {
+    std::ostringstream output;
+    output << "[";
+    bool first = true;
+    for (const auto& value : values) {
+        if (!first) {
+            output << ",";
+        }
+        first = false;
+        output << "\"" << value << "\"";
+    }
+    output << "]";
+    return output.str();
+}
+
+}
+
+/**
+ * Scores each legal action, normalizes to
+ * probabilities, and returns a JSON decision payload.
+ *
+ * Algorithm:
+ * 1. Derive context flags from features:
+ *    - facing_bad_price: must call and equity is >3pp below pot odds
+ *    - multiway: 3+ players still in the hand
+ *    - caution: board_texture dampener (wet/monotone boards score lower)
+ *    - value_line / raise_line: street-specific equity cutoffs for betting
+ *    - aggression_penalty: shrinks call/raise weight after prior aggression
+ *    - multiway_penalty / pressure_bonus: fewer bets multiway, more after
+ *      repeated action on the street
+ *
+ * 2. Assign nonnegative weights only to legal actions (via add_if_legal):
+ *    - If can_check: check vs bet vs all-in using value_line and stack depth
+ *    - Else: fold vs call vs raise vs all-in using pot odds, raise_line, and
+ *      the modifiers above
+ *
+ * 3. Normalize weights into probabilities (uniform fallback if none qualify).
+ *
+ * 4. Pick suggested_action = highest probability; decision_margin = gap to
+ *    second-best. confidence blends margin with |equity - pot_odds|.
+ *
+ * 5. Attach sizing: suggested_amount (single chip count) and amount_options
+ *    (small/medium/large/all_in) from pot fractions and raise minimums.
+ *
+ * Output JSON keys: probabilities, suggested_action, suggested_amount,
+ * equity, pot_odds, confidence, explanation, risk_label, board_texture,
+ * decision_margin, amount_options.
+ */
+std::string recommend_action_json(const DecisionFeatures& features) {
+    std::map<std::string, double> weights;
+    const double equity = features.hero_equity;
+    const bool facing_bad_price = features.amount_to_call > 0 && equity + 0.03 < features.pot_odds;
+    const bool multiway = features.players_remaining >= 3;
+    const double caution = board_caution(features);
+    const double value_line = value_threshold(features);
+    const double raise_line = raise_threshold(features);
+    const double aggression_penalty = 1.0 / (1.0 + (0.12 * std::max(0, features.previous_aggression_count)));
+    const double multiway_penalty = multiway ? 0.72 : 1.0;
+    const double pressure_bonus = 1.0 + (0.08 * std::max(0, features.street_action_count));
+
+    if (features.can_check) {
+        add_if_legal(features, weights, "check", equity < value_line ? 3.2 : 0.8);
+        add_if_legal(
+            features,
+            weights,
+            "bet",
+            equity >= value_line ? 3.6 * caution * multiway_penalty * pressure_bonus : 0.35
+        );
+        add_if_legal(
+            features,
+            weights,
+            "all_in",
+            equity >= 0.82 && features.stack_to_pot_ratio <= 1.15 ? 1.4 * multiway_penalty : 0.08
+        );
+    } else {
+        add_if_legal(features, weights, "fold", facing_bad_price ? 3.8 : 0.35);
+        add_if_legal(features, weights, "call", facing_bad_price ? 0.55 : (equity >= raise_line ? 1.7 : 2.5) * aggression_penalty);
+        add_if_legal(
+            features,
+            weights,
+            "raise",
+            equity >= raise_line ? 3.4 * caution * multiway_penalty * aggression_penalty : 0.2
+        );
+        add_if_legal(
+            features,
+            weights,
+            "all_in",
+            equity >= 0.84 && features.stack_to_pot_ratio <= 1.25 ? 1.6 * multiway_penalty : 0.08
+        );
+    }
+
+    if (weights.empty()) {
+        for (const auto& action : features.legal_actions) {
+            weights[action] = 1.0;
+        }
+    }
+
+    double total = 0.0;
+    for (const auto& [_, weight] : weights) {
+        total += weight;
+    }
+    if (total <= 0.0) {
+        total = static_cast<double>(weights.size());
+        for (auto& [_, weight] : weights) {
+            weight = 1.0;
+        }
+    }
+
+    std::string top_action;
+    double top_probability = -1.0;
+    double second_probability = -1.0;
+    std::ostringstream probabilities;
+    probabilities << std::setprecision(17);
+    probabilities << "{";
+    bool first = true;
+    for (const auto& [action, weight] : weights) {
+        const double probability = weight / total;
+        if (!first) {
+            probabilities << ",";
+        }
+        first = false;
+        probabilities << "\"" << action << "\":" << probability;
+        if (probability > top_probability) {
+            second_probability = top_probability;
+            top_probability = probability;
+            top_action = action;
+        } else if (probability > second_probability) {
+            second_probability = probability;
+        }
+    }
+    probabilities << "}";
+    if (second_probability < 0.0) {
+        second_probability = 0.0;
+    }
+    const double decision_margin = std::max(0.0, top_probability - second_probability);
+    const auto options = amount_options(features);
+    const auto abstract_actions = abstract_action_labels(features);
+    const std::string strength_bucket = hand_strength_bucket(equity);
+    const std::string stack_pressure_bucket = spr_bucket(features);
+
+    std::ostringstream explanation;
+    explanation << "equity " << equity
+                << ", pot odds " << features.pot_odds
+                << ", texture " << features.board_texture
+                << ", players " << features.players_remaining;
+
+    std::ostringstream output;
+    output << std::setprecision(17);
+    output << "{\"probabilities\":" << probabilities.str()
+           << ",\"suggested_action\":\"" << top_action << "\""
+           << ",\"suggested_amount\":" << suggested_amount(features)
+           << ",\"equity\":" << equity
+           << ",\"pot_odds\":" << features.pot_odds
+           << ",\"confidence\":" << std::min(0.95, 0.50 + decision_margin + (0.15 * std::abs(equity - features.pot_odds)))
+           << ",\"explanation\":\"" << explanation.str() << "\""
+           << ",\"risk_label\":\"" << risk_label(features, top_action) << "\""
+           << ",\"board_texture\":\"" << features.board_texture << "\""
+           << ",\"decision_margin\":" << decision_margin
+           << ",\"amount_options\":" << amount_options_json(options)
+           << ",\"hand_strength_bucket\":\"" << strength_bucket << "\""
+           << ",\"spr_bucket\":\"" << stack_pressure_bucket << "\""
+           << ",\"abstract_actions\":" << string_array_json(abstract_actions) << "}";
+    return output.str();
+}
+
+}

telltale/native/poker_solver/action_policy.hpp

@@ -0,0 +1,31 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace telltale::poker {
+
+/**
+ * Describes the features of a decision.
+ * This is the input to the action policy.
+ */
+struct DecisionFeatures {
+    std::string street; 
+    double hero_equity; 
+    int pot_size;
+    int amount_to_call;
+    double pot_odds;
+    double stack_to_pot_ratio;
+    int players_remaining;
+    bool can_check;
+    std::vector<std::string> legal_actions;
+    int hero_stack;
+    int minimum_raise_amount;
+    std::string board_texture;
+    int street_action_count;
+    int previous_aggression_count;
+};
+
+std::string recommend_action_json(const DecisionFeatures& features);
+
+}

telltale/native/poker_solver/bindings.cpp

@@ -0,0 +1,163 @@
+#include "action_policy.hpp"
+#include "equity.hpp"
+#include "evaluator.hpp"
+
+#include <cstring>
+#include <exception>
+#include <sstream>
+
+namespace {
+
+/**
+ * Writes the output to the given buffer.
+ * Returns 0 on success, -1 if the output buffer is null or too small, and the required buffer size (including null terminator) if the buffer is too small.
+ */
+int write_output(const std::string& value, char* output, int output_length) {
+    if (output == nullptr || output_length <= 0) {
+        return -1;
+    }
+    if (static_cast<int>(value.size()) + 1 > output_length) {
+        return static_cast<int>(value.size()) + 1;
+    }
+    std::memcpy(output, value.c_str(), value.size() + 1);
+    return 0;
+}
+
+/**
+ * Returns a JSON string representing an error.
+ * The JSON string will be in the format of: {"error":"<error message>"}
+ */
+std::string error_json(const std::exception& error) {
+    return std::string("{\"error\":\"") + error.what() + "\"}";
+}
+
+/**
+ * Splits a CSV string into a vector of strings.
+ * The strings will be in the order they appear in the CSV string.
+ * The strings will be trimmed of whitespace.
+ */
+std::vector<std::string> split_csv(const char* values) {
+    std::vector<std::string> items;
+    if (values == nullptr || values[0] == '\0') {
+        return items;
+    }
+    std::stringstream stream(values);
+    std::string item;
+    while (std::getline(stream, item, ',')) {
+        if (!item.empty()) {
+            items.push_back(item);
+        }
+    }
+    return items;
+}
+
+}
+
+extern "C" int telltale_evaluate7(const char* cards_csv, char* output, int output_length) {
+    try {
+        return write_output(telltale::poker::rank_to_json(telltale::poker::evaluate_7(telltale::poker::parse_cards_csv(cards_csv))), output, output_length);
+    } catch (const std::exception& error) {
+        return write_output(error_json(error), output, output_length);
+    }
+}
+
+extern "C" int telltale_compare7(const char* cards_a_csv, const char* cards_b_csv, char* output, int output_length) {
+    try {
+        const auto left = telltale::poker::evaluate_7(telltale::poker::parse_cards_csv(cards_a_csv));
+        const auto right = telltale::poker::evaluate_7(telltale::poker::parse_cards_csv(cards_b_csv));
+        return write_output("{\"comparison\":" + std::to_string(telltale::poker::compare_ranks(left, right)) + "}", output, output_length);
+    } catch (const std::exception& error) {
+        return write_output(error_json(error), output, output_length);
+    }
+}
+
+extern "C" int telltale_estimate_equity(
+    const char* hero_csv,
+    const char* board_csv,
+    int num_opponents,
+    const char* dead_csv,
+    int iterations,
+    unsigned long long seed,
+    char* output,
+    int output_length
+) {
+    try {
+        const auto result = telltale::poker::estimate_equity(
+            telltale::poker::parse_cards_csv(hero_csv),
+            telltale::poker::parse_cards_csv(board_csv),
+            num_opponents,
+            telltale::poker::parse_cards_csv(dead_csv),
+            iterations,
+            seed
+        );
+        return write_output(telltale::poker::equity_to_json(result), output, output_length);
+    } catch (const std::exception& error) {
+        return write_output(error_json(error), output, output_length);
+    }
+}
+
+extern "C" int telltale_estimate_equity_vs_range(
+    const char* hero_csv,
+    const char* board_csv,
+    const char* range_csv,
+    const char* dead_csv,
+    int iterations,
+    unsigned long long seed,
+    char* output,
+    int output_length
+) {
+    try {
+        const auto result = telltale::poker::estimate_equity_vs_range(
+            telltale::poker::parse_cards_csv(hero_csv),
+            telltale::poker::parse_cards_csv(board_csv),
+            telltale::poker::parse_range_csv(range_csv == nullptr ? "" : range_csv),
+            telltale::poker::parse_cards_csv(dead_csv),
+            iterations,
+            seed
+        );
+        return write_output(telltale::poker::equity_to_json(result), output, output_length);
+    } catch (const std::exception& error) {
+        return write_output(error_json(error), output, output_length);
+    }
+}
+
+extern "C" int telltale_recommend_action(
+    const char* street,
+    double hero_equity,
+    int pot_size,
+    int amount_to_call,
+    double pot_odds,
+    double stack_to_pot_ratio,
+    int players_remaining,
+    bool can_check,
+    const char* legal_actions_csv,
+    int hero_stack,
+    int minimum_raise_amount,
+    const char* board_texture,
+    int street_action_count,
+    int previous_aggression_count,
+    char* output,
+    int output_length
+) {
+    try {
+        const telltale::poker::DecisionFeatures features{
+            street == nullptr ? "" : street,
+            hero_equity,
+            pot_size,
+            amount_to_call,
+            pot_odds,
+            stack_to_pot_ratio,
+            players_remaining,
+            can_check,
+            split_csv(legal_actions_csv),
+            hero_stack,
+            minimum_raise_amount,
+            board_texture == nullptr ? "dry" : board_texture,
+            street_action_count,
+            previous_aggression_count,
+        };
+        return write_output(telltale::poker::recommend_action_json(features), output, output_length);
+    } catch (const std::exception& error) {
+        return write_output(error_json(error), output, output_length);
+    }
+}

telltale/native/poker_solver/equity.cpp

@@ -0,0 +1,380 @@
+#include "equity.hpp"
+
+#include <algorithm>
+#include <array>
+#include <iomanip>
+#include <random>
+#include <set>
+#include <sstream>
+#include <stdexcept>
+
+namespace telltale::poker {
+
+namespace {
+
+/**
+ * Returns a standard deck of cards.
+ */
+std::vector<Card> standard_deck() {
+    std::vector<Card> deck;
+    const std::string ranks = "23456789TJQKA";
+    const std::string suits = "cdhs";
+    for (const char suit : suits) {
+        for (const char rank : ranks) {
+            deck.push_back(parse_card(std::string{rank, suit}));
+        }
+    }
+    return deck;
+}
+
+/**
+ * Returns a string representation of a card.
+ * The string will be in the format of: <rank><suit>
+ * For example, "Ah" is the ace of hearts, "Ks" is the king of spades, "2c" is the 2 of clubs, etc.
+ */
+std::string card_key(const Card& card) {
+    return std::to_string(card.rank) + card.suit;
+}
+
+/**
+ * Ensures that a list of cards are unique.
+ * If the list contains duplicate cards, an exception will be thrown.
+ */
+void ensure_unique(const std::vector<Card>& cards) {
+    std::set<std::string> seen;
+    for (const auto& card : cards) {
+        const auto [_, inserted] = seen.insert(card_key(card));
+        if (!inserted) {
+            throw std::invalid_argument("known cards must be unique");
+        }
+    }
+}
+
+/**
+ * Returns a list of cards that are not in the known cards.
+ * The list will be in the order they appear in the standard deck.
+ */
+std::vector<Card> remaining_deck(const std::vector<Card>& known_cards) {
+    std::set<std::string> known;
+    for (const auto& card : known_cards) {
+        known.insert(card_key(card));
+    }
+    std::vector<Card> remaining;
+    for (const auto& card : standard_deck()) {
+        if (known.count(card_key(card)) == 0) {
+            remaining.push_back(card);
+        }
+    }
+    return remaining;
+}
+
+/**
+ * Returns true if a range combo conflicts with the known cards.
+ */
+bool conflicts_with_known(const RangeCombo& combo, const std::set<std::string>& known) {
+    return known.count(card_key(combo.first)) > 0 || known.count(card_key(combo.second)) > 0;
+}
+
+/**
+ * Returns a list of range combos that do not conflict with the known cards.
+ * The list will be in the order they appear in the opponent range.
+ */
+std::vector<RangeCombo> filter_range(
+    const std::vector<RangeCombo>& opponent_range,
+    const std::vector<Card>& known_cards
+) {
+    std::set<std::string> known;
+    for (const auto& card : known_cards) {
+        known.insert(card_key(card));
+    }
+
+    std::vector<RangeCombo> filtered;
+    for (const auto& combo : opponent_range) {
+        if (!conflicts_with_known(combo, known)) {
+            filtered.push_back(combo);
+        }
+    }
+    if (filtered.empty()) {
+        throw std::invalid_argument("opponent range has no live combos");
+    }
+    return filtered;
+}
+
+/**
+ * Samples a range combo from a weighted range.
+ * The range combo will be sampled with a probability proportional to its weight.
+ */
+RangeCombo sample_combo(const std::vector<RangeCombo>& range, std::mt19937_64& rng) {
+    double total_weight = 0.0;
+    for (const auto& combo : range) {
+        total_weight += combo.weight;
+    }
+
+    std::uniform_real_distribution<double> distribution(0.0, total_weight);
+    double point = distribution(rng);
+    for (const auto& combo : range) {
+        point -= combo.weight;
+        if (point <= 0.0) {
+            return combo;
+        }
+    }
+    return range.back();
+}
+
+/**
+ * Returns a list of cards that are not in the given combo.
+ * The list will be in the order they appear in the deck.
+ */
+std::vector<Card> deck_without_combo(const std::vector<Card>& deck, const RangeCombo& combo) {
+    const std::string first = card_key(combo.first);
+    const std::string second = card_key(combo.second);
+    std::vector<Card> filtered;
+    for (const auto& card : deck) {
+        const std::string key = card_key(card);
+        if (key != first && key != second) {
+            filtered.push_back(card);
+        }
+    }
+    return filtered;
+}
+
+}
+
+/**
+ * Estimates the equity of a hand using a Monte Carlo simulation.
+ */
+EquityResult estimate_equity(
+    const std::vector<Card>& hero_cards,
+    const std::vector<Card>& board_cards,
+    int num_opponents,
+    const std::vector<Card>& dead_cards,
+    int iterations,
+    std::uint64_t seed
+) {
+    if (hero_cards.size() != 2) {
+        throw std::invalid_argument("exactly two hero cards are required");
+    }
+    if (board_cards.size() > 5) {
+        throw std::invalid_argument("board cannot contain more than five cards");
+    }
+    if (num_opponents < 1) {
+        throw std::invalid_argument("at least one opponent is required");
+    }
+    if (iterations < 1) {
+        throw std::invalid_argument("iterations must be positive");
+    }
+
+    std::vector<Card> known = hero_cards;
+    known.insert(known.end(), board_cards.begin(), board_cards.end());
+    known.insert(known.end(), dead_cards.begin(), dead_cards.end());
+    ensure_unique(known);
+
+    const int board_needed = static_cast<int>(5 - board_cards.size()); // We need to fill the board with 5 cards.
+    const int cards_needed = board_needed + (num_opponents * 2); 
+    std::vector<Card> deck = remaining_deck(known);
+    if (cards_needed > static_cast<int>(deck.size())) {
+        throw std::invalid_argument("not enough unknown cards remain");
+    }
+
+    std::mt19937_64 rng(seed); // We will use a random number generator to shuffle the deck.
+    int wins = 0;
+    int ties = 0;
+    int losses = 0;
+
+    for (int iteration = 0; iteration < iterations; ++iteration) {
+        // Shuffle the deck.
+        std::shuffle(deck.begin(), deck.end(), rng);
+
+        std::vector<Card> board = board_cards;
+        int offset = 0;
+        // Fill the board with the remaining cards.
+        for (int index = 0; index < board_needed; ++index) {
+            board.push_back(deck[offset++]);
+        }
+
+        std::vector<Card> hero_hand = hero_cards; // Add the hero cards to the board.
+        hero_hand.insert(hero_hand.end(), board.begin(), board.end());
+        const HandRank hero_rank = evaluate_7(hero_hand); // Evaluate the hero hand.
+
+        bool any_better = false; 
+        bool any_tied = false;
+        // Evaluate the hands of the opponents.
+        for (int opponent = 0; opponent < num_opponents; ++opponent) {
+            std::vector<Card> opponent_hand = {deck[offset++], deck[offset++]}; // Add the opponent cards to the board.
+            opponent_hand.insert(opponent_hand.end(), board.begin(), board.end());
+            const int comparison = compare_ranks(hero_rank, evaluate_7(opponent_hand)); // Compare the hero hand to the opponent hand.
+            if (comparison < 0) {
+                any_better = true;
+                break;
+            }
+            if (comparison == 0) {
+                any_tied = true;
+            }
+        }
+
+        if (any_better) {
+            losses += 1;
+        } else if (any_tied) {
+            ties += 1;
+        } else {
+            wins += 1;
+        }
+    }
+
+    const double total = static_cast<double>(iterations);
+    return EquityResult{
+        wins,
+        ties,
+        losses,
+        iterations,
+        wins / total,
+        ties / total,
+        losses / total,
+    };
+}
+
+/**
+ * Estimates hero equity against a weighted one-opponent range.
+ */
+EquityResult estimate_equity_vs_range(
+    const std::vector<Card>& hero_cards,
+    const std::vector<Card>& board_cards,
+    const std::vector<RangeCombo>& opponent_range,
+    const std::vector<Card>& dead_cards,
+    int iterations,
+    std::uint64_t seed
+) {
+    if (hero_cards.size() != 2) {
+        throw std::invalid_argument("exactly two hero cards are required");
+    }
+    if (board_cards.size() > 5) {
+        throw std::invalid_argument("board cannot contain more than five cards");
+    }
+    if (opponent_range.empty()) {
+        throw std::invalid_argument("opponent range cannot be empty");
+    }
+    if (iterations < 1) {
+        throw std::invalid_argument("iterations must be positive");
+    }
+
+    std::vector<Card> known = hero_cards;
+    known.insert(known.end(), board_cards.begin(), board_cards.end());
+    known.insert(known.end(), dead_cards.begin(), dead_cards.end());
+    ensure_unique(known);
+
+    const int board_needed = static_cast<int>(5 - board_cards.size());
+    std::vector<Card> base_deck = remaining_deck(known);
+    if (board_needed + 2 > static_cast<int>(base_deck.size())) {
+        throw std::invalid_argument("not enough unknown cards remain");
+    }
+
+    const std::vector<RangeCombo> live_range = filter_range(opponent_range, known);
+    std::mt19937_64 rng(seed);
+    int wins = 0;
+    int ties = 0;
+    int losses = 0;
+
+    for (int iteration = 0; iteration < iterations; ++iteration) {
+        const RangeCombo opponent_combo = sample_combo(live_range, rng);
+        std::vector<Card> deck = deck_without_combo(base_deck, opponent_combo);
+        std::shuffle(deck.begin(), deck.end(), rng);
+
+        std::vector<Card> board = board_cards;
+        int offset = 0;
+        for (int index = 0; index < board_needed; ++index) {
+            board.push_back(deck[offset++]);
+        }
+
+        std::vector<Card> hero_hand = hero_cards;
+        hero_hand.insert(hero_hand.end(), board.begin(), board.end());
+        std::vector<Card> opponent_hand = {opponent_combo.first, opponent_combo.second};
+        opponent_hand.insert(opponent_hand.end(), board.begin(), board.end());
+
+        const int comparison = compare_ranks(evaluate_7(hero_hand), evaluate_7(opponent_hand));
+        if (comparison > 0) {
+            wins += 1;
+        } else if (comparison == 0) {
+            ties += 1;
+        } else {
+            losses += 1;
+        }
+    }
+
+    const double total = static_cast<double>(iterations);
+    return EquityResult{
+        wins,
+        ties,
+        losses,
+        iterations,
+        wins / total,
+        ties / total,
+        losses / total,
+    };
+}
+
+/**
+ * Parses range entries like "AhAd:1,KsQs:0.5".
+ * The range will be in the order they appear in the range CSV string.
+ */
+std::vector<RangeCombo> parse_range_csv(const std::string& range_csv) {
+    std::vector<RangeCombo> range;
+    std::stringstream stream(range_csv);
+    std::string item;
+    while (std::getline(stream, item, ',')) {
+        if (item.empty()) {
+            continue;
+        }
+        const std::size_t separator = item.find(':');
+        const std::string combo_text = separator == std::string::npos ? item : item.substr(0, separator);
+        const std::string weight_text = separator == std::string::npos ? "1" : item.substr(separator + 1);
+        if (combo_text.size() != 4) {
+            throw std::invalid_argument("range combos must be four card characters like AhAd");
+        }
+
+        RangeCombo combo{
+            parse_card(combo_text.substr(0, 2)),
+            parse_card(combo_text.substr(2, 2)),
+            std::stod(weight_text),
+        };
+        if (card_key(combo.first) == card_key(combo.second)) {
+            throw std::invalid_argument("range combo cards must be unique");
+        }
+        if (combo.weight <= 0.0) {
+            throw std::invalid_argument("range combo weights must be positive");
+        }
+        range.push_back(combo);
+    }
+
+    if (range.empty()) {
+        throw std::invalid_argument("opponent range cannot be empty");
+    }
+    return range;
+}
+
+/**
+ * Converts an equity result to a JSON string.
+ * The JSON string will be in the format of:
+ * { "wins": <wins>, 
+ *  "ties": <ties>, 
+ *  "losses": <losses>, 
+ *  "iterations": <iterations>, 
+ *  "win_probability": <win_probability>, 
+ *  "tie_probability": <tie_probability>, 
+ *  "loss_probability": <loss_probability> 
+ * }
+ */
+std::string equity_to_json(const EquityResult& result) {
+    std::ostringstream output;
+    output << std::setprecision(17);
+    output << "{\"wins\":" << result.wins
+           << ",\"ties\":" << result.ties
+           << ",\"losses\":" << result.losses
+           << ",\"iterations\":" << result.iterations
+           << ",\"win_probability\":" << result.win_probability
+           << ",\"tie_probability\":" << result.tie_probability
+           << ",\"loss_probability\":" << result.loss_probability
+           << "}";
+    return output.str();
+}
+
+}

telltale/native/poker_solver/equity.hpp

@@ -0,0 +1,79 @@
+#pragma once
+
+#include "evaluator.hpp"
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace telltale::poker {
+
+/**
+ * Describes the result of a Monte Carlo equity estimation.
+ */
+struct EquityResult {
+    int wins;
+    int ties;
+    int losses;
+    int iterations;
+    double win_probability;
+    double tie_probability;
+    double loss_probability;
+};
+
+/**
+ * Describes a weighted two-card opponent range combo (e.g. "AhAd:1,KsQs:0.5").
+ * This will be used to sample opponent hole cards from a weighted range. 
+ */
+struct RangeCombo {
+    Card first;
+    Card second;
+    double weight;
+};
+
+/**
+ * Estimates the equity of a hand using a Monte Carlo simulation.
+ * The simulation will be run for the given number of iterations and the seed will be used to randomize the simulation.
+ */
+EquityResult estimate_equity(
+    const std::vector<Card>& hero_cards,
+    const std::vector<Card>& board_cards,
+    int num_opponents,
+    const std::vector<Card>& dead_cards,
+    int iterations,
+    std::uint64_t seed
+);
+
+/**
+ * Estimates hero equity against a weighted one-opponent range.
+ */
+EquityResult estimate_equity_vs_range(
+    const std::vector<Card>& hero_cards,
+    const std::vector<Card>& board_cards,
+    const std::vector<RangeCombo>& opponent_range,
+    const std::vector<Card>& dead_cards,
+    int iterations,
+    std::uint64_t seed
+);
+
+/**
+ * Parses range entries like "AhAd:1,KsQs:0.5".
+ */
+std::vector<RangeCombo> parse_range_csv(const std::string& range_csv);
+
+/**
+ * Converts an equity result to a JSON string.
+ * The JSON string will be in the format of:
+ * { "wins": <wins>, 
+ *  "ties": <ties>, 
+ *  "losses": <losses>, 
+ *  "equity": <win_probability + (tie_probability * 0.5)>,
+ * "iterations": <iterations>, 
+ * "win_probability": <win_probability>, 
+ * "tie_probability": <tie_probability>, 
+ * "loss_probability": <loss_probability> 
+ * }
+ */
+std::string equity_to_json(const EquityResult& result);
+
+}

telltale/native/poker_solver/evaluator.cpp

@@ -0,0 +1,259 @@
+#include "evaluator.hpp"
+
+#include <algorithm>
+#include <array>
+#include <map>
+#include <sstream>
+#include <stdexcept>
+
+namespace telltale::poker {
+
+namespace {
+
+/**
+ * Converts a card rank character to its corresponding integer value. 
+ * For example, 'A' returns 14, 'K' returns 13, 'Q' returns 12, etc. 
+ */
+int rank_value(char rank) {
+    const std::string ranks = "23456789TJQKA";
+    const auto index = ranks.find(rank);
+    if (index == std::string::npos) {
+        throw std::invalid_argument("invalid card rank");
+    }
+    return static_cast<int>(index) + 2;
+}
+
+/**
+ * Returns the label for a hand rank category. 
+ * For example, 8 returns "straight flush", 7 returns "four of a kind", etc. 
+ */
+std::string label_for_category(int category) {
+    static const std::array<std::string, 9> labels = {
+        "high card",
+        "one pair",
+        "two pair",
+        "three of a kind",
+        "straight",
+        "flush",
+        "full house",
+        "four of a kind",
+        "straight flush",
+    };
+    return labels.at(category);
+}
+
+/**
+ * Returns the ranks with a count other than the excluded count. 
+ * For example, if the counts are {2: 2, 3: 2, 4: 1}, then the ranks with count other than 2 are {3, 4}. 
+ * This will be used to get the kickers for a hand rank. 
+ */
+std::vector<int> ranks_with_count_other_than(const std::map<int, int>& counts, int excluded_count) {
+    std::vector<int> ranks;
+    for (const auto& [rank, count] : counts) {
+        if (count != excluded_count) {
+            ranks.push_back(rank);
+        }
+    }
+    std::sort(ranks.begin(), ranks.end(), std::greater<int>());
+    return ranks;
+}
+
+/**
+ * Appends a vector of integers to a string stream as a JSON array. 
+ * For example, [1, 2, 3] will be appended as "[1,2,3]". 
+ */
+void append_int_array(std::ostringstream& output, const std::vector<int>& values) {
+    output << "[";
+    for (std::size_t index = 0; index < values.size(); ++index) {
+        if (index > 0) {
+            output << ",";
+        }
+        output << values[index];
+    }
+    output << "]";
+}
+
+}
+
+/**
+ * Parses a card from a string. 
+ * The string should be two characters, the first being the rank and the second being the suit. 
+ * For example, "Ah" is the ace of hearts, "Ks" is the king of spades, "2c" is the 2 of clubs, etc. 
+ */
+Card parse_card(const std::string& value) {
+    if (value.size() != 2) {
+        throw std::invalid_argument("card must be two characters");
+    }
+    const char suit = value[1];
+    if (suit != 'c' && suit != 'd' && suit != 'h' && suit != 's') {
+        throw std::invalid_argument("invalid card suit");
+    }
+    return Card{rank_value(value[0]), suit};
+}
+
+
+/**
+ * Parses a list of cards from a CSV string. 
+ * For example, "Ah,Ks,2c" is the ace of hearts, the king of spades, and the 2 of clubs. 
+ * The cards are returned in the order they appear in the string. 
+ */
+std::vector<Card> parse_cards_csv(const char* values) {
+    std::vector<Card> cards;
+    if (values == nullptr || values[0] == '\0') {
+        return cards;
+    }
+    std::stringstream stream(values);
+    std::string item;
+    while (std::getline(stream, item, ',')) {
+        if (!item.empty()) {
+            cards.push_back(parse_card(item));
+        }
+    }
+    return cards;
+}
+
+/**
+ * Evaluates a 5-card hand and returns a HandRank object.
+ * You can read the note.md file for more detail and explanation on how this implementation works. 
+ */
+HandRank evaluate_5(const std::array<Card, 5>& cards) {
+    std::vector<int> values;
+    values.reserve(5);
+    std::map<int, int> counts;
+    bool is_flush = true;
+    const char suit = cards[0].suit;
+    for (const auto& card : cards) {
+        values.push_back(card.rank);
+        counts[card.rank] += 1;
+        if (card.suit != suit) {
+            is_flush = false;
+        }
+    }
+    std::sort(values.begin(), values.end(), std::greater<int>());
+
+    std::vector<int> unique_values = values;
+    unique_values.erase(std::unique(unique_values.begin(), unique_values.end()), unique_values.end());
+
+    bool is_straight = false;
+    int straight_high = 0;
+    if (unique_values.size() == 5) {
+        if (unique_values[0] - unique_values[4] == 4) {
+            is_straight = true;
+            straight_high = unique_values[0];
+        } else if (unique_values == std::vector<int>{14, 5, 4, 3, 2}) {
+            is_straight = true;
+            straight_high = 5;
+        }
+    }
+
+    std::vector<std::pair<int, int>> by_count;
+    for (const auto& [rank, count] : counts) {
+        by_count.emplace_back(rank, count);
+    }
+    std::sort(by_count.begin(), by_count.end(), [](const auto& left, const auto& right) {
+        if (left.second != right.second) {
+            return left.second > right.second;
+        }
+        return left.first > right.first;
+    });
+
+    if (is_straight && is_flush) {
+        return HandRank{8, {straight_high}, label_for_category(8)};
+    }
+    if (by_count[0].second == 4) {
+        return HandRank{7, {by_count[0].first, by_count[1].first}, label_for_category(7)};
+    }
+    if (by_count[0].second == 3 && by_count[1].second == 2) {
+        return HandRank{6, {by_count[0].first, by_count[1].first}, label_for_category(6)};
+    }
+    if (is_flush) {
+        return HandRank{5, values, label_for_category(5)};
+    }
+    if (is_straight) {
+        return HandRank{4, {straight_high}, label_for_category(4)};
+    }
+    if (by_count[0].second == 3) {
+        auto kickers = ranks_with_count_other_than(counts, 3);
+        std::vector<int> tiebreakers = {by_count[0].first};
+        tiebreakers.insert(tiebreakers.end(), kickers.begin(), kickers.end());
+        return HandRank{3, tiebreakers, label_for_category(3)};
+    }
+    if (by_count[0].second == 2 && by_count[1].second == 2) {
+        const int high_pair = std::max(by_count[0].first, by_count[1].first);
+        const int low_pair = std::min(by_count[0].first, by_count[1].first);
+        return HandRank{2, {high_pair, low_pair, by_count[2].first}, label_for_category(2)};
+    }
+    if (by_count[0].second == 2) {
+        auto kickers = ranks_with_count_other_than(counts, 2);
+        std::vector<int> tiebreakers = {by_count[0].first};
+        tiebreakers.insert(tiebreakers.end(), kickers.begin(), kickers.end());
+        return HandRank{1, tiebreakers, label_for_category(1)};
+    }
+    return HandRank{0, values, label_for_category(0)};
+}
+
+/**
+ * Evaluates a 7-card hand and returns a HandRank object.
+ * First, we will need to iterate over all possible combinations of 5 cards and evaluate the hand rank.
+ * Then, we will compare the hand rank to the best possible hand rank and return the best hand rank.
+ */
+HandRank evaluate_7(const std::vector<Card>& cards) {
+    if (cards.size() < 7) {
+        throw std::invalid_argument("evaluate_7 requires at least seven cards");
+    }
+    bool has_best = false;
+    HandRank best;
+    for (std::size_t a = 0; a < cards.size() - 4; ++a) {
+        for (std::size_t b = a + 1; b < cards.size() - 3; ++b) {
+            for (std::size_t c = b + 1; c < cards.size() - 2; ++c) {
+                for (std::size_t d = c + 1; d < cards.size() - 1; ++d) {
+                    for (std::size_t e = d + 1; e < cards.size(); ++e) {
+                        const std::array<Card, 5> hand = {cards[a], cards[b], cards[c], cards[d], cards[e]};
+                        const HandRank rank = evaluate_5(hand);
+                        if (!has_best || compare_ranks(rank, best) > 0) {
+                            best = rank;
+                            has_best = true;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return best;
+}
+
+/**
+ * Compares two hand ranks.
+ * Returns -1 if the left hand rank is lower than the right hand rank, 
+ * 0 if they are equal, and 1 if the left hand rank is higher than the right hand rank. 
+ */
+int compare_ranks(const HandRank& left, const HandRank& right) {
+    if (left.category != right.category) {
+        return left.category > right.category ? 1 : -1;
+    }
+    const std::size_t limit = std::min(left.tiebreakers.size(), right.tiebreakers.size());
+    for (std::size_t index = 0; index < limit; ++index) {
+        if (left.tiebreakers[index] != right.tiebreakers[index]) {
+            return left.tiebreakers[index] > right.tiebreakers[index] ? 1 : -1;
+        }
+    }
+    if (left.tiebreakers.size() == right.tiebreakers.size()) {
+        return 0;
+    }
+    return left.tiebreakers.size() > right.tiebreakers.size() ? 1 : -1;
+}
+
+/**
+ * Converts a hand rank to a JSON string.
+ * The JSON string will be in the format of:
+ * { "category": <category>, "tiebreakers": [<tiebreakers>], "label": "<label>" }
+ */
+std::string rank_to_json(const HandRank& rank) {
+    std::ostringstream output;
+    output << "{\"category\":" << rank.category << ",\"tiebreakers\":";
+    append_int_array(output, rank.tiebreakers);
+    output << ",\"label\":\"" << rank.label << "\"}";
+    return output.str();
+}
+
+}

telltale/native/poker_solver/evaluator.hpp

@@ -0,0 +1,64 @@
+#pragma once
+
+#include <array>
+#include <string>
+#include <vector>
+
+namespace telltale::poker {
+
+/**
+ * Describes a card in a poker hand. 
+ */
+struct Card {
+    int rank;
+    char suit;
+};
+
+/**
+ * Describes a hand rank in a poker hand. 
+ * There are 9 categories of hand ranks in poker, and they are ordered from highest (straight flush) to lowest (high card). 
+ */
+struct HandRank {
+    int category; // the category of the hand rank. 
+    std::vector<int> tiebreakers; // tiebreakers are used to break ties within a same category. 
+    std::string label; // the label of the hand rank. 
+};
+
+/**
+ * Parses a card from a string. 
+ * The string should be two characters, the first being the rank and the second being the suit. 
+ * For example, "Ah" is the ace of hearts, "Ks" is the king of spades, "2c" is the 2 of clubs, etc. 
+ */
+Card parse_card(const std::string& value);
+
+/**
+ * Parses a list of cards from a CSV string. 
+ * For example, "Ah,Ks,2c" is the ace of hearts, the king of spades, and the 2 of clubs. 
+ * The cards are returned in the order they appear in the string. 
+ */
+std::vector<Card> parse_cards_csv(const char* values);
+
+
+/**
+ * Evaluates a 5-card hand. This follws the same logic as the Python implementation. 
+ */
+HandRank evaluate_5(const std::array<Card, 5>& cards);
+
+/**
+ * Evaluates a 7-card hand. 
+ */
+HandRank evaluate_7(const std::vector<Card>& cards);
+
+/**
+ * Compares two hand ranks.
+ * Returns -1 if the left hand rank is lower than the right hand rank, 
+ * 0 if they are equal, and 1 if the left hand rank is higher than the right hand rank. 
+ */
+int compare_ranks(const HandRank& left, const HandRank& right);
+
+/**
+ * Converts a hand rank to a JSON string. 
+ */ 
+std::string rank_to_json(const HandRank& rank);
+
+}

telltale/native/poker_solver/note.md

@@ -0,0 +1,205 @@
+In this document, I want to go through the poker solver and attempt to explain how the whole thing works. I want to do this so that a) I know that I understand how it all works and b) someone who is looking over this codebase can get a quick introduction to how it works. 
+
+The main idea in making this solver is that I don't want to create the most game theory optimal (GTO) poker solver. This is a small game where you are playing with small LLMs. I want the personality of the agents that are playing the game, the way the game is being played, and things like that to also dictate the strategy of any individial agent. So, there will definitely be cases where the solver will not theoretically/qunatitatively reflect the most sound and reasonable play. But, that is okay. This solver will just serve as a way for the agents to get actual objective information about the game, so that they can reason about what their next move should be on their own. 
+
+## Evaluating a hand of poker
+
+The first thing that we will need to understand is how to evaluate a hand of poker. Out of the 2 hole cards that each player has, and the 5 community cards that is common to all players, we will need to find the best-5 card hand. We will evaluate this by ranking each possible combination and comparing it to the best possible hand that you can make. To do that, we will use a `HandRank` class that will have category, tiebreakers, and label as its attributes. There are only 9 categories of cards in No-limit Texas Hold'em, so we will rank them according to the strength of the hand as follows: 
+
+
+| Category | Label           | Tiebreakers (in order)              |
+| -------- | --------------- | ----------------------------------- |
+| 0        | high card       | all five ranks, high to low         |
+| 1        | one pair        | pair rank, then kickers high to low |
+| 2        | two pair        | high pair, low pair, kicker         |
+| 3        | three of a kind | trips rank, then kickers            |
+| 4        | straight        | high card of the straight           |
+| 5        | flush           | all five ranks, high to low         |
+| 6        | full house      | trips rank, then pair rank          |
+| 7        | four of a kind  | quad rank, then kicker              |
+| 8        | straight flush  | high card of the straight           |
+
+
+A good thing about this is that a higher category always beats a lower category. And, for cards in the same category, we can just use the tiebreaker cards. Therefore, once we have a `HandRank`, comparing two hands is just a basic comparison:
+
+1. Compare `category` first. A higher category always wins.
+2. If categories are equal, compare `tiebreakers` one element at a time, left to right.
+3. If all compared tiebreakers match, the hands tie.
+
+`evaluate_5()` takes a hand and returns the HandRank object for it. To do that, it first collects some basic facts about the five cards: how many of each rank appear, whether all five cards share the same suit (a flush), and whether the distinct ranks form a consecutive run (a straight), with a special case for the wheel straight `A-2-3-4-5` where the ace plays low and the high card is 5. It then walks down the category list from strongest to weakest straight and returns as soon as it finds a match, filling in the appropriate tiebreakers along the way. For hands with pairs or better, kickers are the ranks that are not part of the main combination, sorted from highest to lowest.
+
+In Hold'em we rarely evaluate exactly five cards on their own. `evaluate_7()` takes all seven cards (two hole cards plus five community cards), tries every possible five-card subset, there are 21 of them, runs `evaluate_5()` on each, and keeps the strongest result.
+
+## Some Important Decision Features to Know About
+
+This was just basic hand evaluation. It is important now as we move forward to get to something that will actually help us give some information about how strong one's current position is at a given moment and can help us in our decision making.
+
+### Equity
+
+Equity tries to answer the question that given what we know and what is still unknown, **what share of the pot do we expect to win** if the hand runs out?
+
+Conceptually:
+
+$$
+\text{equity} = \frac{\mathbb{E}[\text{amount won by hero}]}{\text{total pot}}
+$$
+
+We never compute that expectation in closed form. Instead, `estimate_equity()` in `equity.cpp` runs a **Monte Carlo simulation**, where we complete the hand thousands of times at random, count outcomes, and use sample frequencies as probabilities. The same `EquityResult` shape is also returned by `estimate_equity_vs_range()`, which samples opponent hands from a **weighted range** instead of uniformly from the deck.
+
+Before any trial starts, the code builds a **known card set** = hero + board + dead cards, checks that no card appears twice, and builds a **remaining deck** of everything else in the standard 52-card deck.
+
+It also computes how many unknown cards each trial needs:
+
+$$
+\text{boardneeded} = 5 - |\text{board}|, \quad
+\text{cardsneeded} = \text{boardneeded} + 2 \cdot \text{numopponents}
+$$
+
+If `cardsneeded` exceeds the remaining deck size, estimation throws an error saying that there are not enough cards left to deal.
+
+#### Standard mode: `estimate_equity()`
+
+This is what `PokerPolicyWriter` calls during live play. Opponent hole cards are **uniformly random**: any live two-card combo is equally likely, conditional on not conflicting with known cards.
+
+**One trial:**
+
+1. Shuffle the remaining deck with the seeded RNG.
+2. Deal `boardneeded` cards off the top to complete the board to five cards.
+3. Evaluate the hero with `evaluate_7(hero + board)`.
+4. For each opponent, deal two hole cards from the deck and evaluate with `evaluate_7(opponent + board)`.
+5. Classify the trial:
+   - **Loss**: at least one opponent's hand beats the hero (comparison stops early on the first loss).
+   - **Tie**: no opponent beats the hero, but at least one opponent ties.
+   - **Win**: the hero has the sole best hand.
+
+Step 5 is important for multiway pots. The hero only wins a trial when nobody beats them and nobody chops. One player outdrawing us is enough for the whole trial to count as a loss, even if we would have tied someone else.
+
+After $N$ iterations:
+
+$$
+P(\text{win}) = \frac{\text{wins}}{N}, \quad
+P(\text{tie}) = \frac{\text{ties}}{N}, \quad
+P(\text{loss}) = \frac{\text{losses}}{N}
+$$
+
+Hero equity combines wins and ties:
+
+$$
+\text{heroequity} = P(\text{win}) + 0.5 \cdot P(\text{tie})
+$$
+
+The factor of $\frac{1}{2}$ on ties reflects chopping: if we tie for the best hand, we only recover half of the contested pot on average.
+
+#### Range mode: `estimate_equity_vs_range()`
+
+The second entry point models a **single opponent** whose hand is drawn from a weighted combo list rather than uniformly from the deck. Each `RangeCombo` is two cards plus a positive weight, e.g. `AhAd:1,KsQs:0.5` via `parse_range_csv()`.
+
+**One trial:**
+
+1. Filter the range to **live combos**: drop any combo that shares a card with hero, board, or dead cards.
+2. Sample one combo with probability proportional to its weight.
+3. Remove that combo's two cards from the deck, shuffle what is left, and deal out the remaining board cards.
+4. Compare hero vs the sampled opponent hand head-to-head (win / tie / loss).
+
+Range mode is heads-up only: there is no `num_opponents` parameter because the opponent hand is defined by the range sample. If every combo conflicts with known cards, estimation throws (`opponent range has no live combos`).
+
+### Pot Odds
+
+Equity tells us how strong our hand is, but pot odds tell us whether the price of continuing is worth paying. When we face a bet, we need to put in more chips to stay in the hand. Pot odds measure that cost as a fraction of the total pot we are fighting for after we call.
+
+If there is nothing to call, pot odds are zero. Otherwise:
+
+$$
+\text{potodds} = \frac{\text{amounttocall}}{\text{potsize} + \text{amounttocall}}
+$$
+
+The denominator is the pot after we call, because that is the total prize we are contesting once we pay the outstanding amount. For example, if the pot is 100 and we must call 50, then:
+
+$$
+\text{potodds} = \frac{50}{100 + 50} = \frac{1}{3} \approx 0.33
+$$
+
+So we are risking one third of the final pot to win the whole thing. In the simplest heads-up, one-street model, a call is roughly break-even when:
+
+$$
+\text{heroequity} \approx \text{potodds}
+$$
+
+If our equity is below pot odds, calling loses money on average; if it is above, calling wins money on average. Real poker is more complicated because future betting streets exist, but this is still a useful baseline.
+
+### Stack-to-Pot Ratio
+
+Stack-to-pot ratio (SPR) measures how deep our remaining stack is relative to the pot. It tells us how much room we have left to bet on later streets, and how close we are to being committed.
+
+$$
+\text{SPR} = \frac{\text{herostack}}{\text{potsize}}
+$$
+
+If the pot is empty, we define SPR as the hero's full stack so the value is still meaningful as a large number.
+
+A low SPR means the pot is already large compared to what we have left. For example, $\text{SPR} = 0.8$ means our stack is only 80% of the pot, one more reasonable bet can put us all in. A high SPR means we are still deep relative to the pot and have more room to maneuver.
+
+### Board Texture
+
+Board texture is a label for how coordinated and dangerous the community cards are. Two players can have the same equity number on very different boards: a dry rainbow flop is stable, while a monotone connected flop creates many straight and flush possibilities for opponents we have not seen yet.
+
+`board_texture()` in `policy.py` assigns one label once at least three community cards are out. Before the flop, or with fewer than three board cards, the texture is `"dry"`.
+
+The function looks at three properties of the board:
+
+1. **Suit pattern**: how many distinct suits appear.
+2. **Pairing**: whether any rank appears more than once.
+3. **Connectivity**: whether the ranks contain a three-card straight window (ranks within a span of 4, including the wheel case $A$-$2$-$3$-$4$-$5$).
+
+The labels are assigned in priority order:
+
+
+| Label       | Meaning                                         |
+| ----------- | ----------------------------------------------- |
+| `monotone`  | All board cards share one suit                  |
+| `wet`       | Connected board that is also two-tone or paired |
+| `connected` | Straight-draw potential, but not wet            |
+| `paired`    | At least one paired rank on board               |
+| `two_tone`  | Exactly two suits on board                      |
+| `dry`       | None of the above                               |
+
+
+`"wet"` boards are the most volatile: they combine connectivity with flush or full-house texture. `"dry"` boards change less when new cards arrive.
+
+# How does the Solver Recommend?
+
+`recommend_action_json()` in `action_policy.cpp` turns `DecisionFeatures` (equity, pot odds, SPR, board texture, legal actions, and history) into a JSON recommendation. It does **not** run CFR or build opponent ranges. It scores each legal action with some weights, normalizes them into probabilities, and returns the top pick plus metadata for agents and prompts.
+
+`PokerPolicyWriter` in `policy.py` is the usual entry point: estimate equity -> build features -> call `native.recommend_action()` → wrap as `PokerDecision`.
+
+## How the recommendation is built
+
+- The policy uses two different weight tables: passive line (check / bet / all-in) vs facing a bet (fold / call / raise / all-in). 
+- Each street has a value line (when to bet for value) and a raise line (when raising is reasonable):
+
+| Street | Value line | Raise line |
+| ------ | ---------- | ---------- |
+| preflop | 0.63 | 0.74 |
+| flop | 0.60 | 0.72 |
+| turn | 0.58 | 0.70 |
+| river | 0.55 | 0.67 |
+
+- If we must call and $\text{equity} + 0.03 < \text{potodds}$, the fold weight spikes. That encodes "don't pay more than our fair share of the pot without a cushion."
+- Wet and monotone boards apply a caution multiplier (down to 0.72) on bets and raises. Scary runouts deserve less eagerness to build pots without a strong hand.
+- With three or more players left, bet/raise weights are multiplied by 0.72. More opponents means someone is more likely to have us beat.
+- `previous_aggression_count` shrinks call/raise weights via an aggression penalty. Stations and repeat bettors are modeled as less attractive to engage lightly.
+- `street_action_count` adds a small pressure bonus to betting weights. Repeated action on a street nudges toward continuing the story with a bet.
+- All-in only gets meaningful weight when equity is very high (>= 0.82–0.84 depending on line) and SPR is shallow (<= 1.15-1.25). Deep stacks with medium strength should not default to shoving.
+- We, will then divide each action's weight by the sum. If nothing qualified, fall back to a uniform distribution over legal actions.
+- We will then pick `suggested_action`, the highest probability wins. `decision_margin` is the gap to the runner-up; `confidence` blends margin with $|\text{equity} - \text{potodds}|$.
+- `suggested_amount` defaults to roughly half-pot (clamped to min-raise and stack). `amount_options` exposes small / medium / large / all-in chip counts from pot fractions.
+
+## Extra output buckets
+
+| Field | Buckets | Purpose |
+| ----- | ------- | ------- |
+| `hand_strength_bucket` | weak (< 0.42), medium, strong (<= 0.62), monster (>= 0.82) | Plain-language hand strength for prompts |
+| `spr_bucket` | low (<= 1.5), medium (<= 4.0), deep | How committed we are relative to the pot |
+| `abstract_actions` | fold, check, call, bet_33/66/100, raise_2_5x, raise_pot, all_in | Advisory sizing vocabulary when those lines are legal |
+| `risk_label` | low / medium / high | Rough risk of the top action given SPR, board, and action type |
+

telltale/poker/__init__.py

@@ -0,0 +1,3 @@
+from telltale.poker.policy import PokerDecision, PokerPolicyConfig, PokerPolicyWriter
+
+__all__ = ["PokerDecision", "PokerPolicyConfig", "PokerPolicyWriter"]

telltale/poker/native.py

@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+import ctypes
+from dataclasses import dataclass
+import hashlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from telltale.game.cards import Card
+
+
+CardLike = Card | str
+_ROOT = Path(__file__).resolve().parents[2]
+_SOURCE_DIR = _ROOT / "telltale" / "native" / "poker_solver"
+_BUILD_DIR = _ROOT / "build" / "native_poker_solver"
+_LIB_NAME = "libtelltale_poker_solver.dylib" if sys.platform == "darwin" else "libtelltale_poker_solver.so"
+_LIB_PATH = _BUILD_DIR / _LIB_NAME
+
+
+@dataclass(frozen=True)
+class HandRank:
+    category: int
+    tiebreakers: tuple[int, ...]
+    label: str
+
+    def as_tuple(self) -> tuple[int, ...]:
+        return (self.category, *self.tiebreakers)
+
+
+@dataclass(frozen=True)
+class EquityResult:
+    wins: int
+    ties: int
+    losses: int
+    iterations: int
+    win_probability: float
+    tie_probability: float
+    loss_probability: float
+
+    @property
+    def equity(self) -> float:
+        return self.win_probability + (self.tie_probability * 0.5)
+
+
+@dataclass(frozen=True)
+class RangeCombo:
+    first: CardLike
+    second: CardLike
+    weight: float = 1.0
+
+
+@dataclass(frozen=True)
+class DecisionFeatures:
+    street: str
+    hero_equity: float
+    pot_size: int
+    amount_to_call: int
+    pot_odds: float
+    stack_to_pot_ratio: float
+    players_remaining: int
+    can_check: bool
+    legal_actions: tuple[str, ...]
+    hero_stack: int = 0
+    minimum_raise_amount: int = 1
+    board_texture: str = "dry"
+    street_action_count: int = 0
+    previous_aggression_count: int = 0
+
+
+@dataclass(frozen=True)
+class PolicyRecommendation:
+    probabilities: dict[str, float]
+    suggested_action: str
+    suggested_amount: int
+    equity: float
+    pot_odds: float
+    confidence: float
+    explanation: str
+    risk_label: str = "low"
+    board_texture: str = "dry"
+    decision_margin: float = 0.0
+    amount_options: dict[str, int] | None = None
+    hand_strength_bucket: str = "medium"
+    spr_bucket: str = "medium"
+    abstract_actions: tuple[str, ...] = ()
+
+
+class NativePokerSolver:
+    def estimate_equity(
+        self,
+        hero_cards: Sequence[CardLike],
+        board_cards: Sequence[CardLike] = (),
+        num_opponents: int = 1,
+        dead_cards: Sequence[CardLike] | None = None,
+        iterations: int = 1000,
+        seed: int | str | bytes | None = None,
+        opponent_count: int | None = None,
+        simulations: int | None = None,
+    ) -> EquityResult:
+        if opponent_count is not None:
+            num_opponents = opponent_count
+        if simulations is not None:
+            iterations = simulations
+        return estimate_equity(
+            hero_cards=hero_cards,
+            board_cards=board_cards,
+            num_opponents=num_opponents,
+            dead_cards=dead_cards,
+            iterations=iterations,
+            seed=seed,
+        )
+
+    def estimate_equity_vs_range(
+        self,
+        hero_cards: Sequence[CardLike],
+        board_cards: Sequence[CardLike],
+        opponent_range: Sequence[RangeCombo],
+        dead_cards: Sequence[CardLike] | None = None,
+        iterations: int = 1000,
+        seed: int | str | bytes | None = None,
+    ) -> EquityResult:
+        return estimate_equity_vs_range(
+            hero_cards=hero_cards,
+            board_cards=board_cards,
+            opponent_range=opponent_range,
+            dead_cards=dead_cards,
+            iterations=iterations,
+            seed=seed,
+        )
+
+
+def native_available() -> bool:
+    try:
+        _load_library()
+    except RuntimeError:
+        return False
+    return True
+
+
+def evaluate_7(cards: Sequence[CardLike]) -> HandRank:
+    data = _call_json("telltale_evaluate7", _cards_csv(cards))
+    return HandRank(data["category"], tuple(data["tiebreakers"]), data["label"])
+
+
+def compare_hands(cards_a: Sequence[CardLike], cards_b: Sequence[CardLike]) -> int:
+    data = _call_json("telltale_compare7", _cards_csv(cards_a), _cards_csv(cards_b))
+    return int(data["comparison"])
+
+
+def estimate_equity(
+    hero_cards: Sequence[CardLike],
+    board_cards: Sequence[CardLike],
+    num_opponents: int,
+    dead_cards: Sequence[CardLike] | None = None,
+    iterations: int = 1000,
+    seed: int | str | bytes | None = None,
+) -> EquityResult:
+    data = _call_json(
+        "telltale_estimate_equity",
+        _cards_csv(hero_cards),
+        _cards_csv(board_cards),
+        int(num_opponents),
+        _cards_csv(dead_cards or ()),
+        int(iterations),
+        _seed_to_uint64(seed),
+    )
+    return EquityResult(
+        wins=data["wins"],
+        ties=data["ties"],
+        losses=data["losses"],
+        iterations=data["iterations"],
+        win_probability=data["win_probability"],
+        tie_probability=data["tie_probability"],
+        loss_probability=data["loss_probability"],
+    )
+
+
+def estimate_equity_vs_range(
+    hero_cards: Sequence[CardLike],
+    board_cards: Sequence[CardLike],
+    opponent_range: Sequence[RangeCombo],
+    dead_cards: Sequence[CardLike] | None = None,
+    iterations: int = 1000,
+    seed: int | str | bytes | None = None,
+) -> EquityResult:
+    data = _call_json(
+        "telltale_estimate_equity_vs_range",
+        _cards_csv(hero_cards),
+        _cards_csv(board_cards),
+        _range_csv(opponent_range),
+        _cards_csv(dead_cards or ()),
+        int(iterations),
+        _seed_to_uint64(seed),
+    )
+    return EquityResult(
+        wins=data["wins"],
+        ties=data["ties"],
+        losses=data["losses"],
+        iterations=data["iterations"],
+        win_probability=data["win_probability"],
+        tie_probability=data["tie_probability"],
+        loss_probability=data["loss_probability"],
+    )
+
+
+def recommend_action(features: DecisionFeatures) -> PolicyRecommendation:
+    data = _call_json(
+        "telltale_recommend_action",
+        features.street,
+        float(features.hero_equity),
+        int(features.pot_size),
+        int(features.amount_to_call),
+        float(features.pot_odds),
+        float(features.stack_to_pot_ratio),
+        int(features.players_remaining),
+        bool(features.can_check),
+        ",".join(features.legal_actions),
+        int(features.hero_stack),
+        int(features.minimum_raise_amount),
+        features.board_texture,
+        int(features.street_action_count),
+        int(features.previous_aggression_count),
+    )
+    return PolicyRecommendation(
+        probabilities={str(action): float(probability) for action, probability in data["probabilities"].items()},
+        suggested_action=str(data["suggested_action"]),
+        suggested_amount=int(data["suggested_amount"]),
+        equity=float(data["equity"]),
+        pot_odds=float(data["pot_odds"]),
+        confidence=float(data["confidence"]),
+        explanation=str(data["explanation"]),
+        risk_label=str(data.get("risk_label", "low")),
+        board_texture=str(data.get("board_texture", features.board_texture)),
+        decision_margin=float(data.get("decision_margin", 0.0)),
+        amount_options={str(label): int(amount) for label, amount in data.get("amount_options", {}).items()},
+        hand_strength_bucket=str(data.get("hand_strength_bucket", "medium")),
+        spr_bucket=str(data.get("spr_bucket", "medium")),
+        abstract_actions=tuple(str(action) for action in data.get("abstract_actions", ())),
+    )
+
+
+def _load_library() -> ctypes.CDLL:
+    if not _LIB_PATH.exists() or _native_sources_are_newer():
+        _build_library()
+    library = ctypes.CDLL(str(_LIB_PATH))
+    library.telltale_evaluate7.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int]
+    library.telltale_evaluate7.restype = ctypes.c_int
+    library.telltale_compare7.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int]
+    library.telltale_compare7.restype = ctypes.c_int
+    library.telltale_estimate_equity.argtypes = [
+        ctypes.c_char_p,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_ulonglong,
+        ctypes.c_char_p,
+        ctypes.c_int,
+    ]
+    library.telltale_estimate_equity.restype = ctypes.c_int
+    library.telltale_estimate_equity_vs_range.argtypes = [
+        ctypes.c_char_p,
+        ctypes.c_char_p,
+        ctypes.c_char_p,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_ulonglong,
+        ctypes.c_char_p,
+        ctypes.c_int,
+    ]
+    library.telltale_estimate_equity_vs_range.restype = ctypes.c_int
+    library.telltale_recommend_action.argtypes = [
+        ctypes.c_char_p,
+        ctypes.c_double,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_double,
+        ctypes.c_double,
+        ctypes.c_int,
+        ctypes.c_bool,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_int,
+    ]
+    library.telltale_recommend_action.restype = ctypes.c_int
+    return library
+
+
+def _build_library() -> None:
+    _BUILD_DIR.mkdir(parents=True, exist_ok=True)
+    command = [
+        "c++",
+        "-std=c++17",
+        "-O3",
+        "-shared",
+        "-fPIC",
+        str(_SOURCE_DIR / "bindings.cpp"),
+        str(_SOURCE_DIR / "evaluator.cpp"),
+        str(_SOURCE_DIR / "equity.cpp"),
+        str(_SOURCE_DIR / "action_policy.cpp"),
+        "-o",
+        str(_LIB_PATH),
+    ]
+    try:
+        subprocess.run(command, check=True, capture_output=True, text=True)
+    except (OSError, subprocess.CalledProcessError) as error:
+        stderr = getattr(error, "stderr", "")
+        raise RuntimeError(f"native poker solver build failed: {stderr}") from error
+
+
+def _native_sources_are_newer() -> bool:
+    if not _LIB_PATH.exists():
+        return True
+    library_mtime = _LIB_PATH.stat().st_mtime
+    for source in _SOURCE_DIR.glob("*.*"):
+        if source.suffix in {".cpp", ".hpp"} and source.stat().st_mtime > library_mtime:
+            return True
+    return False
+
+
+def _call_json(function_name: str, *args) -> dict:
+    library = _load_library()
+    function = getattr(library, function_name)
+    encoded_args = [_encode_arg(arg) for arg in args]
+    output = ctypes.create_string_buffer(4096)
+    status = function(*encoded_args, output, ctypes.sizeof(output))
+    if status > ctypes.sizeof(output):
+        output = ctypes.create_string_buffer(status)
+        status = function(*encoded_args, output, ctypes.sizeof(output))
+    if status != 0:
+        raise RuntimeError(f"native call {function_name} failed with status {status}")
+    data = json.loads(output.value.decode("utf-8"))
+    if "error" in data:
+        raise ValueError(data["error"])
+    return data
+
+
+def _encode_arg(value):
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    return value
+
+
+def _cards_csv(cards: Sequence[CardLike]) -> str:
+    return ",".join(str(card) for card in cards)
+
+
+def _range_csv(opponent_range: Sequence[RangeCombo]) -> str:
+    return ",".join(
+        f"{combo.first}{combo.second}:{float(combo.weight)}"
+        for combo in opponent_range
+    )
+
+
+def _seed_to_uint64(seed: int | str | bytes | None) -> int:
+    if seed is None:
+        return 0
+    if isinstance(seed, int):
+        return seed % (2**64)
+    if isinstance(seed, str):
+        seed = seed.encode("utf-8")
+    digest = hashlib.sha256(seed).digest()
+    return int.from_bytes(digest[:8], "little")

telltale/poker/policy.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from telltale.game.holdem import ActionType, HandState, PlayerState
+from telltale.poker import native
+
+
+RANK_ORDER = "23456789TJQKA"
+
+
+@dataclass(frozen=True)
+class PokerPolicyConfig:
+    simulations: int = 1_500
+
+
+@dataclass(frozen=True)
+class PokerDecision:
+    action: ActionType
+    amount: int = 0
+    equity: float = 0.0
+    pot_odds: float = 0.0
+    reason: str = ""
+
+
+class PokerPolicyWriter:
+    """Writes solver equity into legal Hold'em actions."""
+
+    def __init__(
+        self,
+        solver: native.NativePokerSolver | None = None,
+        config: PokerPolicyConfig | None = None,
+    ):
+        self.solver = solver or native.NativePokerSolver()
+        self.config = config or PokerPolicyConfig()
+
+    def choose_action(
+        self,
+        hand: HandState,
+        player_id: str | None = None,
+        seed: int | str | bytes | None = None,
+    ) -> PokerDecision:
+        player = _actor_or_player(hand, player_id)
+        legal = hand.legal_actions(player.player_id)
+        if not legal:
+            return PokerDecision(ActionType.CHECK, reason="no legal betting action")
+
+        opponent_count = _active_opponent_count(hand, player)
+        result = self.solver.estimate_equity(
+            player.hole_cards,
+            hand.board_cards,
+            num_opponents=opponent_count,
+            iterations=self.config.simulations,
+            seed=seed,
+        )
+        pot_odds = _pot_odds(hand, player)
+        outstanding = hand.current_max_bet() - player.current_bet
+        features = native.DecisionFeatures(
+            street=hand.street.value,
+            hero_equity=result.equity,
+            pot_size=sum(hand.pot_contributions.values()),
+            amount_to_call=outstanding,
+            pot_odds=pot_odds,
+            stack_to_pot_ratio=_stack_to_pot_ratio(hand, player),
+            players_remaining=opponent_count + 1,
+            can_check=ActionType.CHECK in legal,
+            legal_actions=tuple(sorted(action.value for action in legal)),
+            hero_stack=player.stack,
+            minimum_raise_amount=hand.minimum_raise_amount,
+            board_texture=board_texture(hand),
+            street_action_count=_street_action_count(hand),
+            previous_aggression_count=_previous_aggression_count(hand),
+        )
+        recommendation = native.recommend_action(features)
+        chosen = ActionType(recommendation.suggested_action)
+
+        if chosen in {ActionType.BET, ActionType.RAISE}:
+            amount = _legal_bet_or_raise_amount(hand, player, chosen, recommendation.suggested_amount)
+        elif chosen == ActionType.ALL_IN:
+            amount = player.stack
+        else:
+            amount = 0
+        return PokerDecision(
+            chosen,
+            amount=amount,
+            equity=result.equity,
+            pot_odds=pot_odds,
+            reason=recommendation.explanation,
+        )
+
+    def apply_action(
+        self,
+        hand: HandState,
+        player_id: str | None = None,
+        seed: int | str | bytes | None = None,
+    ) -> PokerDecision:
+        decision = self.choose_action(hand, player_id=player_id, seed=seed)
+        hand.apply_action(decision.action, amount=decision.amount, player_id=player_id)
+        return decision
+
+
+def _actor_or_player(hand: HandState, player_id: str | None) -> PlayerState:
+    if player_id is None:
+        if hand.current_actor_index is None:
+            raise ValueError("there is no current actor")
+        return hand.players[hand.current_actor_index]
+    for player in hand.players:
+        if player.player_id == player_id:
+            return player
+    raise ValueError(f"unknown player id: {player_id}")
+
+
+def _active_opponent_count(hand: HandState, player: PlayerState) -> int:
+    opponents = 0
+    for other in hand.players:
+        if other.player_id != player.player_id and not other.has_folded:
+            opponents += 1
+    return max(1, opponents)
+
+
+def _pot_odds(hand: HandState, player: PlayerState) -> float:
+    outstanding = hand.current_max_bet() - player.current_bet
+    if outstanding <= 0:
+        return 0.0
+    pot = sum(hand.pot_contributions.values())
+    return outstanding / (pot + outstanding)
+
+
+def _legal_bet_or_raise_amount(
+    hand: HandState,
+    player: PlayerState,
+    action: ActionType,
+    suggested_amount: int,
+) -> int:
+    if action == ActionType.BET:
+        return min(player.stack, max(hand.minimum_raise_amount, suggested_amount))
+    if action == ActionType.RAISE:
+        outstanding = hand.current_max_bet() - player.current_bet
+        minimum_amount = outstanding + hand.minimum_raise_amount
+        return min(player.stack, max(minimum_amount, suggested_amount))
+    return 0
+
+
+def _stack_to_pot_ratio(hand: HandState, player: PlayerState) -> float:
+    pot = sum(hand.pot_contributions.values())
+    if pot <= 0:
+        return float(player.stack)
+    return player.stack / pot
+
+
+def board_texture(hand: HandState) -> str:
+    board = hand.board_cards
+    if len(board) < 3:
+        return "dry"
+
+    ranks = [_rank_value(card.rank) for card in board]
+    suits = [card.suit for card in board]
+    unique_suits = set(suits)
+    paired = len(set(ranks)) < len(ranks)
+    monotone = len(unique_suits) == 1
+    two_tone = len(unique_suits) == 2
+    connected = _is_connected(ranks)
+
+    if monotone:
+        return "monotone"
+    if connected and (two_tone or paired):
+        return "wet"
+    if connected:
+        return "connected"
+    if paired:
+        return "paired"
+    if two_tone:
+        return "two_tone"
+    return "dry"
+
+
+def _rank_value(rank: str) -> int:
+    return RANK_ORDER.index(rank) + 2
+
+
+def _is_connected(ranks: list[int]) -> bool:
+    unique = sorted(set(ranks))
+    if len(unique) < 3:
+        return False
+    for window_start in range(len(unique) - 2):
+        window = unique[window_start : window_start + 3]
+        if window[-1] - window[0] <= 4:
+            return True
+    if 14 in unique:
+        wheel = sorted({1 if rank == 14 else rank for rank in unique})
+        for window_start in range(len(wheel) - 2):
+            window = wheel[window_start : window_start + 3]
+            if window[-1] - window[0] <= 4:
+                return True
+    return False
+
+
+def _street_action_count(hand: HandState) -> int:
+    return sum(1 for record in hand.action_history if record.street == hand.street)
+
+
+def _previous_aggression_count(hand: HandState) -> int:
+    return sum(
+        1
+        for record in hand.action_history
+        if record.action in {ActionType.BET, ActionType.RAISE, ActionType.ALL_IN}
+    )

telltale/server/__init__.py

@@ -0,0 +1 @@
+

telltale/server/api.py

@@ -0,0 +1,591 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+from pathlib import Path
+from random import Random
+from typing import Any
+
+from telltale.agents.decision import AgentDecision, parse_agent_decision, validate_and_repair
+from telltale.agents.dialogue import PlayerUtterance
+from telltale.agents.memory import AgentMemory
+from telltale.agents.profiles import (
+    DEFAULT_FINAL_BOSS_ID,
+    AgentProfile,
+    get_agent_profile,
+    profiles_for_floor,
+)
+from telltale.agents.prompts import build_agent_prompt
+from telltale.agents.trace import TraceLogger
+from telltale.game.economy import RunState, RunStatus, derive_seed
+from telltale.game.floors import FLOOR_CONFIGS, FloorConfig
+from telltale.game.holdem import ActionType, HandState, PlayerState, PokerError, Street
+from telltale.game.perks import PERK_DEFINITIONS
+from telltale.models.llama_runtime import LocalTextRuntime, RuntimeSettings
+from telltale.models.stt import STTRuntime
+from telltale.models.tts import TTSRuntime
+from telltale.poker.policy import PokerDecision, PokerPolicyConfig, PokerPolicyWriter
+from telltale.server.events import EventBatch, EventBuilder
+
+
+HUMAN_PLAYER_ID = "player"
+DEMO_SEED = 77713
+
+
+@dataclass(frozen=True)
+class RunSettings:
+    model_mode: str | None = None
+    seed: int | None = None
+    tts_enabled: bool = False
+    stt_enabled: bool = False
+    trace_enabled: bool = True
+
+
+@dataclass(frozen=True)
+class TraceExport:
+    run_id: str
+    path: str | None
+    content: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class GameSession:
+    run: RunState
+    runtime: LocalTextRuntime
+    tts: TTSRuntime
+    stt: STTRuntime
+    trace: TraceLogger
+    policy: PokerPolicyWriter
+    sequence: int = 0
+    hand_counter: int = 0
+    dealer_index: int = 0
+    opponent_profiles: list[AgentProfile] | None = None
+    memories: dict[str, AgentMemory] | None = None
+    latest_speech: dict[str, str] | None = None
+    last_player_utterance: PlayerUtterance | None = None
+
+    def __post_init__(self) -> None:
+        self.opponent_profiles = self.opponent_profiles or []
+        self.memories = self.memories or {}
+        self.latest_speech = self.latest_speech or {}
+
+
+_SESSIONS: dict[str, GameSession] = {}
+
+
+def start_run(seed: int | None = None, settings: RunSettings | dict[str, Any] | None = None) -> dict[str, Any]:
+    run_settings = _coerce_settings(settings)
+    run_seed = seed if seed is not None else run_settings.seed
+    run = RunState.start(seed=run_seed, bankroll=260)
+    run.enter_current_floor()
+    runtime_settings = RuntimeSettings.from_env()
+    runtime_settings = RuntimeSettings(
+        mode=run_settings.model_mode or runtime_settings.mode,
+        model_name=runtime_settings.model_name,
+        gguf_path=runtime_settings.gguf_path,
+        context_size=runtime_settings.context_size,
+        max_tokens=runtime_settings.max_tokens,
+        temperature=runtime_settings.temperature,
+        seed=runtime_settings.seed,
+    )
+    session = GameSession(
+        run=run,
+        runtime=LocalTextRuntime(runtime_settings),
+        tts=TTSRuntime(enabled=run_settings.tts_enabled),
+        stt=STTRuntime(enabled=run_settings.stt_enabled),
+        trace=TraceLogger(run.run_id),
+        policy=PokerPolicyWriter(config=PokerPolicyConfig(simulations=250)),
+    )
+    _SESSIONS[run.run_id] = session
+    builder = EventBuilder(run.run_id, session.sequence)
+    builder.emit("run_started", seed=run.seed, bankroll=run.bankroll)
+    builder.emit("floor_intro", **_floor_payload(run))
+    _start_hand(session, builder)
+    batch = _continue_until_player_turn(session, builder)
+    return batch.public_state
+
+
+def list_floors() -> dict[str, Any]:
+    return {
+        "floors": [_floor_config_payload(floor) for floor in FLOOR_CONFIGS],
+        "total_floors": len(FLOOR_CONFIGS),
+    }
+
+
+def get_state(run_id: str) -> dict[str, Any]:
+    return _public_state(_get_session(run_id))
+
+
+def submit_player_action(
+    run_id: str,
+    action: str,
+    amount: int | None = None,
+    utterance: str | None = None,
+    audio: bytes | None = None,
+) -> dict[str, Any]:
+    session = _get_session(run_id)
+    builder = EventBuilder(run_id, session.sequence)
+    if audio:
+        transcription = session.stt.transcribe(audio)
+        if transcription.text and not utterance:
+            utterance = transcription.text
+        elif transcription.error:
+            builder.emit("stt_failed", error=transcription.error)
+    session.last_player_utterance = PlayerUtterance(raw_text=utterance or "")
+    hand = _require_hand(session)
+    if hand.street == Street.COMPLETE:
+        _resolve_completed_hand(session, builder)
+    else:
+        actor = _current_actor(hand)
+        if actor.player_id != HUMAN_PLAYER_ID:
+            raise ValueError("it is not the player's turn")
+        legal = {item.value for item in hand.legal_actions(HUMAN_PLAYER_ID)}
+        if action not in legal:
+            raise ValueError(f"{action} is not legal right now")
+        paid = _apply_action(hand, HUMAN_PLAYER_ID, ActionType(action), amount or 0)
+        builder.emit(
+            "action_taken",
+            player_id=HUMAN_PLAYER_ID,
+            name="You",
+            action=action,
+            amount=paid,
+            utterance=utterance or "",
+        )
+        if utterance:
+            session.latest_speech[HUMAN_PLAYER_ID] = utterance
+            builder.emit("player_spoke", player_id=HUMAN_PLAYER_ID, text=utterance)
+        if hand.street == Street.COMPLETE:
+            _resolve_completed_hand(session, builder)
+    session.sequence = builder.sequence
+    return _continue_until_player_turn(session, builder).to_dict()
+
+
+def continue_until_player_turn(run_id: str) -> dict[str, Any]:
+    session = _get_session(run_id)
+    builder = EventBuilder(run_id, session.sequence)
+    return _continue_until_player_turn(session, builder).to_dict()
+
+
+def choose_reward(run_id: str, perk_id: str) -> dict[str, Any]:
+    session = _get_session(run_id)
+    builder = EventBuilder(run_id, session.sequence)
+    session.run.choose_reward(perk_id)
+    builder.emit("reward_chosen", perk_id=perk_id)
+    if session.run.status == RunStatus.ACTIVE:
+        session.run.enter_current_floor()
+        builder.emit("floor_intro", **_floor_payload(session.run))
+        _start_hand(session, builder)
+    session.sequence = builder.sequence
+    return _continue_until_player_turn(session, builder).to_dict()
+
+
+def export_trace(run_id: str) -> dict[str, Any]:
+    session = _get_session(run_id)
+    path = str(session.trace.path) if session.trace.path.exists() else None
+    return TraceExport(run_id=run_id, path=path, content=session.trace.export_text()).to_dict()
+
+
+def transcribe_player_audio(run_id: str, audio: bytes) -> dict[str, Any]:
+    session = _get_session(run_id)
+    result = session.stt.transcribe(audio)
+    return {
+        "text": result.text,
+        "confidence": result.confidence,
+        "disabled": result.disabled,
+        "error": result.error,
+    }
+
+
+def get_tts_audio(audio_id: str) -> dict[str, Any]:
+    if "/" in audio_id or "\\" in audio_id or audio_id in {"", ".", ".."}:
+        raise ValueError("invalid audio id")
+    path = (Path("runs/tts_cache") / audio_id).resolve()
+    cache_root = Path("runs/tts_cache").resolve()
+    if cache_root not in path.parents:
+        raise ValueError("invalid audio id")
+    if not path.is_file():
+        raise KeyError(f"unknown audio id: {audio_id}")
+    return {"path": str(path), "mime_type": "audio/wav"}
+
+
+def reset_sessions() -> None:
+    _SESSIONS.clear()
+
+
+def _continue_until_player_turn(session: GameSession, builder: EventBuilder) -> EventBatch:
+    while session.run.status == RunStatus.ACTIVE and not session.run.awaiting_reward:
+        hand = _require_hand(session)
+        if hand.street == Street.COMPLETE:
+            _resolve_completed_hand(session, builder)
+            continue
+        actor = _current_actor(hand)
+        if actor.player_id == HUMAN_PLAYER_ID:
+            builder.emit("player_turn", legal_actions=_legal_actions_payload(hand), pot=_pot(hand))
+            break
+        _agent_turn(session, builder, actor)
+    session.sequence = builder.sequence
+    public_state = _public_state(session)
+    return EventBatch(session.run.run_id, list(builder.events), public_state)
+
+
+def _agent_turn(session: GameSession, builder: EventBuilder, actor: PlayerState) -> None:
+    hand = _require_hand(session)
+    profile = _profile_for_player(session, actor.player_id)
+    memory = session.memories.setdefault(profile.agent_id, AgentMemory.neutral(profile.agent_id))
+    legal = hand.legal_actions(actor.player_id)
+    solver_decision = session.policy.choose_action(
+        hand,
+        player_id=actor.player_id,
+        seed=derive_seed(session.run.seed, "policy", hand.hand_id, len(hand.action_history)),
+    )
+    public_state = hand.to_public_state(viewer_player_id=actor.player_id)
+    private_state = {
+        "hole_cards": [str(card) for card in actor.hole_cards],
+        "stack": actor.stack,
+        "hand_summary": _hand_summary(actor, hand),
+    }
+    utterance = session.last_player_utterance
+    prompt = build_agent_prompt(
+        profile,
+        memory,
+        public_state,
+        private_state,
+        solver_decision,
+        utterance,
+        legal,
+    )
+    generation = session.runtime.generate(
+        prompt,
+        context={
+            "agent_name": profile.name,
+            "suggested_action": solver_decision.action.value,
+            "suggested_amount": solver_decision.amount,
+            "player_utterance": utterance.raw_text if utterance else "",
+        },
+    )
+    repair_applied = False
+    repair_reason = ""
+    try:
+        decision = parse_agent_decision(generation.text)
+        decision = validate_and_repair(decision, legal, solver_decision)
+    except Exception as error:
+        repair_applied = True
+        repair_reason = f"model output repaired after parse/validation error: {error}"
+        decision = AgentDecision(
+            action=solver_decision.action,
+            amount=solver_decision.amount,
+            speech=f"{profile.name}: I will keep this legal.",
+            honest_rationale=solver_decision.reason or "The repaired action follows the solver recommendation.",
+            emotional_state="composed",
+            memory_delta=memory_delta_empty(),
+        )
+    before = memory.to_dict()
+    paid = _safe_apply_agent_decision(hand, actor.player_id, decision, solver_decision)
+    memory.apply_delta(decision.memory_delta)
+    after = memory.to_dict()
+    session.latest_speech[actor.player_id] = decision.speech
+    builder.emit(
+        "action_taken",
+        player_id=actor.player_id,
+        name=actor.name,
+        action=_action_value(decision.action),
+        amount=paid,
+    )
+    builder.emit("agent_spoke", player_id=actor.player_id, name=actor.name, text=decision.speech)
+    tts = session.tts.synthesize(decision.speech, profile.voice_id)
+    if tts.audio_path:
+        audio_id = Path(tts.audio_path).name
+        builder.emit(
+            "tts_ready",
+            player_id=actor.player_id,
+            audio_id=audio_id,
+            audio_url=f"/api/audio/{audio_id}",
+            mime_type=tts.mime_type,
+        )
+    elif tts.error and not tts.disabled:
+        builder.emit("tts_failed", player_id=actor.player_id, error=tts.error)
+    session.trace.record(
+        floor_index=session.run.floor_index,
+        hand_id=hand.hand_id,
+        action_index=len(hand.action_history),
+        agent_id=profile.agent_id,
+        public_state=public_state,
+        private_agent_state=private_state,
+        solver_recommendation=solver_decision,
+        player_utterance=utterance.to_dict() if utterance else None,
+        memory_before=before,
+        prompt=prompt,
+        raw_model_output=generation.text,
+        parsed_model_output=decision,
+        repair_applied=repair_applied,
+        repair_reason=repair_reason,
+        final_action=_action_value(decision.action),
+        final_amount=paid,
+        speech=decision.speech,
+        honest_rationale=decision.honest_rationale,
+        memory_delta=decision.memory_delta,
+        memory_after=after,
+        runtime_mode=session.runtime.mode,
+        model_metadata=generation.metadata | {
+            "tokens_per_second": generation.tokens_per_second,
+            "latency_ms": generation.latency_ms,
+        },
+    )
+    if hand.street == Street.COMPLETE:
+        _resolve_completed_hand(session, builder)
+
+
+def _safe_apply_agent_decision(
+    hand: HandState,
+    player_id: str,
+    decision: AgentDecision,
+    solver_decision: PokerDecision,
+) -> int:
+    try:
+        return _apply_action(hand, player_id, ActionType(_action_value(decision.action)), decision.amount)
+    except (PokerError, ValueError):
+        return _apply_action(hand, player_id, solver_decision.action, solver_decision.amount)
+
+
+def _apply_action(hand: HandState, player_id: str, action: ActionType, amount: int) -> int:
+    before = hand.pot_contributions[player_id]
+    hand.apply_action(action, amount=amount, player_id=player_id)
+    return hand.pot_contributions[player_id] - before
+
+
+def _resolve_completed_hand(session: GameSession, builder: EventBuilder) -> None:
+    hand = _require_hand(session)
+    if hand.street != Street.COMPLETE:
+        return
+    player = _player_by_id(hand, HUMAN_PLAYER_ID)
+    opponents = [item for item in hand.players if item.player_id != HUMAN_PLAYER_ID]
+    if session.run.current_table is not None:
+        session.run.current_table.player_stack = player.stack
+        session.run.current_table.opponent_stacks = [opponent.stack for opponent in opponents]
+        session.run.current_table.hand_index += 1
+    builder.emit(
+        "hand_complete",
+        player_stack=player.stack,
+        opponent_stacks=[opponent.stack for opponent in opponents],
+        pot=_pot(hand),
+        board_cards=[str(card) for card in hand.board_cards],
+    )
+    floor = session.run.current_floor
+    if player.stack <= 0:
+        session.run.lose_current_floor(all_in_loss=True)
+        if session.run.status == RunStatus.LOST:
+            builder.emit("run_lost", reason="player_busted", objective="Win all five floors.")
+        elif session.run.status == RunStatus.ACTIVE:
+            builder.emit("debt_accepted", debt_markers=session.run.continues, bankroll=session.run.bankroll)
+            session.run.enter_current_floor()
+            builder.emit("floor_intro", **_floor_payload(session.run))
+            _start_hand(session, builder)
+        return
+    if player.stack >= floor.win_target or all(opponent.stack <= 0 for opponent in opponents):
+        session.run.win_current_floor(ending_stack=player.stack)
+        builder.emit("floor_won", floor_number=floor.floor_number, bankroll=session.run.bankroll)
+        if session.run.status == RunStatus.WON:
+            builder.emit("run_won", objective="You cleared the casino.")
+        else:
+            builder.emit("reward_offered", rewards=session.run.available_rewards)
+        return
+    _start_hand(session, builder)
+
+
+def _start_hand(session: GameSession, builder: EventBuilder) -> None:
+    run = session.run
+    if run.current_table is None:
+        run.enter_current_floor()
+    assert run.current_table is not None
+    profiles = _select_profiles(run.floor_index, len(run.current_table.opponent_stacks), run.seed)
+    session.opponent_profiles = profiles
+    for profile in profiles:
+        session.memories.setdefault(profile.agent_id, AgentMemory.neutral(profile.agent_id))
+    player_stack = run.current_table.player_stack
+    opponent_stacks = run.current_table.opponent_stacks
+    if player_stack <= 0:
+        run.lose_current_floor(all_in_loss=True)
+        return
+    players = [PlayerState(HUMAN_PLAYER_ID, "You", 0, player_stack, is_human=True)]
+    for index, (profile, stack) in enumerate(zip(profiles, opponent_stacks, strict=False), start=1):
+        if stack > 0:
+            players.append(PlayerState(profile.agent_id, profile.name, index, stack))
+    if len(players) < 2:
+        run.win_current_floor(ending_stack=player_stack)
+        return
+    session.hand_counter += 1
+    hand_seed = run.hand_seed(hand_index=session.hand_counter)
+    dealer_index = session.dealer_index % len(players)
+    if run.current_table.pending_metadata.get("player_acts_last_first_hand") and run.current_table.hand_index == 0:
+        dealer_index = max(0, len(players) - 2)
+    run.current_hand = HandState.start(
+        players,
+        seed=hand_seed,
+        dealer_button_index=dealer_index,
+        small_blind=run.current_table.small_blind,
+        big_blind=run.current_table.big_blind,
+        hand_id=f"{run.run_id}-h{session.hand_counter}",
+    )
+    session.dealer_index = (dealer_index + 1) % len(players)
+    builder.emit(
+        "hand_started",
+        hand_id=run.current_hand.hand_id,
+        floor_number=run.current_floor.floor_number,
+        blinds={"small": run.current_table.small_blind, "big": run.current_table.big_blind},
+    )
+    builder.emit("cards_dealt", player_cards=[str(card) for card in players[0].hole_cards])
+
+
+def _public_state(session: GameSession) -> dict[str, Any]:
+    run = session.run
+    hand = run.current_hand
+    hand_state = hand.to_public_state(HUMAN_PLAYER_ID) if hand is not None else None
+    floor = run.current_floor if run.status == RunStatus.ACTIVE else None
+    legal_actions = hand_state["legal_actions"] if hand_state else []
+    return {
+        "run_id": run.run_id,
+        "seed": run.seed,
+        "status": run.status.value,
+        "objective": "Win the run by clearing all five floors. Current floor win target is the next chip goal.",
+        "floor_index": run.floor_index,
+        "floor": _floor_payload(run) if floor else None,
+        "bankroll": run.bankroll,
+        "debt_markers": run.continues,
+        "active_perks": [perk.serialize() for perk in run.active_perks],
+        "completed_floors": list(run.completed_floors),
+        "hand": hand_state,
+        "pot": _pot(hand) if hand else 0,
+        "legal_actions": legal_actions,
+        "latest_speech": dict(session.latest_speech or {}),
+        "reward_choices": [_perk_payload(perk_id) for perk_id in run.available_rewards],
+        "awaiting_reward": run.awaiting_reward,
+        "model": session.runtime.metadata(),
+        "voice": {"tts_enabled": session.tts.enabled, "stt_enabled": session.stt.enabled},
+        "trace_available": bool(session.trace.records or session.trace.path.exists()),
+    }
+
+
+def _floor_config_payload(floor: FloorConfig) -> dict[str, Any]:
+    return {
+        "floor_number": floor.floor_number,
+        "name": floor.name,
+        "buy_in": floor.buy_in,
+        "win_target": floor.win_target,
+        "small_blind": floor.blinds.small_blind,
+        "big_blind": floor.blinds.big_blind,
+        "is_boss": floor.is_boss,
+        "opponent_count_min": floor.opponent_count_min,
+        "opponent_count_max": floor.opponent_count_max,
+    }
+
+
+def _floor_payload(run: RunState) -> dict[str, Any]:
+    return {
+        **_floor_config_payload(run.current_floor),
+        "total_floors": len(FLOOR_CONFIGS),
+    }
+
+
+def _perk_payload(perk_id: str) -> dict[str, Any]:
+    for perk in PERK_DEFINITIONS:
+        if perk.perk_id == perk_id:
+            return perk.serialize()
+    return {"perk_id": perk_id, "name": perk_id, "description": ""}
+
+
+def _select_profiles(floor_index: int, opponent_count: int, seed: str) -> list[AgentProfile]:
+    floor_number = floor_index + 1
+    if FLOOR_CONFIGS[floor_index].is_boss:
+        boss = get_agent_profile(DEFAULT_FINAL_BOSS_ID)
+        pool = [profile for profile in profiles_for_floor(floor_number) if profile.agent_id != boss.agent_id]
+        return [boss, *pool[: max(0, opponent_count - 1)]]
+    pool = list(profiles_for_floor(floor_number, include_bosses=False))
+    Random(derive_seed(seed, "profiles", floor_number)).shuffle(pool)
+    return pool[:opponent_count]
+
+
+def _profile_for_player(session: GameSession, player_id: str) -> AgentProfile:
+    for profile in session.opponent_profiles or []:
+        if profile.agent_id == player_id:
+            return profile
+    return get_agent_profile(player_id)
+
+
+def _legal_actions_payload(hand: HandState) -> list[str]:
+    return sorted(action.value for action in hand.legal_actions(HUMAN_PLAYER_ID))
+
+
+def _hand_summary(player: PlayerState, hand: HandState) -> str:
+    return f"{player.name} has {' '.join(str(card) for card in player.hole_cards)} on {hand.street.value}."
+
+
+def _current_actor(hand: HandState) -> PlayerState:
+    if hand.current_actor_index is None:
+        raise PokerError("there is no current actor")
+    return hand.players[hand.current_actor_index]
+
+
+def _player_by_id(hand: HandState, player_id: str) -> PlayerState:
+    for player in hand.players:
+        if player.player_id == player_id:
+            return player
+    raise PokerError(f"unknown player id: {player_id}")
+
+
+def _require_hand(session: GameSession) -> HandState:
+    if session.run.current_hand is None:
+        raise PokerError("no active hand")
+    return session.run.current_hand
+
+
+def _pot(hand: HandState | None) -> int:
+    if hand is None:
+        return 0
+    return sum(hand.pot_contributions.values())
+
+
+def _coerce_settings(settings: RunSettings | dict[str, Any] | None) -> RunSettings:
+    if settings is None:
+        return RunSettings()
+    if isinstance(settings, RunSettings):
+        return settings
+    return RunSettings(**settings)
+
+
+def _get_session(run_id: str) -> GameSession:
+    try:
+        return _SESSIONS[run_id]
+    except KeyError as error:
+        raise KeyError(f"unknown run id: {run_id}") from error
+
+
+def _action_value(action: ActionType | str | Enum) -> str:
+    if isinstance(action, Enum):
+        return str(action.value)
+    return str(action)
+
+
+def memory_delta_empty():
+    from telltale.agents.memory import MemoryDelta
+
+    return MemoryDelta()
+
+
+__all__ = [
+    "DEMO_SEED",
+    "HUMAN_PLAYER_ID",
+    "RunSettings",
+    "TraceExport",
+    "choose_reward",
+    "continue_until_player_turn",
+    "export_trace",
+    "get_tts_audio",
+    "get_state",
+    "reset_sessions",
+    "start_run",
+    "submit_player_action",
+    "transcribe_player_audio",
+]

telltale/server/events.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from uuid import uuid4
+import json
+from typing import Any
+
+
+@dataclass(frozen=True)
+class GameEvent:
+    event_id: str
+    event_type: str
+    run_id: str
+    sequence: int
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_id": self.event_id,
+            "event_type": self.event_type,
+            "run_id": self.run_id,
+            "sequence": self.sequence,
+            "payload": self.payload,
+        }
+
+
+@dataclass(frozen=True)
+class EventBatch:
+    run_id: str
+    events: list[GameEvent]
+    public_state: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "events": [event.to_dict() for event in self.events],
+            "public_state": self.public_state,
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), default=str)
+
+
+class EventBuilder:
+    def __init__(self, run_id: str, start_sequence: int = 0):
+        self.run_id = run_id
+        self._sequence = start_sequence
+        self.events: list[GameEvent] = []
+
+    @property
+    def sequence(self) -> int:
+        return self._sequence
+
+    def emit(self, event_type: str, **payload: Any) -> GameEvent:
+        self._sequence += 1
+        event = GameEvent(
+            event_id=str(uuid4()),
+            event_type=event_type,
+            run_id=self.run_id,
+            sequence=self._sequence,
+            payload=payload,
+        )
+        self.events.append(event)
+        return event

telltale/server/schemas.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from telltale.game.economy import RunStatus
+from telltale.game.holdem import ActionType, Street
+
+
+class ActionRequest(BaseModel):
+    player_id: str
+    action: ActionType
+    amount: int = Field(default=0, ge=0)
+    table_talk: "PlayerUtteranceRequest | None" = None
+
+
+class PlayerUtteranceRequest(BaseModel):
+    raw_text: str = ""
+    target_agent_id: str | None = None
+
+
+class AgentMemoryUpdateSchema(BaseModel):
+    respect_for_player: float | None = None
+    fear_of_player: float | None = None
+    charmed_by_player: float | None = None
+    grudge_against_player: float | None = None
+    recent_player_patterns: list[str] = Field(default_factory=list)
+    recent_dialogue_impressions: list[str] = Field(default_factory=list)
+    summary: str | None = None
+
+
+class AgentDecisionSchema(BaseModel):
+    action: ActionType
+    amount: int = Field(default=0, ge=0)
+    speech: str
+    honest_rationale: str
+    emotional_state: str
+    memory_delta: AgentMemoryUpdateSchema = Field(default_factory=AgentMemoryUpdateSchema)
+    source: str = "model"
+
+
+class PlayerPublicState(BaseModel):
+    player_id: str
+    name: str
+    seat_index: int
+    stack: int
+    hole_cards: list[str]
+    current_bet: int
+    has_folded: bool
+    is_all_in: bool
+    is_human: bool
+
+
+class HandPublicState(BaseModel):
+    hand_id: str
+    street: Street
+    board_cards: list[str]
+    players: list[PlayerPublicState]
+    pot_contributions: dict[str, int]
+    current_actor_index: int | None
+    legal_actions: list[ActionType]
+    action_history: list[dict]
+
+
+class PerkPublicState(BaseModel):
+    perk_id: str
+    name: str
+    description: str
+    trigger_timing: str
+    remaining_uses: int | None = None
+    remaining_floors: int | None = None
+    metadata: dict = Field(default_factory=dict)
+
+
+class TablePublicState(BaseModel):
+    floor_number: int
+    seed: str
+    player_stack: int
+    opponent_stacks: list[int]
+    small_blind: int
+    big_blind: int
+    hand_index: int
+    pending_metadata: dict = Field(default_factory=dict)
+
+
+class RunPublicState(BaseModel):
+    run_id: str
+    seed: str
+    floor_index: int
+    floor_number: int | None
+    bankroll: int
+    continues: int
+    active_perks: list[PerkPublicState]
+    completed_floors: list[int]
+    status: RunStatus
+    current_table: TablePublicState | None
+    available_rewards: list[str]
+    awaiting_reward: bool
+    event_log: list[dict]