0.30.1 (#190)

* address circular import issues

* set 0.30.1

* docs

* numpy to 2

* docs

.github/workflows/test.yml

@@ -0,0 +1,58 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [ master, main, 'prep-*' ]
+  pull_request:
+    branches: [ master, main, 'prep-*' ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Install poetry
+      run: |
+        python -m pip install --upgrade pip
+        pip install poetry
+
+    - name: Cache poetry dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pypoetry
+        key: ${{ runner.os }}-poetry-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-poetry-${{ matrix.python-version }}-
+
+    - name: Install dependencies
+      run: |
+        python -m venv talemate_env
+        source talemate_env/bin/activate
+        poetry config virtualenvs.create false
+        poetry install
+
+    - name: Setup configuration file
+      run: |
+        cp config.example.yaml config.yaml
+
+    - name: Download NLTK data
+      run: |
+        source talemate_env/bin/activate
+        python -c "import nltk; nltk.download('punkt_tab')"
+
+    - name: Run tests
+      run: |
+        source talemate_env/bin/activate
+        pytest tests/ -p no:warnings 

.gitignore

@@ -17,4 +17,5 @@ scenes/
 !scenes/infinity-quest-dynamic-scenario/infinity-quest.json
 !scenes/infinity-quest/assets/
 !scenes/infinity-quest/infinity-quest.json
-tts_voice_samples/*.wav
+tts_voice_samples/*.wav
+third-party-docs/

Dockerfile

@@ -34,7 +34,7 @@ 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 --no-dev --no-root
+    poetry install  --only main --no-root
 
 # Copy the Python source code
 COPY ./src /app/src
@@ -83,4 +83,4 @@ EXPOSE 5050
 EXPOSE 8080
 
 # Use bash as the shell, activate the virtual environment, and run backend server
-CMD ["poetry run src/talemate/server/run.py runserver --host 0.0.0.0 --port 5050 --frontend-host 0.0.0.0 --frontend-port 8080"]
+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"]

README.md

@@ -2,10 +2,13 @@
 
 Roleplay with AI with a focus on strong narration and consistent world and game state tracking.
 
-|![Screenshot 3](docs/img/0.17.0/ss-1.png)|![Screenshot 3](docs/img/0.17.0/ss-2.png)|
+<div align="center">
+
+|<img src="docs/img/ss-1.png" width="400" height="250" alt="Screenshot 1">|<img src="docs/img/ss-2.png" width="400" height="250" alt="Screenshot 2">|
 |------------------------------------------|------------------------------------------|
-|![Screenshot 4](docs/img/0.17.0/ss-4.png)|![Screenshot 1](docs/img/0.19.0/Screenshot_15.png)|
-|![Screenshot 2](docs/img/0.19.0/Screenshot_16.png)|![Screenshot 3](docs/img/0.19.0/Screenshot_17.png)|
+|<img src="docs/img/ss-3.png" width="400" height="250" alt="Screenshot 3">|<img src="docs/img/ss-4.png" width="400" height="250" alt="Screenshot 4">|
+
+</div>
 
 ## Core Features
 
@@ -14,6 +17,7 @@ Roleplay with AI with a focus on strong narration and consistent world and game
 - Long-term memory and passage of time tracking
 - Narrative world state management to reinforce character and world truths
 - Creative tools for managing NPCs, AI-assisted character, and scenario creation with template support
+- Node editor for creating complex scenarios and re-usable modules
 - Context management for character details, world information, past events, and pinned information
 - Customizable templates for all prompts using Jinja2
 - Modern, responsive UI
@@ -23,6 +27,10 @@ Roleplay with AI with a focus on strong narration and consistent world and game
 - [Installation and Getting started](https://vegu-ai.github.io/talemate/)
 - [User Guide](https://vegu-ai.github.io/talemate/user-guide/interacting/)
 
+## Discord Community
+
+Need help? Join the new [Discord community](https://discord.gg/8bGNRmFxMj)
+
 ## Supported APIs
 
 - [OpenAI](https://platform.openai.com/overview)

docs/cleanup.py

@@ -0,0 +1,166 @@
+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:
+        content = f.read()
+    
+    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:]
+            # Only keep references to versioned images
+            parts = os.path.normpath(path).split(os.sep)
+            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'):
+                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 == '.':
+            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():
+            continue
+            
+        for file in files:
+            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.
+    Returns True if any reference is found, False otherwise.
+    """
+    try:
+        # Split the image path to get version and filename
+        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],
+                capture_output=True,
+                text=True
+            )
+            if result.stdout.strip():
+                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')
+    args = parser.parse_args()
+
+    # Convert paths to absolute paths
+    docs_dir = os.path.abspath(args.docs_dir)
+    img_dir = os.path.abspath(args.img_dir)
+
+    print(f"Scanning markdown files in: {docs_dir}")
+    print(f"Looking for versioned images in: {img_dir}")
+
+    # Get all markdown files
+    md_files = scan_markdown_files(docs_dir)
+    print(f"Found {len(md_files)} markdown files")
+
+    # Collect all image references
+    used_images = set()
+    for md_file in md_files:
+        refs = find_image_references(md_file)
+        used_images.update(refs)
+
+    # Get all actual images (only from version directories)
+    all_images = set(find_all_images(img_dir))
+
+    if args.verbose:
+        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}")
+
+    # Find potentially unused images
+    unused_images = all_images - used_images
+
+    # Additional grep validation if not skipped
+    if not args.skip_grep and unused_images:
+        print("\nPerforming additional grep validation...")
+        actually_unused = set()
+        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!")
+        unused_images = actually_unused
+
+    # Report findings
+    print("\nResults:")
+    print(f"Total versioned images found: {len(all_images)}")
+    print(f"Versioned images referenced in markdown: {len(used_images)}")
+    print(f"Unused versioned images: {len(unused_images)}")
+
+    if unused_images:
+        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:
+                full_path = os.path.join(img_dir, img)
+                try:
+                    os.remove(full_path)
+                    print(f"Deleted: {img}")
+                except Exception as e:
+                    print(f"Error deleting {img}: {e}")
+            print("\nDeletion complete")
+    else:
+        print("\nNo unused versioned images found!")
+
+if __name__ == "__main__":
+    main()

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

@@ -126,5 +126,4 @@ class RunPodVLLMClient(ClientBase):
             self.model_name = kwargs["model"]
         if "runpod_id" in kwargs:
             self.api_auth = kwargs["runpod_id"]
-        log.warning("reconfigure", kwargs=kwargs)
         self.set_client(**kwargs)

docs/dev/third-party-reference.md

@@ -0,0 +1,14 @@
+## Third Party API docs
+
+### Chat completions
+
+- [Anthropic](https://docs.anthropic.com/en/api/messages)
+- [Cohere](https://docs.cohere.com/reference/chat)
+- [Google AI](https://ai.google.dev/api/generate-content#v1beta.GenerationConfig)
+- [Groq](https://console.groq.com/docs/api-reference#chat-create)
+- [KoboldCpp](https://lite.koboldai.net/koboldcpp_api#/api/v1)
+- [LMStudio](https://lmstudio.ai/docs/api/rest-api)
+- [Mistral AI](https://docs.mistral.ai/api/)
+- [OpenAI](https://platform.openai.com/docs/api-reference/completions)
+- [TabbyAPI](https://theroyallab.github.io/tabbyAPI/#operation/chat_completion_request_v1_chat_completions_post)
+- [Text-Generation-WebUI](https://github.com/oobabooga/text-generation-webui/blob/main/extensions/openai/typing.py)

docs/getting-started/advanced/.pages

@@ -0,0 +1,3 @@
+nav:
+    - change-host-and-port.md
+    - ...

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

@@ -0,0 +1,102 @@
+# Changing host and port
+
+## Backend
+
+By default, the backend listens on `localhost:5050`.
+
+To run the server on a different host and port, you need to change the values passed to the `--host` and `--port` parameters during startup and also make sure the frontend knows the new values.
+
+### Changing the host and port for the backend
+
+#### :material-linux: Linux
+
+Copy `start.sh` to `start_custom.sh` and edit the `--host` and `--port` parameters in the `uvicorn` command.
+
+```bash
+#!/bin/sh
+. talemate_env/bin/activate
+python 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.
+
+```batch
+start cmd /k "cd talemate_env\Scripts && activate && cd ../../ && python 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`.
+
+```env
+VUE_APP_TALEMATE_BACKEND_WEBSOCKET_URL=ws://localhost:1234
+```
+
+Next rebuild the frontend.
+
+```bash
+cd talemate_frontend
+npm run build
+```
+
+### Start the backend and frontend
+
+Start the backend and frontend as usual.
+
+#### :material-linux: Linux
+
+```bash
+./start_custom.sh
+```
+
+#### :material-microsoft-windows: Windows
+
+```batch
+start_custom.bat
+```
+
+## Frontend
+
+By default, the frontend listens on `localhost:8080`.
+
+To change the frontend host and port, you need to change the values passed to the `--frontend-host` and `--frontend-port` parameters during startup.
+
+### Changing the host and port for the frontend
+
+#### :material-linux: Linux
+
+Copy `start.sh` to `start_custom.sh` and edit the `--frontend-host` and `--frontend-port` parameters.
+
+```bash
+#!/bin/sh
+. talemate_env/bin/activate
+python src/talemate/server/run.py runserver --host 0.0.0.0 --port 5055 \
+--frontend-host localhost --frontend-port 8082
+```
+
+#### :material-microsoft-windows: Windows
+
+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"
+```
+
+### Start the backend and frontend
+
+Start the backend and frontend as usual.
+
+#### :material-linux: Linux
+
+```bash
+./start_custom.sh
+```
+
+#### :material-microsoft-windows: Windows
+
+```batch
+start_custom.bat
+```
+

docs/getting-started/connect-a-client.md

@@ -19,7 +19,7 @@ On the right hand side click the **:material-plus-box: ADD CLIENT** button.
 
 The client configuration window will appear. Here you can choose the type of client you want to add.
 
-![connect a client add client modal](/talemate/img/0.26.0/connect-a-client-add-client-modal.png)
+![connect a client add client modal](/talemate/img/0.30.0/connect-a-client-add-client-modal.png)
 
 ## Choose an API / Client Type
 
@@ -55,7 +55,7 @@ Select the API you want to use and click through to follow the instructions to c
 
 Whenever you add your first client, Talemate will automatically assign it to all agents. Once the client is configured and assigned, all agents should have a green dot next to them. (Or grey if the agent is currently disabled)
 
-![Connect a client assigned](/talemate/img/0.26.0/connect-a-client-ready.png)
+![Connect a client assigned](/talemate/img/0.30.0/connect-a-client-ready.png)
 
 You can tell the client is assigned to the agent by checking the tag beneath the agent name, which will contain the client name if it is assigned.
 

docs/getting-started/installation/linux.md

@@ -1,13 +1,12 @@
 
 ## Quick install instructions
 
-!!! warning
-    python 3.12 is currently not supported.
-
 ### Dependencies
 
+--8<-- "docs/snippets/common.md:python-versions"
+
 1. node.js and npm - see instructions [here](https://nodejs.org/en/download/package-manager/)
-1. python 3.10 or 3.11 - see instructions [here](https://www.python.org/downloads/)
+1. python- see instructions [here](https://www.python.org/downloads/)
 
 ### Installation
 

docs/getting-started/installation/troubleshoot.md

@@ -2,13 +2,17 @@
 
 ## Windows
 
-### Installation fails with "Microsoft Visual C++" error
+### Installation fails with "Microsoft Visual C++" or "ValueError: The onnxruntime python package is not installed." errors
     
-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.
+If your installation errors with a notification to upgrade "Microsoft Visual C++" go to [https://visualstudio.microsoft.com/visual-cpp-build-tools/](https://visualstudio.microsoft.com/visual-cpp-build-tools/) and click "Download Build Tools" and run it.
 
 -  During installation make sure you select the C++ development package (upper left corner)
 -  Run `reinstall.bat` inside talemate directory
 
+### Frontend fails with errors
+
+- ensure none of the directories have special characters in them, this can cause issues with the frontend. so no `(1)` in the directory name.
+
 ## Docker
 
 ### Docker has created `config.yaml` directory

docs/getting-started/installation/windows.md

@@ -1,25 +1,29 @@
 ## Quick install instructions
 
-!!! warning
-    python 3.12 is currently not supported
-
-1. Download and install Python 3.10 or Python 3.11 from the [official Python website](https://www.python.org/downloads/windows/).
+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/)
+    - June 2025: people have reported issues with python 3.13 still, due to some dependencies not being available yet, if you run into issues during installation try downgrading.
 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. Navigate your browser to http://localhost:8080
+1. Once the talemate logo shows up, navigate your browser to 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.
 
 If everything went well, you can proceed to [connect a client](../../connect-a-client).
 
 ## Additional Information
 
-### How to Install Python 3.10 or 3.11
+### 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 version of Python 3.10 or 3.11 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.10 to PATH before you click Install Now.
+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
 
@@ -35,6 +39,13 @@ This batch file is used to set up the project on your local machine. It creates
 
 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.