0.34.1 - Openrouter reasoning model fixes (#241)

fix openrouter reasoning model issues

.github/workflows/ci.yml

@@ -1,30 +1,76 @@
-name: ci 
+name: ci
+
 on:
   push:
     branches:
-      - master 
       - main
-      - prep-0.26.0
+      - master
+  release:
+    types: [published]
+
 permissions:
   contents: write
+  packages: write
+
 jobs:
-  deploy:
+  container-build:
+    if: github.event_name == 'release'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Configure Git Credentials
+
+      - name: Remove unnecessary files to release disk space
         run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
+          sudo rm -rf \
+            "$AGENT_TOOLSDIRECTORY" \
+            /opt/ghc \
+            /opt/google/chrome \
+            /opt/microsoft/msedge \
+            /opt/microsoft/powershell \
+            /opt/pipx \
+            /usr/lib/mono \
+            /usr/local/julia* \
+            /usr/local/lib/android \
+            /usr/local/lib/node_modules \
+            /usr/local/share/chromium \
+            /usr/local/share/powershell \
+            /usr/local/share/powershell \
+            /usr/share/dotnet \
+            /usr/share/swift
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
         with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build & push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:latest
+            ghcr.io/${{ github.repository }}:${{ github.ref_name }}
+
+  deploy-docs:
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git credentials
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.x' }
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
-          restore-keys: |
-            mkdocs-material-
+          restore-keys: mkdocs-material-
       - run: pip install mkdocs-material mkdocs-awesome-pages-plugin mkdocs-glightbox
       - run: mkdocs gh-deploy --force

.github/workflows/test-container-build.yml

@@ -0,0 +1,51 @@
+name: test-container-build
+
+on:
+  push:
+    branches: [ 'prep-*' ]
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  container-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Remove unnecessary files to release disk space
+        run: |
+          sudo rm -rf \
+            "$AGENT_TOOLSDIRECTORY" \
+            /opt/ghc \
+            /opt/google/chrome \
+            /opt/microsoft/msedge \
+            /opt/microsoft/powershell \
+            /opt/pipx \
+            /usr/lib/mono \
+            /usr/local/julia* \
+            /usr/local/lib/android \
+            /usr/local/lib/node_modules \
+            /usr/local/share/chromium \
+            /usr/local/share/powershell \
+            /usr/local/share/powershell \
+            /usr/share/dotnet \
+            /usr/share/swift
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build & push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          # Tag with prep suffix to avoid conflicts with production
+          tags: |
+            ghcr.io/${{ github.repository }}:${{ github.ref_name }}

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Python Tests
 
 on:
   push:
-    branches: [ master, main, 'prep-*' ]
+    branches: [ main, 'prep-*' ]
   pull_request:
-    branches: [ master, main, 'prep-*' ]
+    branches: [ main, 'prep-*' ]
 
 jobs:
   test:
@@ -23,25 +23,29 @@ jobs:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
 
-    - name: Install poetry
+    - name: Install uv
       run: |
         python -m pip install --upgrade pip
-        pip install poetry
+        pip install uv
 
-    - name: Cache poetry dependencies
+    - name: Cache uv dependencies
       uses: actions/cache@v4
       with:
-        path: ~/.cache/pypoetry
-        key: ${{ runner.os }}-poetry-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+        path: ~/.cache/uv
+        key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml') }}
         restore-keys: |
-          ${{ runner.os }}-poetry-${{ matrix.python-version }}-
+          ${{ runner.os }}-uv-${{ matrix.python-version }}-
 
     - name: Install dependencies
       run: |
-        python -m venv talemate_env
-        source talemate_env/bin/activate
-        poetry config virtualenvs.create false
-        poetry install
+        uv venv
+        source .venv/bin/activate
+        uv pip install -e ".[dev]"
+
+    - name: Run linting
+      run: |
+        source .venv/bin/activate
+        uv run pre-commit run --all-files
 
     - name: Setup configuration file
       run: |
@@ -49,10 +53,10 @@ jobs:
 
     - name: Download NLTK data
       run: |
-        source talemate_env/bin/activate
+        source .venv/bin/activate
         python -c "import nltk; nltk.download('punkt_tab')"
 
     - name: Run tests
       run: |
-        source talemate_env/bin/activate
+        source .venv/bin/activate
         pytest tests/ -p no:warnings 

.gitignore

@@ -8,8 +8,20 @@
 talemate_env
 chroma
 config.yaml
+.cursor
+.claude
+
+# uv
+.venv/
 templates/llm-prompt/user/*.jinja2
 templates/world-state/*.yaml
+tts/voice/piper/*.onnx
+tts/voice/piper/*.json
+tts/voice/kokoro/*.pt
+tts/voice/xtts2/*.wav
+tts/voice/chatterbox/*.wav
+tts/voice/f5tts/*.wav
+tts/voice/voice-library.json
 scenes/
 !scenes/infinity-quest-dynamic-scenario/
 !scenes/infinity-quest-dynamic-scenario/assets/
@@ -18,4 +30,6 @@ scenes/
 !scenes/infinity-quest/assets/
 !scenes/infinity-quest/infinity-quest.json
 tts_voice_samples/*.wav
-third-party-docs/
+third-party-docs/
+legacy-state-reinforcements.yaml
+CLAUDE.md

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+fail_fast: false
+exclude: |
+    (?x)^(
+        tests/data/.*
+        |install-utils/.*
+    )$
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.12.1
+    hooks:
+    # Run the linter.
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format

.python-version

@@ -0,0 +1 @@
+3.11

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to Talemate
+
+## About This Project
+
+Talemate is a **personal hobbyist project** that I maintain in my spare time. While I appreciate the community's interest and contributions, please understand that:
+
+- This is primarily a passion project that I enjoy working on myself
+- I have limited time for code reviews and prefer to spend that time developing fixes or new features myself
+- Large contributions require significant review and testing time that takes away from my own development
+
+For these reasons, I've established contribution guidelines that balance community involvement with my desire to actively develop the project myself.
+
+## Contribution Policy
+
+**I welcome small bugfix and small feature pull requests!** If you've found a bug and have a fix, or have a small feature improvement, I'd love to review it.
+
+However, please note that **I am not accepting large refactors or major feature additions** at this time. This includes:
+- Major architectural changes
+- Large new features or significant functionality additions
+- Large-scale code reorganization
+- Breaking API changes
+- Features that would require significant maintenance
+
+## What is accepted
+
+✅ **Small bugfixes** - Fixes for specific, isolated bugs
+
+✅ **Small features** - Minor improvements that don't break existing functionality
+
+✅ **Documentation fixes** - Typo corrections, clarifications in existing docs
+
+✅ **Minor dependency updates** - Security patches or minor version bumps
+
+## What is not accepted
+
+❌ **Major features** - Large new functionality or systems
+
+❌ **Large refactors** - Code reorganization or architectural changes
+
+❌ **Breaking changes** - Any changes that break existing functionality
+
+❌ **Major dependency changes** - Framework upgrades or replacements
+
+## Submitting a PR
+
+If you'd like to submit a bugfix or small feature:
+
+1. **Open an issue first** - Describe the bug you've found or feature you'd like to add
+2. **Keep it small** - Focus on one specific issue or small improvement
+3. **Follow existing code style** - Match the project's current patterns
+4. **Don't break existing functionality** - Ensure all existing tests pass
+5. **Include tests** - Add or update tests that verify your fix or feature
+6. **Update documentation** - If your changes affect behavior, update relevant docs
+
+## Testing
+
+Ensure all tests pass by running:
+```bash
+uv run pytest tests/ -p no:warnings
+```
+
+## Questions?
+
+If you're unsure whether your contribution would be welcome, please open an issue to discuss it first. This saves everyone time and ensures alignment with the project's direction.

Dockerfile

@@ -1,15 +1,19 @@
 # Stage 1: Frontend build
-FROM node:21 AS frontend-build
-
-ENV NODE_ENV=development
+FROM node:21-slim AS frontend-build
 
 WORKDIR /app
 
-# Copy the frontend directory contents into the container at /app
-COPY ./talemate_frontend /app
+# Copy frontend package files
+COPY talemate_frontend/package*.json ./
 
-# Install all dependencies and build
-RUN npm install && npm run build
+# Install dependencies
+RUN npm ci
+
+# Copy frontend source
+COPY talemate_frontend/ ./
+
+# Build frontend
+RUN npm run build
 
 # Stage 2: Backend build
 FROM python:3.11-slim AS backend-build
@@ -22,31 +26,17 @@ RUN apt-get update && apt-get install -y \
     gcc \
     && rm -rf /var/lib/apt/lists/*
 
-# Install poetry
-RUN pip install poetry
+# Install uv
+RUN pip install uv
 
-# Copy poetry files
-COPY pyproject.toml poetry.lock* /app/
+# Copy installation files
+COPY pyproject.toml uv.lock /app/
 
-# Create a virtual environment
-RUN python -m venv /app/talemate_env
-
-# Activate virtual environment and install dependencies
-RUN . /app/talemate_env/bin/activate && \
-    poetry config virtualenvs.create false && \
-    poetry install  --only main --no-root
-
-# Copy the Python source code
+# Copy the Python source code (needed for editable install)
 COPY ./src /app/src
 
-# Conditional PyTorch+CUDA install
-ARG CUDA_AVAILABLE=false
-RUN . /app/talemate_env/bin/activate && \
-    if [ "$CUDA_AVAILABLE" = "true" ]; then \
-        echo "Installing PyTorch with CUDA support..." && \
-        pip uninstall torch torchaudio -y && \
-        pip install torch~=2.4.1 torchaudio~=2.4.1 --index-url https://download.pytorch.org/whl/cu121; \
-    fi
+# Create virtual environment and install dependencies (includes CUDA support via pyproject.toml)
+RUN uv sync
 
 # Stage 3: Final image
 FROM python:3.11-slim
@@ -55,10 +45,31 @@ WORKDIR /app
 
 RUN apt-get update && apt-get install -y \
     bash \
+    wget \
+    tar \
+    xz-utils \
     && rm -rf /var/lib/apt/lists/*
 
+# Install uv in the final stage
+RUN pip install uv
+
 # Copy virtual environment from backend-build stage
-COPY --from=backend-build /app/talemate_env /app/talemate_env
+COPY --from=backend-build /app/.venv /app/.venv
+
+# Download and install FFmpeg 8.0 with shared libraries into .venv (matching Windows installer approach)
+# Using BtbN FFmpeg builds which provide shared libraries - verified to work
+# Note: We tried using jrottenberg/ffmpeg:8.0-ubuntu image but copying libraries from it didn't work properly,
+#       so we use the direct download approach which is more reliable and matches the Windows installer
+RUN cd /tmp && \
+    wget -q https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linux64-gpl-shared.tar.xz -O ffmpeg.tar.xz && \
+    tar -xf ffmpeg.tar.xz && \
+    cp -a ffmpeg-master-latest-linux64-gpl-shared/bin/* /app/.venv/bin/ && \
+    cp -a ffmpeg-master-latest-linux64-gpl-shared/lib/* /app/.venv/lib/ && \
+    rm -rf ffmpeg-master-latest-linux64-gpl-shared ffmpeg.tar.xz && \
+    LD_LIBRARY_PATH=/app/.venv/lib /app/.venv/bin/ffmpeg -version | head -n 1
+
+# Set LD_LIBRARY_PATH so torchcodec can find ffmpeg libraries at runtime
+ENV LD_LIBRARY_PATH=/app/.venv/lib:${LD_LIBRARY_PATH}
 
 # Copy Python source code
 COPY --from=backend-build /app/src /app/src
@@ -83,4 +94,4 @@ EXPOSE 5050
 EXPOSE 8080
 
 # Use bash as the shell, activate the virtual environment, and run backend server
-CMD ["/bin/bash", "-c", "source /app/talemate_env/bin/activate && python src/talemate/server/run.py runserver --host 0.0.0.0 --port 5050 --frontend-host 0.0.0.0 --frontend-port 8080"]
+CMD ["uv", "run", "src/talemate/server/run.py", "runserver", "--host", "0.0.0.0", "--port", "5050", "--frontend-host", "0.0.0.0", "--frontend-port", "8080"]

README.md

@@ -39,12 +39,14 @@ Need help? Join the new [Discord community](https://discord.gg/8bGNRmFxMj)
 - [Cohere](https://www.cohere.com/)
 - [Groq](https://www.groq.com/)
 - [Google Gemini](https://console.cloud.google.com/)
+- [OpenRouter](https://openrouter.ai/)
 
 Supported self-hosted APIs:
 - [KoboldCpp](https://koboldai.org/cpp) ([Local](https://koboldai.org/cpp), [Runpod](https://koboldai.org/runpodcpp), [VastAI](https://koboldai.org/vastcpp), also includes image gen support)
 - [oobabooga/text-generation-webui](https://github.com/oobabooga/text-generation-webui) (local or with runpod support)
 - [LMStudio](https://lmstudio.ai/)
 - [TabbyAPI](https://github.com/theroyallab/tabbyAPI/)
+- [Ollama](https://ollama.com/)
 
 Generic OpenAI api implementations (tested and confirmed working):
 - [DeepInfra](https://deepinfra.com/)

docker-compose.manual.yml

@@ -0,0 +1,20 @@
+version: '3.8'
+
+services:
+  talemate:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "${FRONTEND_PORT:-8080}:8080"
+      - "${BACKEND_PORT:-5050}:5050"
+    volumes:
+      - ./config.yaml:/app/config.yaml
+      - ./scenes:/app/scenes
+      - ./templates:/app/templates
+      - ./chroma:/app/chroma
+      - ./tts:/app/tts
+    environment:
+      - PYTHONUNBUFFERED=1
+      - PYTHONPATH=/app/src:$PYTHONPATH
+    command: ["uv", "run", "src/talemate/server/run.py", "runserver", "--host", "0.0.0.0", "--port", "5050", "--frontend-host", "0.0.0.0", "--frontend-port", "8080"]

docker-compose.yml

@@ -2,11 +2,7 @@ version: '3.8'
 
 services:
   talemate:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      args:
-        - CUDA_AVAILABLE=${CUDA_AVAILABLE:-false}
+    image: ghcr.io/vegu-ai/talemate:latest
     ports:
       - "${FRONTEND_PORT:-8080}:8080"
       - "${BACKEND_PORT:-5050}:5050"
@@ -15,7 +11,8 @@ services:
       - ./scenes:/app/scenes
       - ./templates:/app/templates
       - ./chroma:/app/chroma
+      - ./tts:/app/tts
     environment:
       - PYTHONUNBUFFERED=1
       - PYTHONPATH=/app/src:$PYTHONPATH
-    command: ["/bin/bash", "-c", "source /app/talemate_env/bin/activate && python src/talemate/server/run.py runserver --host 0.0.0.0 --port 5050 --frontend-host 0.0.0.0 --frontend-port 8080"]
+    command: ["uv", "run", "src/talemate/server/run.py", "runserver", "--host", "0.0.0.0", "--port", "5050", "--frontend-host", "0.0.0.0", "--frontend-port", "8080"]

docs/cleanup.py

@@ -1,60 +1,63 @@
 import os
 import re
 import subprocess
-from pathlib import Path
 import argparse
 
+
 def find_image_references(md_file):
     """Find all image references in a markdown file."""
-    with open(md_file, 'r', encoding='utf-8') as f:
+    with open(md_file, "r", encoding="utf-8") as f:
         content = f.read()
-    
-    pattern = r'!\[.*?\]\((.*?)\)'
+
+    pattern = r"!\[.*?\]\((.*?)\)"
     matches = re.findall(pattern, content)
-    
+
     cleaned_paths = []
     for match in matches:
-        path = match.lstrip('/')
-        if 'img/' in path:
-            path = path[path.index('img/') + 4:]
+        path = match.lstrip("/")
+        if "img/" in path:
+            path = path[path.index("img/") + 4 :]
             # Only keep references to versioned images
             parts = os.path.normpath(path).split(os.sep)
-            if len(parts) >= 2 and parts[0].replace('.', '').isdigit():
+            if len(parts) >= 2 and parts[0].replace(".", "").isdigit():
                 cleaned_paths.append(path)
-    
+
     return cleaned_paths
 
+
 def scan_markdown_files(docs_dir):
     """Recursively scan all markdown files in the docs directory."""
     md_files = []
     for root, _, files in os.walk(docs_dir):
         for file in files:
-            if file.endswith('.md'):
+            if file.endswith(".md"):
                 md_files.append(os.path.join(root, file))
     return md_files
 
+
 def find_all_images(img_dir):
     """Find all image files in version subdirectories."""
     image_files = []
     for root, _, files in os.walk(img_dir):
         # Get the relative path from img_dir to current directory
         rel_dir = os.path.relpath(root, img_dir)
-        
+
         # Skip if we're in the root img directory
-        if rel_dir == '.':
+        if rel_dir == ".":
             continue
-            
+
         # Check if the immediate parent directory is a version number
         parent_dir = rel_dir.split(os.sep)[0]
-        if not parent_dir.replace('.', '').isdigit():
+        if not parent_dir.replace(".", "").isdigit():
             continue
-            
+
         for file in files:
-            if file.lower().endswith(('.png', '.jpg', '.jpeg', '.gif', '.svg')):
+            if file.lower().endswith((".png", ".jpg", ".jpeg", ".gif", ".svg")):
                 rel_path = os.path.relpath(os.path.join(root, file), img_dir)
                 image_files.append(rel_path)
     return image_files
 
+
 def grep_check_image(docs_dir, image_path):
     """
     Check if versioned image is referenced anywhere using grep.
@@ -65,33 +68,46 @@ def grep_check_image(docs_dir, image_path):
         parts = os.path.normpath(image_path).split(os.sep)
         version = parts[0]  # e.g., "0.29.0"
         filename = parts[-1]  # e.g., "world-state-suggestions-2.png"
-        
+
         # For versioned images, require both version and filename to match
         version_pattern = f"{version}.*{filename}"
         try:
             result = subprocess.run(
-                ['grep', '-r', '-l', version_pattern, docs_dir],
+                ["grep", "-r", "-l", version_pattern, docs_dir],
                 capture_output=True,
-                text=True
+                text=True,
             )
             if result.stdout.strip():
-                print(f"Found reference to {image_path} with version pattern: {version_pattern}")
+                print(
+                    f"Found reference to {image_path} with version pattern: {version_pattern}"
+                )
                 return True
         except subprocess.CalledProcessError:
             pass
-            
+
     except Exception as e:
         print(f"Error during grep check for {image_path}: {e}")
-    
+
     return False
 
+
 def main():
-    parser = argparse.ArgumentParser(description='Find and optionally delete unused versioned images in MkDocs project')
-    parser.add_argument('--docs-dir', type=str, required=True, help='Path to the docs directory')
-    parser.add_argument('--img-dir', type=str, required=True, help='Path to the images directory')
-    parser.add_argument('--delete', action='store_true', help='Delete unused images')
-    parser.add_argument('--verbose', action='store_true', help='Show all found references and files')
-    parser.add_argument('--skip-grep', action='store_true', help='Skip the additional grep validation')
+    parser = argparse.ArgumentParser(
+        description="Find and optionally delete unused versioned images in MkDocs project"
+    )
+    parser.add_argument(
+        "--docs-dir", type=str, required=True, help="Path to the docs directory"
+    )
+    parser.add_argument(
+        "--img-dir", type=str, required=True, help="Path to the images directory"
+    )
+    parser.add_argument("--delete", action="store_true", help="Delete unused images")
+    parser.add_argument(
+        "--verbose", action="store_true", help="Show all found references and files"
+    )
+    parser.add_argument(
+        "--skip-grep", action="store_true", help="Skip the additional grep validation"
+    )
     args = parser.parse_args()
 
     # Convert paths to absolute paths
@@ -118,7 +134,7 @@ def main():
         print("\nAll versioned image references found in markdown:")
         for img in sorted(used_images):
             print(f"- {img}")
-        
+
         print("\nAll versioned images in directory:")
         for img in sorted(all_images):
             print(f"- {img}")
@@ -133,9 +149,11 @@ def main():
         for img in unused_images:
             if not grep_check_image(docs_dir, img):
                 actually_unused.add(img)
-        
+
         if len(actually_unused) != len(unused_images):
-            print(f"\nGrep validation found {len(unused_images) - len(actually_unused)} additional image references!")
+            print(
+                f"\nGrep validation found {len(unused_images) - len(actually_unused)} additional image references!"
+            )
         unused_images = actually_unused
 
     # Report findings
@@ -148,7 +166,7 @@ def main():
         print("\nUnused versioned images:")
         for img in sorted(unused_images):
             print(f"- {img}")
-            
+
         if args.delete:
             print("\nDeleting unused versioned images...")
             for img in unused_images:
@@ -162,5 +180,6 @@ def main():
     else:
         print("\nNo unused versioned images found!")
 
+
 if __name__ == "__main__":
-    main()
+    main()

docs/dev/agents/example/test/__init__.py

@@ -4,12 +4,12 @@ from talemate.events import GameLoopEvent
 import talemate.emit.async_signals
 from talemate.emit import emit
 
+
 @register()
 class TestAgent(Agent):
-    
     agent_type = "test"
     verbose_name = "Test"
-    
+
     def __init__(self, client):
         self.client = client
         self.is_enabled = True
@@ -20,7 +20,7 @@ class TestAgent(Agent):
                 description="Test",
             ),
         }
-        
+
     @property
     def enabled(self):
         return self.is_enabled
@@ -36,7 +36,7 @@ class TestAgent(Agent):
     def connect(self, scene):
         super().connect(scene)
         talemate.emit.async_signals.get("game_loop").connect(self.on_game_loop)
-        
+
     async def on_game_loop(self, emission: GameLoopEvent):
         """
         Called on the beginning of every game loop
@@ -45,4 +45,8 @@ class TestAgent(Agent):
         if not self.enabled:
             return
 
-        emit("status", status="info", message="Annoying you with a test message every game loop.")
+        emit(
+            "status",
+            status="info",
+            message="Annoying you with a test message every game loop.",
+        )

docs/dev/client/example/runpod_vllm/__init__.py

@@ -1,129 +0,0 @@
-"""
-An attempt to write a client against the runpod serverless vllm worker.
-
-This is close to functional, but since runpod serverless gpu availability is currently terrible, i have
-been unable to properly test it.
-
-Putting it here for now since i think it makes a decent example of how to write a client against a new service.
-"""
-
-import pydantic
-import structlog
-import runpod
-import asyncio
-import aiohttp
-from talemate.client.base import ClientBase, ExtraField
-from talemate.client.registry import register
-from talemate.emit import emit
-from talemate.config import Client as BaseClientConfig
-
-log = structlog.get_logger("talemate.client.runpod_vllm")
-
-class Defaults(pydantic.BaseModel):
-    max_token_length: int = 4096
-    model: str = ""
-    runpod_id: str = ""
-    
-class ClientConfig(BaseClientConfig):
-    runpod_id: str = ""
-
-@register()
-class RunPodVLLMClient(ClientBase):
-    client_type = "runpod_vllm"
-    conversation_retries = 5
-    config_cls = ClientConfig
-
-    class Meta(ClientBase.Meta):
-        title: str = "Runpod VLLM"
-        name_prefix: str = "Runpod VLLM"
-        enable_api_auth: bool = True
-        manual_model: bool = True
-        defaults: Defaults = Defaults()
-        extra_fields: dict[str, ExtraField] = {
-            "runpod_id": ExtraField(
-                name="runpod_id",
-                type="text",
-                label="Runpod ID",
-                required=True,
-                description="The Runpod ID to connect to.",
-            )
-        }
-
-
-    def __init__(self, model=None, runpod_id=None, **kwargs):
-        self.model_name = model
-        self.runpod_id = runpod_id
-        super().__init__(**kwargs)
-
-    @property
-    def experimental(self):
-        return False
-
-
-    def set_client(self, **kwargs):
-        log.debug("set_client", kwargs=kwargs, runpod_id=self.runpod_id)
-        self.runpod_id = kwargs.get("runpod_id", self.runpod_id)
-        
-        
-    def tune_prompt_parameters(self, parameters: dict, kind: str):
-        super().tune_prompt_parameters(parameters, kind)
-
-        keys = list(parameters.keys())
-
-        valid_keys = ["temperature", "top_p", "max_tokens"]
-
-        for key in keys:
-            if key not in valid_keys:
-                del parameters[key]
-
-    async def get_model_name(self):
-        return self.model_name
-
-    async def generate(self, prompt: str, parameters: dict, kind: str):
-        """
-        Generates text from the given prompt and parameters.
-        """
-        prompt = prompt.strip()
-
-        self.log.debug("generate", prompt=prompt[:128] + " ...", parameters=parameters)
-
-        try:
-            
-            async with aiohttp.ClientSession() as session:
-                endpoint = runpod.AsyncioEndpoint(self.runpod_id, session)
-                
-                run_request = await endpoint.run({
-                    "input": {
-                        "prompt": prompt,   
-                    }
-                    #"parameters": parameters
-                })
-                
-                while (await run_request.status()) not in ["COMPLETED", "FAILED", "CANCELLED"]:
-                    status = await run_request.status()
-                    log.debug("generate", status=status)
-                    await asyncio.sleep(0.1)
-                    
-                status = await run_request.status()
-                
-                log.debug("generate", status=status)
-                    
-                response = await run_request.output()
-                
-                log.debug("generate", response=response)
-                
-                return response["choices"][0]["tokens"][0]
-            
-        except Exception as e:
-            self.log.error("generate error", e=e)
-            emit(
-                "status", message="Error during generation (check logs)", status="error"
-            )
-            return ""
-
-    def reconfigure(self, **kwargs):
-        if kwargs.get("model"):
-            self.model_name = kwargs["model"]
-        if "runpod_id" in kwargs:
-            self.api_auth = kwargs["runpod_id"]
-        self.set_client(**kwargs)

docs/dev/client/example/test/__init__.py

@@ -9,6 +9,7 @@ class Defaults(pydantic.BaseModel):
     api_url: str = "http://localhost:1234"
     max_token_length: int = 4096
 
+
 @register()
 class TestClient(ClientBase):
     client_type = "test"
@@ -22,14 +23,13 @@ class TestClient(ClientBase):
         self.client = AsyncOpenAI(base_url=self.api_url + "/v1", api_key="sk-1111")
 
     def tune_prompt_parameters(self, parameters: dict, kind: str):
-        
         """
         Talemate adds a bunch of parameters to the prompt, but not all of them are valid for all clients.
-        
+
         This method is called before the prompt is sent to the client, and it allows the client to remove
         any parameters that it doesn't support.
         """
-        
+
         super().tune_prompt_parameters(parameters, kind)
 
         keys = list(parameters.keys())
@@ -41,11 +41,10 @@ class TestClient(ClientBase):
                 del parameters[key]
 
     async def get_model_name(self):
-        
         """
         This should return the name of the model that is being used.
         """
-        
+
         return "Mock test model"
 
     async def generate(self, prompt: str, parameters: dict, kind: str):

docs/dev/howto/add-a-worldstate-template-type.md

@@ -0,0 +1,166 @@
+# Adding a new world-state template
+
+I am writing this up as I add phrase detection functionality to the `Writing Style` template, so that in the future, hopefully when new template types need to be added this document can just given to the LLM of the month, to do it.
+
+## Introduction
+
+World state templates are reusable components that plug in various parts of talemate.
+
+At this point there are following types:
+
+- Character Attribute
+- Character Detail
+- Writing Style
+- Spice (for randomization of content during generation)
+- Scene Type
+- State Reinforcement
+
+Basically whenever we want to add something reusable and customizable by the user, a world state template is likely a good solution.
+
+## Steps to creating a new template type
+
+### 1. Add a pydantic schema (python)
+
+In `src/talemate/world_state/templates` create a new `.py` file with reasonable name. 
+
+In this example I am extending the `Writing Style` template to include phrase detection functionality, which will be used by the `Editor` agent to detect certain phrases and then act upon them. 
+
+There already is a `content.py` file - so it makes sense to just add this new functionality to this file.
+
+```python
+class PhraseDetection(pydantic.BaseModel):
+    phrase: str
+    instructions: str
+    # can be "unwanted" for now, more added later
+    classification: Literal["unwanted"] = "unwanted"
+
+@register("writing_style")
+class WritingStyle(Template):
+    description: str | None = None
+    phrases: list[PhraseDetection] = pydantic.Field(default_factory=list)
+
+    def render(self, scene: "Scene", character_name: str):
+        return self.formatted("instructions", scene, character_name)
+```
+
+If I were to create a new file I'd still want to read one of the existing files first to understand imports and style.
+
+### 2. Add a vue component to allow management (vue, js)
+
+Next we need to add a new vue component that exposes a UX for us to manage this new template type.
+
+For this I am creating `talemate_frontend/src/components/WorldStateManagerTemplateWritingStyle.vue`.
+
+## Bare Minimum Understanding for New Template Components
+
+When adding a new component for managing a template type, you need to understand:
+
+### Component Structure
+
+1. **Props**: The component always receives an `immutableTemplate` prop with the template data.
+2. **Data Management**: Create a local copy of the template data for editing before saving back.
+3. **Emits**: Use the `update` event to send modified template data back to the parent.
+
+### Core Implementation Requirements
+
+1. **Template Properties**: Always include fields for `name`, `description`, and `favorite` status.
+2. **Data Binding**: Implement two-way binding with `v-model` for all editable fields.
+3. **Dirty State Tracking**: Track when changes are made but not yet saved.
+4. **Save Method**: Implement a `save()` method that emits the updated template.
+
+### Component Lifecycle
+
+1. **Initialization**: Use the `created` hook to initialize the local template copy.
+2. **Watching for Changes**: Set up a watcher for the `immutableTemplate` to handle external updates.
+
+### UI Patterns
+
+1. **Forms**: Use Vuetify form components with consistent validation.
+2. **Actions**: Provide clear user actions for editing and managing template items.
+3. **Feedback**: Give visual feedback when changes are being made or saved.
+
+The WorldStateManagerTemplate components follow a consistent pattern where they:
+- Display and edit general template metadata (name, description, favorite status)
+- Provide specialized UI for the template's unique properties
+- Handle the create, read, update, delete (CRUD) operations for template items
+- Maintain data integrity by properly handling template updates
+
+You absolutely should read an existing component like `WorldStateManagerTemplateWritingStyle.vue` first to get a good understanding of the implementation.
+
+## Integrating with WorldStateManagerTemplates
+
+After creating your template component, you need to integrate it with the WorldStateManagerTemplates component:
+
+### 1. Import the Component
+
+Edit `talemate_frontend/src/components/WorldStateManagerTemplates.vue` and add an import for your new component:
+
+```javascript
+import WorldStateManagerTemplateWritingStyle from './WorldStateManagerTemplateWritingStyle.vue'
+```
+
+### 2. Register the Component
+
+Add your component to the components section of the WorldStateManagerTemplates:
+
+```javascript
+components: {
+  // ... existing components
+  WorldStateManagerTemplateWritingStyle
+}
+```
+
+### 3. Add Conditional Rendering
+
+In the template section, add a new conditional block to render your component when the template type matches:
+
+```html
+<WorldStateManagerTemplateWritingStyle v-else-if="template.template_type === 'writing_style'"
+    :immutableTemplate="template"
+    @update="(template) => applyAndSaveTemplate(template)"
+/>
+```
+
+### 4. Add Icon and Color
+
+Add cases for your template type in the `iconForTemplate` and `colorForTemplate` methods:
+
+```javascript
+iconForTemplate(template) {
+    // ... existing conditions
+    else if (template.template_type == 'writing_style') {
+        return 'mdi-script-text';
+    }
+    return 'mdi-cube-scan';
+},
+
+colorForTemplate(template) {
+    // ... existing conditions
+    else if (template.template_type == 'writing_style') {
+        return 'highlight5';
+    }
+    return 'grey';
+}
+```
+
+### 5. Add Help Message
+
+Add a help message for your template type in the `helpMessages` object in the data section:
+
+```javascript
+helpMessages: {
+    // ... existing messages
+    writing_style: "Writing style templates are used to define a writing style that can be applied to the generated content. They can be used to add a specific flavor or tone. A template must explicitly support writing styles to be able to use a writing style template.",
+}
+```
+
+### 6. Update Template Type Selection
+
+Add your template type to the `templateTypes` array in the data section:
+
+```javascript
+templateTypes: [
+    // ... existing types
+    { "title": "Writing style", "value": 'writing_style'},
+]
+```

docs/getting-started/advanced/change-host-and-port.md

@@ -10,28 +10,27 @@ To run the server on a different host and port, you need to change the values pa
 
 #### :material-linux: Linux
 
-Copy `start.sh` to `start_custom.sh` and edit the `--host` and `--port` parameters in the `uvicorn` command.
+Copy `start.sh` to `start_custom.sh` and edit the `--host` and `--port` parameters.
 
 ```bash
 #!/bin/sh
-. talemate_env/bin/activate
-python src/talemate/server/run.py runserver --host 0.0.0.0 --port 1234
+uv run src/talemate/server/run.py runserver --host 0.0.0.0 --port 1234
 ```
 
 #### :material-microsoft-windows: Windows
 
-Copy `start.bat` to `start_custom.bat` and edit the `--host` and `--port` parameters in the `uvicorn` command.
+Copy `start.bat` to `start_custom.bat` and edit the `--host` and `--port` parameters.
 
 ```batch
-start cmd /k "cd talemate_env\Scripts && activate && cd ../../ && python src\talemate\server\run.py runserver --host 0.0.0.0 --port 1234"
+uv run src\talemate\server\run.py runserver --host 0.0.0.0 --port 1234
 ```
 
 ### Letting the frontend know about the new host and port
 
-Copy `talemate_frontend/example.env.development.local` to `talemate_frontend/.env.production.local` and edit the `VUE_APP_TALEMATE_BACKEND_WEBSOCKET_URL`.
+Copy `talemate_frontend/example.env.development.local` to `talemate_frontend/.env.production.local` and edit the `VITE_TALEMATE_BACKEND_WEBSOCKET_URL`.
 
 ```env
-VUE_APP_TALEMATE_BACKEND_WEBSOCKET_URL=ws://localhost:1234
+VITE_TALEMATE_BACKEND_WEBSOCKET_URL=ws://localhost:1234
 ```
 
 Next rebuild the frontend.
@@ -71,8 +70,7 @@ Copy `start.sh` to `start_custom.sh` and edit the `--frontend-host` and `--front
 
 ```bash
 #!/bin/sh
-. talemate_env/bin/activate
-python src/talemate/server/run.py runserver --host 0.0.0.0 --port 5055 \
+uv run src/talemate/server/run.py runserver --host 0.0.0.0 --port 5055 \
 --frontend-host localhost --frontend-port 8082
 ```
 
@@ -81,7 +79,7 @@ python src/talemate/server/run.py runserver --host 0.0.0.0 --port 5055 \
 Copy `start.bat` to `start_custom.bat` and edit the `--frontend-host` and `--frontend-port` parameters.
 
 ```batch
-start cmd /k "cd talemate_env\Scripts && activate && cd ../../ && python src\talemate\server\run.py runserver --host 0.0.0.0 --port 5055 --frontend-host localhost --frontend-port 8082"
+uv run src\talemate\server\run.py runserver --host 0.0.0.0 --port 5055 --frontend-host localhost --frontend-port 8082
 ```
 
 ### Start the backend and frontend
@@ -98,5 +96,4 @@ Start the backend and frontend as usual.
 
 ```batch
 start_custom.bat
-```
-
+```

docs/getting-started/installation/docker.md

@@ -1,22 +1,15 @@
-!!! example "Experimental"
-    Talemate through docker has not received a lot of testing from me, so please let me know if you encounter any issues.
-    
-    You can do so by creating an issue on the [:material-github: GitHub repository](https://github.com/vegu-ai/talemate)
-
 ## Quick install instructions
 
 1. `git clone https://github.com/vegu-ai/talemate.git`
 1. `cd talemate`
 1. copy config file
     1. linux: `cp config.example.yaml config.yaml` 
-    1. windows: `copy config.example.yaml config.yaml`
-1. If your host has a CUDA compatible Nvidia GPU
-    1. Windows (via PowerShell): `$env:CUDA_AVAILABLE="true"; docker compose up`
-    1. Linux: `CUDA_AVAILABLE=true docker compose up`
-1. If your host does **NOT** have a CUDA compatible Nvidia GPU
-    1. Windows: `docker compose up`
-    1. Linux: `docker compose up`
+    1. windows: `copy config.example.yaml config.yaml` (or just copy the file and rename it via the file explorer)
+1. `docker compose up`
 1. Navigate your browser to http://localhost:8080
 
+!!! info "Pre-built Images"
+    The default setup uses pre-built images from GitHub Container Registry that include CUDA support by default. To manually build the container instead, use `docker compose -f docker-compose.manual.yml up --build`.
+
 !!! note
     When connecting local APIs running on the hostmachine (e.g. text-generation-webui), you need to use `host.docker.internal` as the hostname.

docs/getting-started/installation/linux.md

@@ -1,4 +1,3 @@
-
 ## Quick install instructions
 
 ### Dependencies
@@ -7,6 +6,7 @@
 
 1. node.js and npm - see instructions [here](https://nodejs.org/en/download/package-manager/)
 1. python- see instructions [here](https://www.python.org/downloads/)
+1. uv - see instructions [here](https://github.com/astral-sh/uv#installation)
 
 ### Installation
 
@@ -25,19 +25,15 @@ If everything went well, you can proceed to [connect a client](../../connect-a-c
 
 1. Open a terminal.
 2. Navigate to the project directory.
-3. Create a virtual environment by running `python3 -m venv talemate_env`.
-4. Activate the virtual environment by running `source talemate_env/bin/activate`.
+3. uv will automatically create a virtual environment when you run `uv venv`.
 
 ### Installing Dependencies
 
-1. With the virtual environment activated, install poetry by running `pip install poetry`.
-2. Use poetry to install dependencies by running `poetry install`.
+1. Use uv to install dependencies by running `uv pip install -e ".[dev]"`.
 
 ### Running the Backend
 
-1. With the virtual environment activated and dependencies installed, you can start the backend server.
-2. Navigate to the `src/talemate/server` directory.
-3. Run the server with `python run.py runserver --host 0.0.0.0 --port 5050`.
+1. You can start the backend server using `uv run src/talemate/server/run.py runserver --host 0.0.0.0 --port 5050`.
 
 ### Running the Frontend
 
@@ -45,4 +41,4 @@ If everything went well, you can proceed to [connect a client](../../connect-a-c
 2. If you haven't already, install npm dependencies by running `npm install`.
 3. Start the server with `npm run serve`.
 
-Please note that you may need to set environment variables or modify the host and port as per your setup. You can refer to the `runserver.sh` and `frontend.sh` files for more details.
+Please note that you may need to set environment variables or modify the host and port as per your setup. You can refer to the various start scripts for more details.

docs/getting-started/installation/troubleshoot.md

@@ -2,12 +2,9 @@
 
 ## Windows
 
-### Installation fails with "Microsoft Visual C++" error
-    
-If your installation errors with a notification to upgrade "Microsoft Visual C++" go to https://visualstudio.microsoft.com/visual-cpp-build-tools/ and click "Download Build Tools" and run it.
+### Frontend fails with errors
 
--  During installation make sure you select the C++ development package (upper left corner)
--  Run `reinstall.bat` inside talemate directory
+- ensure none of the directories leading to your talemate directory have special characters in them, this can cause issues with the frontend. so no `(1)` in the directory name.
 
 ## Docker
 

docs/getting-started/installation/windows.md

@@ -1,52 +1,24 @@
 ## Quick install instructions
 
-1. Download and install Python 3.10 - 3.13 from the [official Python website](https://www.python.org/downloads/windows/).
-    - [Click here for direct link to python 3.11.9 download](https://www.python.org/downloads/release/python-3119/)
-1. Download and install Node.js from the [official Node.js website](https://nodejs.org/en/download/prebuilt-installer). This will also install npm.
-1. Download the Talemate project to your local machine. Download from [the Releases page](https://github.com/vegu-ai/talemate/releases).
-1. Unpack the download and run `install.bat` by double clicking it. This will set up the project on your local machine.
-1. **Optional:** If you are using an nvidia graphics card with CUDA support you may want to also run `install-cuda.bat` **afterwards**, to install the cuda enabled version of torch - although this is only needed if you want to run some bigger embedding models where CUDA can be helpful.
-1. Once the installation is complete, you can start the backend and frontend servers by running `start.bat`.
-1. Once the talemate logo shows up, navigate your browser to http://localhost:8080
+1. Download the latest Talemate release ZIP from the [Releases page](https://github.com/vegu-ai/talemate/releases) and extract it anywhere on your system (for example, `C:\Talemate`).
+2. Double-click **`start.bat`**.
+   - On the very first run Talemate will automatically:
+     1. Download a portable build of Python 3 and Node.js (no global installs required).
+     2. Create and configure a Python virtual environment.
+     3. Install all back-end and front-end dependencies with the included *uv* and *npm*.
+     4. Build the web client.
+3. When the console window prints **"Talemate is now running"** and the logo appears, open your browser at **http://localhost:8080**.
 
-!!! note "First start up may take a while"
-    We have seen cases where the first start of talemate will sit at a black screen for a minute or two. Just wait it out, eventually the Talemate logo should show up.
+!!! note "First start can take a while"
+    The initial download and dependency installation may take several minutes, especially on slow internet connections. The console will keep you updated – just wait until the Talemate logo shows up.
 
-If everything went well, you can proceed to [connect a client](../../connect-a-client).
+## Maintenance & advanced usage
 
-## Additional Information
+| Script | Purpose |
+|--------|---------|
+| **`start.bat`** | Primary entry point – performs the initial install if needed and then starts Talemate. |
+| **`install.bat`** | Runs the installer without launching the server. Useful for automated setups or debugging. |
+| **`install-cuda.bat`** | Installs the CUDA-enabled Torch build (run after the regular install). |
+| **`update.bat`** | Pulls the latest changes from GitHub, updates dependencies, rebuilds the web client. |
 
-### How to Install Python
-
---8<-- "docs/snippets/common.md:python-versions"
-
-1. Visit the official Python website's download page for Windows at [https://www.python.org/downloads/windows/](https://www.python.org/downloads/windows/).
-2. Find the latest updated of Python 3.13 and click on one of the download links. (You will likely want the Windows installer (64-bit))
-4. Run the installer file and follow the setup instructions. Make sure to check the box that says Add Python 3.13 to PATH before you click Install Now.
-
-### How to Install npm
-
-1. Download Node.js from the official site [https://nodejs.org/en/download/prebuilt-installer](https://nodejs.org/en/download/prebuilt-installer).
-2. Run the installer (the .msi installer is recommended).
-3. Follow the prompts in the installer (Accept the license agreement, click the NEXT button a bunch of times and accept the default installation settings).
-
-### Usage of the Supplied bat Files
-
-#### install.bat
-
-This batch file is used to set up the project on your local machine. It creates a virtual environment, activates it, installs poetry, and uses poetry to install dependencies. It then navigates to the frontend directory and installs the necessary npm packages.
-
-To run this file, simply double click on it or open a command prompt in the same directory and type `install.bat`.
-
-#### update.bat
-
-If you are inside a git checkout of talemate you can use this to pull and reinstall talemate if there have been updates.
-
-!!! note "CUDA needs to be reinstalled manually"
-    Running `update.bat` will downgrade your torch install to the non-CUDA version, so if you want CUDA support you will need to run the `install-cuda.bat` script after the update is finished.
-
-#### start.bat
-
-This batch file is used to start the backend and frontend servers. It opens two command prompts, one for the frontend and one for the backend.
-
-To run this file, simply double click on it or open a command prompt in the same directory and type `start.bat`.
+No system-wide Python or Node.js is required – Talemate uses the embedded runtimes it downloads automatically.