0.31.0 (#193 )

* some prompt cleanup * prompt tweaks * prompt tweaks * prompt tweaks * set 0.31.0 * relock * rag queries add brief analysis * brief analysis before building rag questions * rag improvements * prompt tweaks * address circular import issues * set 0.30.1 * docs * numpy to 2 * docs * prompt tweaks * prompt tweak * some template cleanup * prompt viewer increase height * fix codemirror highlighting not working * adjust details height * update default * change to log debug * allow response to scale to max height * template cleanup * prompt tweaks * first progress for installing modules to scene * package install logic * package install polish * package install polish * package install polish and fixes * refactor initial world state update and expose setting for it * add `num` property to ModuleProperty to control order of widgets * dynamic storyline package info * fix issue where deactivating player character would cause inconsistencies in the creative tools menui * cruft * add openrouter support * ollama support * refactor how model choices are loaded, so that can be done per client instance as opposed to just per client type * set num_ctx * remove debug messages * ollama tweaks * toggle for whether or not default character gets added to blank talemate scenes * narrator prompt tweaks and template cleanup * cleanup * prompt tweaks and template cleanup * prompt tweaks * fix instructor embeddings * add additional error handling to prevent broken world state templates from breaking the world editor side menu * fix openrouter breaking startup if not configured * remove debug message * promp tweaks * fix example dialogue generation no longer working * prompt tweaks and better showing of dialogue examples in conversation instructions * prompt tweak * add initial startup message * prompt tweaks * fix asset error * move complex acting instructions into the task block * fix content input socket on DynamicInstructions node * log.error with traceback over log.exception since that has a tendency to explode and hang everything * fix usse with number nodes where they would try to execute even if the incoming wire wasnt active * fix issue with editor revision events missing template_vars * DynamicInstruction node should only run if both header and content can resolve * removed remaining references to 90s adventure game writing style * prompt tweaks * support embeddings via client apis (koboldcpp) * fix label on client-api embeddings * fix issue where adding / removing an embedding preset would not be reflected immediately in the memory agent config * remove debug output * prompt tweaks * prompt tweaks * autocomplete passes message object * validate group names to be filename valid * embedded winsows env installs and up to poetry2 * version config * get-pip * relock * pin runpod * no longer needed * remove rapidfuzz dependency * nodejs directly into embedded_node without a versioned middleman dir - also remove defunct local-tts install script * fix update script * update script error handling * update.bat error handling * adjust wording * support loading jinja2 templates node modules in templates/modules * update google model list * client t/s and business indicator - also switch all clients to async streaming * formatting * support coercion for anthropic / google switch to the new google genai sdk upgrade websockets * more coercion fixes * gracefully handle keyboard interrupt * EmitSystemMessage node * allow visual prompt generation without image generation * relock * chromadb to v1 * fix error handling * fix issue where adding client model list would be empty * supress pip install warnings * allow overriding of base urls * remove key from log * add fade effect * tweak request info ux * further clarification of endpoint override api key * world state manager: fix issue that caused max changes setting to disappear from character progress config * fix issue with google safety settings off causing generation failures * update to base url should always reset the client * getattr * support v3 chara card version and attempt to future proof * client based embeddings improvements * more fixes for client based embeddings * use client icon * history management tools progress * history memory ids fixed and added validation * regenerate summary fixes * more history regeneration fixes * fix layered history gen and prompt twweaks * allow regeneration of individual layered history entries * return list of LayeredArchiveEntry * reorg for less code dupelication * new scene message renderer based on marked * add inspect functionality to history viewer * message if no history entries yet * allow adding of history entries manually * allow deletion of history * summarization unslop improvements * fix make charcter real action from worldstate listing * allow overriding length in all context generation isntructioon dialogs * fix issue where extract_list could fail with an unhandled error if the llm response didnt contain a list * update whats'new * fix issues with the new history management tools * fix check * Switch dependency handling to UV (#202) * Migrate from Poetry to uv package manager (#200) * migrate from poetry to uv package manager * Update all installation and startup scripts for uv migration * Fix pyproject.toml for uv - allow direct references for hatchling * Fix PR feedback: Restore removed functionality - Restored embedded Python/Node.js functionality in install.bat and update.bat - Restored environment variable exposure in docker-compose.yml (CUDA_AVAILABLE, port configs) - Fixed GitHub Actions branches (main, prep-* instead of main, dev) - Restored fail-fast: false and cache configuration in test.yml These changes preserve all the functionality that should not be removed during the migration from Poetry to uv. --------- Co-authored-by: Ztripez von Matérn <ztripez@bobby.se> * remove uv.lock from .gitignore * add lock file * fix install issues * warn if unable to remove legacy poetry virt env dir * uv needs to be explicitly installed into the .venv so its available * third time's the charm? * fix windows install scripts * add .venv guard to update.bat * call :die * fix docker venv install * node 21 * fix cuda install * start.bat calls install if needed * sync start-local to other startup scripts * no need to activate venv --------- Co-authored-by: Ztripez <reg@otherland.nu> Co-authored-by: Ztripez von Matérn <ztripez@bobby.se> * ignore hfhub symlink warnings * add openrouter and ollama mentions * update windows install documentation * docs * docs * fix issue with memory agent fingerprint * removing a client that supports embeddings will also remove any embedding functions it created * on invalid embeddings reset to default * docs * typo * formatting * docs * docs * install package * adjust topic * add more obvious way to exit creative mode * when importing character cards immediately persist a usable save after the restoration save --------- Co-authored-by: Ztripez <reg@otherland.nu> Co-authored-by: Ztripez von Matérn <ztripez@bobby.se>
0.30.1 (#190 )
2025-12-24 15:39:34 +01:00 · 2025-06-29 18:06:11 +03:00 · 2025-06-10 21:05:46 +03:00 · 2025-06-03 12:26:12 +03:00
824 changed files with 112521 additions and 18348 deletions
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -0,0 +1,57 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [ main, 'prep-*' ]
+  pull_request:
+    branches: [ 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 uv
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+
+    - name: Cache uv dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/uv
+        key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-uv-${{ matrix.python-version }}-
+
+    - name: Install dependencies
+      run: |
+        uv venv
+        source .venv/bin/activate
+        uv pip install -e ".[dev]"
+
+    - name: Setup configuration file
+      run: |
+        cp config.example.yaml config.yaml
+
+    - name: Download NLTK data
+      run: |
+        source .venv/bin/activate
+        python -c "import nltk; nltk.download('punkt_tab')"
+
+    - name: Run tests
+      run: |
+        source .venv/bin/activate
+        pytest tests/ -p no:warnings 
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,9 @@
 talemate_env
 chroma
 config.yaml
+
+# uv
+.venv/
 templates/llm-prompt/user/*.jinja2
 templates/world-state/*.yaml
 scenes/
@@ -17,4 +20,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/
--- a/.python-version
+++ b/.python-version
@@ -0,0 +1 @@
+3.11
--- a/52
+++ b/52
@@ -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,30 +26,25 @@ 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

+# Create virtual environment and install dependencies
+RUN uv sync
+
 # Conditional PyTorch+CUDA install
 ARG CUDA_AVAILABLE=false
-RUN . /app/talemate_env/bin/activate && \
+RUN . /app/.venv/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; \
+        uv pip uninstall torch torchaudio && \
+        uv pip install torch~=2.7.0 torchaudio~=2.7.0 --index-url https://download.pytorch.org/whl/cu128; \
    fi

 # Stage 3: Final image
@@ -57,8 +56,11 @@ RUN apt-get update && apt-get install -y \
    bash \
    && 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

 # Copy Python source code
 COPY --from=backend-build /app/src /app/src
@@ -83,4 +85,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"]
--- a/README.md
+++ b/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/ss-1.png)|![Screenshot 3](docs/img/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/ss-4.png)|![Screenshot 1](docs/img/Screenshot_15.png)|
-|![Screenshot 2](docs/img/Screenshot_16.png)|![Screenshot 3](docs/img/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)
@@ -31,12 +39,14 @@ Roleplay with AI with a focus on strong narration and consistent world and game
 - [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/)
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -18,4 +18,4 @@ services:
    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"]
--- a/docs/dev/client/example/runpod_vllm/init.py
+++ b/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)
--- a/docs/dev/howto/add-a-worldstate-template-type.md
+++ b/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'},
+]
+```
--- a/docs/getting-started/advanced/change-host-and-port.md
+++ b/docs/getting-started/advanced/change-host-and-port.md
@@ -10,20 +10,19 @@ 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
@@ -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
-```
-
+```
--- a/docs/getting-started/connect-a-client.md
+++ b/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.

--- a/docs/getting-started/installation/linux.md
+++ b/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/)
+1. uv - see instructions [here](https://github.com/astral-sh/uv#installation)

 ### Installation

@@ -26,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

@@ -46,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.
--- a/docs/getting-started/installation/troubleshoot.md
+++ b/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

--- a/docs/getting-started/installation/windows.md
+++ b/docs/getting-started/installation/windows.md
@@ -1,42 +1,32 @@
 ## Quick install instructions

-!!! warning
-    python 3.12 is currently not supported
+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**.

-1. Download and install Python 3.10 or Python 3.11 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. 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
+!!! 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).
+### Optional: CUDA support

-## Additional Information
+If you have an NVIDIA GPU and want CUDA acceleration for larger embedding models:

-### How to Install Python 3.10 or 3.11
+1. Close Talemate (if it is running).
+2. Double-click **`install-cuda.bat`**. This script swaps the CPU-only Torch build for the CUDA 12.8 build.
+3. Start Talemate again via **`start.bat`**.

-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.
+## Maintenance & advanced usage

-### How to Install npm
+| 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. |

-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`.
-
-#### 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.
--- a/docs/img/0.26.0/connect-a-client-add-client-modal.png
+++ b/docs/img/0.26.0/connect-a-client-add-client-modal.png
--- a/docs/img/0.26.0/connect-a-client-ready.png
+++ b/docs/img/0.26.0/connect-a-client-ready.png
--- a/docs/img/0.26.0/inference-presets-1.png
+++ b/docs/img/0.26.0/inference-presets-1.png
--- a/docs/img/0.26.0/scene-tool-character-actions.png
+++ b/docs/img/0.26.0/scene-tool-character-actions.png
--- a/docs/img/0.26.0/scene-tool-creative-actions.png
+++ b/docs/img/0.26.0/scene-tool-creative-actions.png
--- a/docs/img/0.26.0/scene-tool-creative-add-character-1.png
+++ b/docs/img/0.26.0/scene-tool-creative-add-character-1.png
--- a/docs/img/0.26.0/scene-tool-creative-add-character-2.png
+++ b/docs/img/0.26.0/scene-tool-creative-add-character-2.png
--- a/docs/img/0.26.0/scene-tool-creative-add-character-3.png
+++ b/docs/img/0.26.0/scene-tool-creative-add-character-3.png
--- a/docs/img/0.26.0/scene-tool-creative-introduce-2.png
+++ b/docs/img/0.26.0/scene-tool-creative-introduce-2.png
--- a/docs/img/0.26.0/scene-tool-narrator-actions.png
+++ b/docs/img/0.26.0/scene-tool-narrator-actions.png
--- a/docs/img/0.29.0/conversation-general-settings.png
+++ b/docs/img/0.29.0/conversation-general-settings.png
--- a/docs/img/0.30.0/auto-direction-unavailable.png
+++ b/docs/img/0.30.0/auto-direction-unavailable.png
--- a/docs/img/0.30.0/auto-progress-on.png
+++ b/docs/img/0.30.0/auto-progress-on.png
--- a/docs/img/0.30.0/client-ratelimit-notification.png
+++ b/docs/img/0.30.0/client-ratelimit-notification.png
--- a/docs/img/0.30.0/client-ratelimit-popup.png
+++ b/docs/img/0.30.0/client-ratelimit-popup.png
--- a/docs/img/0.30.0/client-ratelimit.png
+++ b/docs/img/0.30.0/client-ratelimit.png
--- a/docs/img/0.30.0/connect-a-client-add-client-modal.png
+++ b/docs/img/0.30.0/connect-a-client-add-client-modal.png
--- a/docs/img/0.30.0/connect-a-client-ready.png
+++ b/docs/img/0.30.0/connect-a-client-ready.png
--- a/docs/img/0.30.0/conversation-content-settings.png
+++ b/docs/img/0.30.0/conversation-content-settings.png
--- a/docs/img/0.30.0/conversation-general-settings.png
+++ b/docs/img/0.30.0/conversation-general-settings.png
--- a/docs/img/0.30.0/create-template-scene-type.png
+++ b/docs/img/0.30.0/create-template-scene-type.png
--- a/docs/img/0.30.0/creator-agent-item.png
+++ b/docs/img/0.30.0/creator-agent-item.png
--- a/docs/img/0.30.0/creator-autocomplete-settings.png
+++ b/docs/img/0.30.0/creator-autocomplete-settings.png
--- a/docs/img/0.30.0/director-auto-direction-settings.png
+++ b/docs/img/0.30.0/director-auto-direction-settings.png
--- a/docs/img/0.30.0/editor-has-messages.png
+++ b/docs/img/0.30.0/editor-has-messages.png
--- a/docs/img/0.30.0/editor-revision-history.png
+++ b/docs/img/0.30.0/editor-revision-history.png
--- a/docs/img/0.30.0/editor-revision-issue-identified.png
+++ b/docs/img/0.30.0/editor-revision-issue-identified.png
--- a/docs/img/0.30.0/editor-revision-rewriting.png
+++ b/docs/img/0.30.0/editor-revision-rewriting.png
--- a/docs/img/0.30.0/editor-revision-settings-dedupe.png
+++ b/docs/img/0.30.0/editor-revision-settings-dedupe.png
--- a/docs/img/0.30.0/editor-revision-settings-rewrite.png
+++ b/docs/img/0.30.0/editor-revision-settings-rewrite.png
--- a/docs/img/0.30.0/editor-revision-settings-unslop.png
+++ b/docs/img/0.30.0/editor-revision-settings-unslop.png
--- a/docs/img/0.30.0/inference-preset-group-applied.png
+++ b/docs/img/0.30.0/inference-preset-group-applied.png
--- a/docs/img/0.30.0/inference-preset-group-apply.png
+++ b/docs/img/0.30.0/inference-preset-group-apply.png
--- a/docs/img/0.30.0/inference-presets-1.png
+++ b/docs/img/0.30.0/inference-presets-1.png
--- a/docs/img/0.30.0/inference-presets-custom-group-1.png
+++ b/docs/img/0.30.0/inference-presets-custom-group-1.png
--- a/docs/img/0.30.0/inference-presets-custom-group-2.png
+++ b/docs/img/0.30.0/inference-presets-custom-group-2.png
--- a/docs/img/0.30.0/save-graph.png
+++ b/docs/img/0.30.0/save-graph.png
--- a/docs/img/0.30.0/scene-tool-character-actions.png
+++ b/docs/img/0.30.0/scene-tool-character-actions.png
--- a/docs/img/0.30.0/scene-tool-creative-actions.png
+++ b/docs/img/0.30.0/scene-tool-creative-actions.png
--- a/docs/img/0.30.0/scene-tool-creative-introduce-2.png
+++ b/docs/img/0.30.0/scene-tool-creative-introduce-2.png
--- a/docs/img/0.30.0/scene-tool-intro-char-1.png
+++ b/docs/img/0.30.0/scene-tool-intro-char-1.png
--- a/docs/img/0.30.0/scene-tool-intro-char-templates.png
+++ b/docs/img/0.30.0/scene-tool-intro-char-templates.png
--- a/docs/img/0.30.0/scene-tool-narrator-actions.png
+++ b/docs/img/0.30.0/scene-tool-narrator-actions.png
--- a/docs/img/0.30.0/writing-style-phrase-detection.png
+++ b/docs/img/0.30.0/writing-style-phrase-detection.png
--- a/docs/img/0.31.0/client-endpoint-override.png
+++ b/docs/img/0.31.0/client-endpoint-override.png
--- a/docs/img/0.31.0/client-ollama-no-model.png
+++ b/docs/img/0.31.0/client-ollama-no-model.png
--- a/docs/img/0.31.0/client-ollama-offline.png
+++ b/docs/img/0.31.0/client-ollama-offline.png
--- a/docs/img/0.31.0/client-ollama-ready.png
+++ b/docs/img/0.31.0/client-ollama-ready.png
--- a/docs/img/0.31.0/client-ollama-select-model.png
+++ b/docs/img/0.31.0/client-ollama-select-model.png
--- a/docs/img/0.31.0/client-ollama.png
+++ b/docs/img/0.31.0/client-ollama.png
--- a/docs/img/0.31.0/client-openrouter-no-api-key.png
+++ b/docs/img/0.31.0/client-openrouter-no-api-key.png
--- a/docs/img/0.31.0/client-openrouter-ready.png
+++ b/docs/img/0.31.0/client-openrouter-ready.png
--- a/docs/img/0.31.0/client-openrouter-select-model.png
+++ b/docs/img/0.31.0/client-openrouter-select-model.png
--- a/docs/img/0.31.0/client-openrouter.png
+++ b/docs/img/0.31.0/client-openrouter.png
--- a/docs/img/0.31.0/history-add-entry.png
+++ b/docs/img/0.31.0/history-add-entry.png
--- a/docs/img/0.31.0/history-regenerate-all.png
+++ b/docs/img/0.31.0/history-regenerate-all.png
--- a/docs/img/0.31.0/history.png
+++ b/docs/img/0.31.0/history.png
--- a/docs/img/0.31.0/koboldcpp-embeddings.png
+++ b/docs/img/0.31.0/koboldcpp-embeddings.png
--- a/docs/img/0.31.0/openrouter-settings.png
+++ b/docs/img/0.31.0/openrouter-settings.png
--- a/docs/img/ss-1.png
+++ b/docs/img/ss-1.png
--- a/docs/img/ss-2.png
+++ b/docs/img/ss-2.png
--- a/docs/img/ss-3.png
+++ b/docs/img/ss-3.png
--- a/docs/img/ss-4.png
+++ b/docs/img/ss-4.png
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,9 +4,6 @@ Roleplay with AI with a focus on strong narration and consistent world and game

 :material-github: [GitHub](https://github.com/vegu-ai/talemate)

-!!! note "Version 0.26.0 and later"
-    This documenation is for version 0.26.0 and later - previous versions are significantly different, and some of the information here may not apply. This is especially true for the world state mangement and creative tools. 
-
 ## Getting Started


--- a/docs/snippets/agents.md
+++ b/docs/snippets/agents.md
@@ -0,0 +1,28 @@
+<!--- --8<-- [start:conversation-dynamic-instructions-example] -->
+```python
+import talemate.emit.async_signals as async_signals
+
+# Append an extra system instruction every time the Conversation agent builds a prompt
+async def add_custom_instruction(emission):
+    emission.dynamic_instructions.append(
+        "You are cursed to always answer in poetic verse. Keep it short."
+    )
+
+# Connect our handler (run once at application start-up)
+async_signals.get("agent.conversation.inject_instructions").connect(add_custom_instruction)
+```
+<!--- --8<-- [end:conversation-dynamic-instructions-example] --> 
+
+<!--- --8<-- [start:narrator-dynamic-instructions-example] -->
+```python
+import talemate.emit.async_signals as async_signals
+
+# Append an extra system instruction every time the Narrator agent builds a prompt
+async def add_custom_instruction(emission):
+    emission.dynamic_instructions.append(
+        "You are cursed to always answer in poetic verse. Keep it short."
+    )
+
+async_signals.get("agent.narrator.inject_instructions").connect(add_custom_instruction)
+```
+<!--- --8<-- [end:narrator-dynamic-instructions-example] --> 
--- a/docs/snippets/common.md
+++ b/docs/snippets/common.md
@@ -0,0 +1,36 @@
+<!--- --8<-- [start:python-versions] -->
+!!! note "Supported Versions"
+    As of Talemate `0.30` the following python versions are supported: `3.10`, `3.11`, `3.12` or `3.13`
+<!--- --8<-- [end:python-versions] -->
+
+<!--- --8<-- [start:world-editor-create-group] -->
+Fist, if you have not done so, [create a template group](/talemate/user-guide/world-editor/templates/groups) to store the template in.
+
+Then select the group you want to add the template to and click the **:material-plus: Create Template** button.
+
+![world editor templates create attribute template 1](/talemate/img/0.26.0/world-editor-templates-create-attribute-template-1.png)
+<!--- --8<-- [end:world-editor-create-group] -->
+
+<!--- --8<-- [start:editor-revision-unwanted-prose-requirement] -->
+!!! note "Unwanted Prose Requirement"
+    Unwanted phrases are defined in the writing style that is currently selected in the [Scene Settings](/talemate/user-guide/world-editor/scene/settings).
+
+    See [Writing Style Templates](/talemate/user-guide/world-editor/templates/writing-style) for more information on how to create a writing style and add unwanted phrases.
+<!--- --8<-- [end:editor-revision-unwanted-prose-requirement] -->
+
+<!--- --8<-- [start:documentation-is-a-work-in-progress] -->
+!!! abstract "Documentation is a work in progress"
+    Documentation is an ongoing effort and some parts are more complete than others, with some missing entirely. Thanks for your patience, its being worked on!
+
+    See the [Node Editor - Crash Course](/talemate/user-guide/howto/infinity-quest-dynamic/) tutorial for an extensive introduction to the node editor.
+<!--- --8<-- [end:documentation-is-a-work-in-progress] -->
+
+<!--- --8<-- [start:save-scene-project] -->
+!!! success "Save!"
+    **:material-content-save: Save** the scene project.
+<!--- --8<-- [end:save-scene-project] -->
+
+<!--- --8<-- [start:save-graph] -->
+!!! success "Save!"
+    **:material-check-circle-outline: Save** the module. 
+<!--- --8<-- [end:save-graph] -->
--- a/docs/style.css
+++ b/docs/style.css
@@ -0,0 +1,60 @@
+pre > code {
+    white-space: pre-wrap;
+}
+
+/* Custom load admonition */
+.md-typeset .admonition.load,
+.md-typeset details.load {
+    border-color: #9c27b0;
+}
+
+.md-typeset .load > .admonition-title,
+.md-typeset .load > summary {
+    background-color: rgba(156, 39, 176, 0.1);
+    border-color: #9c27b0;
+}
+
+.md-typeset .load > .admonition-title::before,
+.md-typeset .load > summary::before {
+    background-color: #9c27b0;
+    -webkit-mask-image: var(--md-admonition-icon--load);
+            mask-image: var(--md-admonition-icon--load);
+}
+
+/* custom event payload admonition */
+.md-typeset .admonition.payload,
+.md-typeset details.payload {
+    border-color: #616799;
+}
+
+.md-typeset .payload > .admonition-title,
+.md-typeset .payload > summary {
+    background-color: rgba(97, 103, 153, 0.1);
+    border-color: #616799;
+}
+
+.md-typeset .payload > .admonition-title::before,
+.md-typeset .payload > summary::before {
+    background-color: #616799;
+    -webkit-mask-image: var(--md-admonition-icon--payload);
+    mask-image: var(--md-admonition-icon--payload);
+}
+
+/* custom learn more admonition (605381 color) */
+.md-typeset .admonition.learn-more,
+.md-typeset details.learn-more {
+    border-color: #605381;
+}
+
+.md-typeset .learn-more > .admonition-title,
+.md-typeset .learn-more > summary {
+    background-color: rgba(96, 83, 129, 0.1);
+    border-color: #605381;
+}
+
+.md-typeset .learn-more > .admonition-title::before,
+.md-typeset .learn-more > summary::before {
+    background-color: #6f5aa3;
+    -webkit-mask-image: var(--md-admonition-icon--learn-more);
+    mask-image: var(--md-admonition-icon--learn-more);
+}
--- a/docs/user-guide/agents/conversation/index.md
+++ b/docs/user-guide/agents/conversation/index.md
@@ -1,5 +1,5 @@
 # Overview

-The conversation agent drives the AI generated dialogue.
+Also known as the **Actor** agent it is responsible for generating character driven dialogue and actions.

-It rquires a text-generation client to be configured and assigned.
+It requires a text-generation client to be configured and assigned.
--- a/docs/user-guide/agents/conversation/settings.md
+++ b/docs/user-guide/agents/conversation/settings.md
@@ -2,7 +2,7 @@

 ## General

-![Conversation agent general settings](/talemate/img/0.29.0/conversation-general-settings.png)
+![Conversation agent general settings](/talemate/img/0.30.0/conversation-general-settings.png)

 !!! note "Inference perameters"
    Inference parameters are NOT configured through any individual agent.
@@ -17,17 +17,11 @@ The text-generation client to use for conversation generation.

 If checked and talemate detects a repetitive response (based on a threshold), it will automatically re-generate the resposne with increased randomness parameters.

-##### Natural Flow
+!!! note "Deprecated"
+    This will soon be removed in favor of the new [Editor Agent Revision Action](/talemate/user-guide/agents/editor/settings#revision)

-When there are multiple characters in the scene, this will help the AI to keep the conversation flowing naturally, making sure turns are somewhat evenly distributed, and also checking that the most relevant character gets the next turn, based on the context.
-
-##### Max. Auto turns
-
-Maximum turns the AI gets in succession, before the player gets a turn no matter what.
-
-##### Max. Idle turns
-
-The maximum number of turns a character can go without speaking before the AI will force them to speak.
+!!! note "Natural flow was moved"
+    The natural flow settings have been moved to the [Director Agent](/talemate/user-guide/agents/director) settings as part of the auto direction feature.

 ## Generation

@@ -64,6 +58,14 @@ General, broad isntructions for ALL actors in the scene. This will be appended t

 If > 0 will offset the instructions for the actor (both broad and character specific) into the history by that many turns. Some LLMs struggle to generate coherent continuations if the scene is interrupted by instructions right before the AI is asked to generate dialogue. This allows to shift the instruction backwards.

+## :material-script-text: Content
+
+![Conversation agent content settings](/talemate/img/0.30.0/conversation-content-settings.png)
+
+Enable this setting to apply a writing style to the generated content.
+
+Make sure the a writing style is selected in the [Scene Settings](/talemate/user-guide/world-editor/scene/settings) to apply the writing style to the generated content.
+
 ## Long Term Memory

 --8<-- "docs/snippets/tips.md:agent_long_term_memory_settings"
--- a/docs/user-guide/agents/creator/index.md
+++ b/docs/user-guide/agents/creator/index.md
@@ -1,5 +1,3 @@
 # Overview

-The creator agent is responsible for creating the AI generated content. It requires a text-generation client to be configured and assigned.
-
-Currently exposes no settings to configure the agent itself.
+Used tor most creative tasks that involves the creation of new context.
--- a/docs/user-guide/agents/creator/settings.md
+++ b/docs/user-guide/agents/creator/settings.md
@@ -0,0 +1,21 @@
+# Settings
+
+Open by clicking the **Creator** agent in the agent list.
+
+![Creator agent item](/talemate/img/0.30.0/creator-agent-item.png)
+
+## Long Term Memory
+
+--8<-- "docs/snippets/tips.md:agent_long_term_memory_settings"
+
+## Autocomplete
+
+![Conversation agent autocomplete settings](/talemate/img/0.30.0/creator-autocomplete-settings.png)
+
+##### Dialogue Suggestion Length
+
+How many tokens to generate (max.) when autocompleting character actions.
+
+##### Narrative Suggestion Length
+
+How many tokens to generate (max.) when autocompleting narrative text.
--- a/docs/user-guide/agents/director/index.md
+++ b/docs/user-guide/agents/director/index.md
@@ -7,4 +7,10 @@ In the future it will shift / expose more of a game master role, controlling the
 Will occasionally generate clickable choices for the user during scene progression. This can be used to allow the user to make choices that will affect the scene or the story in some way without having to manually type out the choice.

 ### Guide Scene
-Will use the summarizer agent's scene analysis to guide characters and the narrator for the next generation, hopefully improving the quality of the generated content.
+Will use the summarizer agent's scene analysis to guide characters and the narrator for the next generation, hopefully improving the quality of the generated content.
+
+### Auto Direction
+A very experimental feature that will cause the director to attempt to direct the scene automatically, instructing actors or the narrator to move the scene forward according to the story and scene intention.
+
+!!! note "Experimental"
+    This is the first iteration of this feature and is very much a work in progress. It will likely change substantially in the future.
--- a/docs/user-guide/agents/director/settings.md
+++ b/docs/user-guide/agents/director/settings.md
@@ -88,4 +88,70 @@ If enabled the director will guide the narrator in the scene.

 ##### Max. Guidance Length

-The maximum number of tokens for the guidance. (e.g., how long should the guidance be).
+The maximum number of tokens for the guidance. (e.g., how long should the guidance be).
+
+## Auto Direction
+
+A very experimental first attempt at giving the reigns to the director to direct the scene automatically.
+
+Currently it can only instruct actors and the narrator, but different actions will be exposed in the future. This is very early in the development cycle and will likely go through substantial changes.
+
+!!! note "Both overall and current intent need to be set for auto-direction to be available"
+    If either the overall or current scene intention is not set, the auto-direction feature will not be available.
+
+    ![Auto Direction Unavailable](/talemate/img/0.30.0/auto-direction-unavailable.png)
+
+    Story and scene intentions are set in the [Scene Direction](/talemate/user-guide/world-editor/scene/direction) section of the World Editor.
+
+![Director agent auto direction settings](/talemate/img/0.30.0/director-auto-direction-settings.png)
+
+##### Enable Auto Direction
+
+Turn auto direction on and off. 
+
+!!! note "Auto progress needs to also be enabled"
+    If auto direction is enabled, auto progress needs to be enabled as well.
+
+    ![Auto Progress On](/talemate/img/0.30.0/auto-progress-on.png)
+#### Natural flow
+
+Will place strict limits on actor turns based on the provided constraints. That means regardless of what the director would like to do, the actor availability will always take precedence.
+
+##### Max. Auto turns
+
+Maximum turns the AI gets in succession (spread accross characters). When this limit is reached, the player will get a turn no matter what.
+
+##### Max. Idle turns
+
+The maximum number of turns a character can go without speaking before they are automatically given a turn by the director. (per character)
+
+##### Max. Repeat Turns
+
+The maximum number of times a character can go in succession without speaking before the director will force them to speak. (per character)
+
+
+#### Instructions
+
+##### Instruct Actors
+
+Allow the director to instruct actors.
+
+##### Instruct Narrator
+
+Allow the director to instruct the narrator.
+
+##### Instruct Frequency
+
+Only pass on instructions to the actors or the narrator every N turns.
+
+!!! note "Evaluation of the scene happens regardless"
+    The director will evaluate the scene after each round regardless of the frequency. This setting merely controls how often the instructions are actually passed on.
+
+##### Evaluate Scene Intention
+
+Allows the director to evaluate the current scene phase and switch to a different scene type or set a new intention.
+
+The number of turns between evaluations. (0 = NEVER)
+
+!!! note "Recommended to leave at 0 (never)"
+    This isn't really working well at this point, so recommended to leave at 0 (never)
--- a/docs/user-guide/agents/editor/revisions.md
+++ b/docs/user-guide/agents/editor/revisions.md
@@ -0,0 +1,17 @@
+Revisions were introduced in version `0.30.0` and allow the editor to detect and fix repetition and unwanted prose.
+
+Please see the [settings](/talemate/user-guide/agents/editor/settings/#revision) for more information on how to configure **:material-typewriter: Revisions**.
+
+Once automatic revisions are enabled, if the editor finds an issue in a message you will see the following status updates:
+
+![Editor revision status](/talemate/img/0.30.0/editor-revision-issue-identified.png)
+
+![Editor revision status](/talemate/img/0.30.0/editor-revision-rewriting.png)
+
+Once the revision is complete the editor agent will indicate that that it made some changes by showing the :material-message-text-outline: icon next to its name.
+
+![Editor revision status](/talemate/img/0.30.0/editor-has-messages.png)
+
+Click the :material-message-text-outline: icon to open the Agent Messages dialog to view the changes.
+
+![Editor revision messages](/talemate/img/0.30.0/editor-revision-history.png)
--- a/docs/user-guide/agents/editor/settings.md
+++ b/docs/user-guide/agents/editor/settings.md
@@ -1,5 +1,7 @@
 # Settings

+## General
+
 ![Editor agent settings](/talemate/img/0.29.0/editor-agent-settings.png)

 ##### Fix exposition
@@ -20,12 +22,125 @@ Applies the same rules as above to the user input messages.

 Will take the generate message and attempt to add more detail to it.

-##### Fix continuity errors
+## Long Term Memory

-Will attempt to fix continuity errors in the generated text.
+--8<-- "docs/snippets/tips.md:agent_long_term_memory_settings"

-!!! example "Experimental, and doesn't work most of the time"
-    There is something about accurately identifying continuity errors that is currently very 
-    difficult for AI to do. So this feature is very hit and miss. More miss than hit.
+## Revision

-    Also takes long to process, so probably leave it turned off.
+![Editor agent revision settings](/talemate/img/0.30.0/editor-revision-settings-dedupe.png)
+
+When :material-typewriter: revision is enabled the editor will analyze and attempt to fix character messages, narrator messages, and contextual generation (such as character attributes, details, world context, etc.).
+
+Currently it can detect the following issues:
+
+- Repetition of phrases / concepts
+- Unwanted prose as defined in the writing style
+
+The revision action is split into three parts:
+
+- Find any issues through fuzzy, regex and semantic similarity (embeddings) matching
+- Analyze the issues and plan a fix
+- Apply the fix
+
+This means it comes at a noticable delay IF it finds issues, but the improvements may be worth it.
+
+##### Enable Revision
+
+Check this to enable revision.
+
+##### Automatic Revision
+
+Check this to enable automatic revision - this will analyze each incoming actor or narrator message and attempt to fix it if there are issues.
+
+##### Automatic Revision Targets
+
+When automatic revision is enabled, you can choose which types of messages to automatically revise:
+
+- **Character Messages** - Automatically revise actor actions and dialogue
+- **Narration Messages** - Automatically revise narrator actions and descriptions  
+- **Contextual generation** - Automatically revise generated context such as character attributes, details, world context, scene intros, etc.
+
+By default, both Character Messages and Narration Messages are enabled. You can enable or disable each type independently based on your preferences.
+
+##### Revision Method
+
+Which method to use to fix issues. 
+
+- `Dedupe (Fast and dumb)` - this is the default
+- `Unslop (AI assisted)` - calls 1 additional prompt after generation to remove repetition, purple prose, unnatural dialogue, and over-description
+- `Targeted Rewrite (AI assisted)` - analyzes text for specific issues and rewrites only problematic parts
+
+**Dedupe (Fast and dumb)**
+
+![Editor agent revision settings - Dedupe](/talemate/img/0.30.0/editor-revision-settings-dedupe.png)
+
+When **Dedupe** is active it will be restricted to finding repetition and removing it without replacing it with something else, nor understanding the intent or context, so it may sometimes cause disjointed dialogue. This method is much faster as it will never prompt the AI for analysis and fixes. (If repetition detection is set to semantic similarity, it will still use the embedding function to find repetition, but it will not prompt the AI for analysis and fixes.)
+
+**Unslop (AI assisted)**
+
+![Editor agent revision settings - Unslop](/talemate/img/0.30.0/editor-revision-settings-unslop.png)
+
+When **Unslop** is active, it calls 1 additional prompt after a generation and will attempt to remove repetition, purple prose, unnatural dialogue, and over-description. May cause details to be lost. This is a general-purpose cleanup method that can also use unwanted prose detection when enabled.
+
+**Targeted Rewrite (AI assisted)**
+
+![Editor agent revision settings - Targeted Rewrite](/talemate/img/0.30.0/editor-revision-settings-rewrite.png)
+
+When **Targeted Rewrite** is active, unwanted prose detection becomes available and when issues are detected the AI will attempt to rewrite the message to fix the issues. This method checks for specific problems first, then only rewrites if enough issues are found.
+
+#### Repetition
+
+##### Repetition Detection Method
+
+How is repetition detected.
+
+- `Fuzzy` - fuzzy matching will match based on character-level similarity, finding text that is approximately the same with small differences (like typos, missing letters, or minor variations). This is faster but less context-aware than semantic matching.
+- `Semantic Similarity` - will match based on the semantic meaning of the text using the Memory Agent's embedding function. (default)
+
+!!! warning "Semantic Similarity"
+    Uses the memory agent's embedding function to compare the text. Will use batching when available, but has the potential to do A LOT of calls to the embedding model.
+
+##### Similarity Threshold
+
+How similar does the text need to be to be considered repetitive. (50 - 100%)
+
+You want to keep this relatively high.
+
+##### Repetition Range
+
+This is the number of **MESSAGES** to consider in the history when checking for repetition.
+
+At its default of `15` it means the last 15 messages will be considered.
+
+##### Repetition Min. Length
+
+The minimum length of a phrase (in characters) to be considered for repetition. Shorter phrases will be ignored.
+
+### AI-Assisted Methods (Unslop & Targeted Rewrite)
+
+Once switched to either **Unslop** or **Targeted Rewrite** mode, additional settings become available.
+
+#### Preferences for Rewriting (Targeted Rewrite only)
+
+##### Test parts of sentences, split on commas
+
+If active this means that when a sentence doesn't produce a hit, if it has one or more commas it will split the sentence on the commas and test each part individually.
+
+##### Minimum issues
+
+The minimum amount of issues that need to be detected to trigger a rewrite.
+
+#### Unwanted Prose (Both Unslop & Targeted Rewrite)
+
+##### Detect Unwanted Prose
+
+Check this to enable unwanted prose detection. Available for both **Unslop** and **Targeted Rewrite** methods.
+
+--8<-- "docs/snippets/common.md:editor-revision-unwanted-prose-requirement"
+
+##### Unwanted Prose Threshold
+
+Similarity threshold for unwanted prose detection. (0.4 - 1.0)
+
+You want to keep this relatively high.
--- a/docs/user-guide/agents/index.md
+++ b/docs/user-guide/agents/index.md
@@ -14,6 +14,10 @@ Used for creative tasks like scene and character generation

 Will eventually become a Game Master type agent. Right now used for some very rudimentary scene direction. Allows complex scene control via the scoped api scripting.

+### Editor
+
+Will try to correct markup and optionally revise text to fix repetition and unwanted prose.
+
 ### Long-term Memory

 Attempts to select and add relevant information to the current context window.
--- a/docs/user-guide/agents/memory/embeddings.md
+++ b/docs/user-guide/agents/memory/embeddings.md
@@ -21,6 +21,12 @@ Sentence transformer model that is decently fast and accurate and will likely be

 ### Instructor Models

+!!! warning "Support of these likely deprecated"
+    Its become increasingly difficult to install support for these while keeping other dependencies up to date.
+    See [this issue](https://github.com/vegu-ai/talemate/issues/176) for more details.
+
+    Use the `Alibaba-NLP/Gte-Base-En-V1.5` embedding instead, its pretty close in accuracy and much smaller.
+
 Instructor embeddings, coming in three sizes: `base`, `large`, and `xl`. XL is the most accurate but also has the biggest memory footprint and is the slowest. Using `cuda` is recommended for the `xl` and `large` models.

 ### OpenAI text-embedding-3-small
--- a/docs/user-guide/agents/memory/koboldcpp.md
+++ b/docs/user-guide/agents/memory/koboldcpp.md
@@ -0,0 +1,25 @@
+# KoboldCpp Embeddings
+
+Talemate can leverage an embeddings model that is already loaded in your KoboldCpp instance.
+
+## 1. Start KoboldCpp with an embeddings model
+
+Launch KoboldCpp with the `--embeddingsmodel` flag so that it loads an embeddings-capable GGUF model alongside the main LLM:
+
+```bash
+koboldcpp_cu12.exe --model google_gemma-3-27b-it-Q6_K.gguf --embeddingsmodel bge-large-en-v1.5.Q8_0.gguf
+```
+
+## 2. Talemate will pick it up automatically
+
+When Talemate starts, the **Memory** agent probes every connected client that advertises embedding support. If it detects that your KoboldCpp instance has an embeddings model loaded:
+
+1. The Memory backend switches the current embedding to **Client API**.
+2. The `client` field in the agent details shows the name of the KoboldCpp client.
+3. A banner informs you that Talemate has switched to the new embedding. <!-- stub: screenshot -->
+
+![Memory agent automatically switched to KoboldCpp embeddings](/talemate/img/0.31.0/koboldcpp-embeddings.png)
+
+## 3. Reverting to a local embedding
+
+Open the memory agent settings and pick a different embedding. See [Memory agent settings](/talemate/user-guide/agents/memory/settings).
--- a/docs/user-guide/apis/.pages
+++ b/docs/user-guide/apis/.pages
@@ -5,5 +5,6 @@ nav:
    - Google Cloud: google.md
    - Groq: groq.md
    - Mistral.ai: mistral.md
+    - OpenRouter: openrouter.md
    - OpenAI: openai.md
    - ...
--- a/docs/user-guide/apis/openrouter.md
+++ b/docs/user-guide/apis/openrouter.md
@@ -0,0 +1,11 @@
+# OpenRouter API Setup
+
+Talemate can use any model accessible through OpenRouter.
+
+You need an OpenRouter API key and must set it in the application config. You can create and manage keys in your OpenRouter dashboard at [https://openrouter.ai/keys](https://openrouter.ai/keys).
+
+Once you have generated a key open the Talemate settings, switch to the `APPLICATION` tab and then select the `OPENROUTER API` category. Paste your key in the **API Key** field.
+
+![OpenRouter API settings](/talemate/img/0.31.0/openrouter-settings.png)
+
+Finally click **Save** to store the credentials.
--- a/docs/user-guide/clients/.pages
+++ b/docs/user-guide/clients/.pages
@@ -4,4 +4,5 @@ nav:
    - Recommended Local Models: recommended-models.md
    - Inference Presets: presets.md
    - Client Types: types
+    - Endpoint Override: endpoint-override.md
    - ...
--- a/docs/user-guide/clients/endpoint-override.md
+++ b/docs/user-guide/clients/endpoint-override.md
@@ -0,0 +1,24 @@
+# Endpoint Override
+
+Starting in version 0.31.0 it is now possible for some of the remote clients to override the endpoint used for the API.
+
+THis is helpful wehn you want to point the client at a proxy gateway to serve the api instead (LiteLLM for example).
+
+!!! warning "Only use trusted endpoints"
+    Only use endpoints that you trust and NEVER used your actual API key with them, unless you are hosting your endpoint proxy yourself.
+
+    If you need to provide an api key there is a separate field for that specifically in the endpoint override settings.
+
+## How to use
+
+Clients that support it will have a tab in their settings that allows you to override the endpoint.
+
+![Endpoint Override](/talemate/img/0.31.0/client-endpoint-override.png)
+
+##### Base URL
+
+The base URL of the endpoint. For example, `http://localhost:4000` if you're running a local LiteLLM gateway,
+
+##### API Key
+
+The API key to use for the endpoint. This is only required if the endpoint requires an API key. This is **NOT** the API key you would use for the official API. For LiteLLM for example this could be the `general_settings.master_key` value.
--- a/docs/user-guide/clients/presets.md
+++ b/docs/user-guide/clients/presets.md
@@ -8,9 +8,9 @@ If you wish to alter the inference parameters sent with the generation requests

 ![open settings](/talemate/img/0.26.0/open-settings.png)

-Navigate to the :material-tune: **Presets** tab then select the preset you wish to edit.
+Navigate to the :material-tune: **Presets** tab then select the :material-matrix: **Inference** tab.

-![selected preset](/talemate/img/0.26.0/inference-presets-1.png)
+![selected preset](/talemate/img/0.30.0/inference-presets-1.png)

 !!! warning
    Not all clients support all parameters, and generally it is assumed that the client implementation handles the parameters in a sane way, especially if values are passed for all of them. All presets are used and will be selected depending on the action the agent is performing. If you don't know what these mean, it is recommended to leave them as they are.
@@ -52,4 +52,28 @@ Used mostly for the director when directing the scene flow. Need to be creative

 ### Summarization

-Used for summarizing the scene progress into narrative text.
+Used for summarizing the scene progress into narrative text.
+
+
+## Preset Groups
+
+Initially there is a `Default` group in which the presets are edited, but if you want you can create additional groups to create - for example - model / client specific presets.
+
+To add a new group, type the title in to the **New Group Name** field in the upper right and press `Enter`.
+
+![new group](/talemate/img/0.30.0/inference-presets-custom-group-1.png)
+
+
+The new group will be added and automatically selected for editing.
+
+![new group](/talemate/img/0.30.0/inference-presets-custom-group-2.png)
+
+Once you have adjusted the presets to your liking you can save the group by clicking the :material-content-save: **Save** button.
+
+### Setting the group for the client
+
+In the client listing find the :material-tune: selected preset and click it to expand the meny containing the groups.
+
+![select group](/talemate/img/0.30.0/inference-preset-group-apply.png)
+
+![select group](/talemate/img/0.30.0/inference-preset-group-applied.png)
--- a/docs/user-guide/clients/rate-limiting.md
+++ b/docs/user-guide/clients/rate-limiting.md
@@ -0,0 +1,19 @@
+# Rate Limiting
+
+You can rate limit a client to N requests per minute.
+
+![Rate limit](/talemate/img/0.30.0/client-ratelimit.png)
+
+Once the limit is hit you will get a popup notification.
+
+![Rate limit popup](/talemate/img/0.30.0/client-ratelimit-popup.png)
+
+Here you can either choose to wait for the rate limit to reset, or to abort the generation.
+
+If you abort the generation, the current stack of actions will be canceled and control will be given back to the user. This is essentially the same as Cancelling the generation through normal means.
+
+If you chose to wait the notification will collapse to the top of the screen with a timer counting down the remaining time.
+
+Clicking the notification will expand it again.
+
+![Rate limit notification](/talemate/img/0.30.0/client-ratelimit-notification.png)
--- a/docs/user-guide/clients/types/.pages
+++ b/docs/user-guide/clients/types/.pages
@@ -8,6 +8,8 @@ nav:
    - Mistral.ai: mistral.md
    - OpenAI: openai.md
    - OpenAI Compatible: openai-compatible.md
+    - Ollama: ollama.md
+    - OpenRouter: openrouter.md
    - TabbyAPI: tabbyapi.md
    - Text-Generation-WebUI: text-generation-webui.md
    - ...
--- a/docs/user-guide/clients/types/ollama.md
+++ b/docs/user-guide/clients/types/ollama.md
@@ -0,0 +1,59 @@
+# Ollama Client
+
+If you want to add an Ollama client, change the `Client Type` to `Ollama`.
+
+![Client Ollama](/talemate/img/0.31.0/client-ollama.png)
+
+Click `Save` to add the client.
+
+### Ollama Server
+
+The client should appear in the clients list. Talemate will ping the Ollama server to verify that it is running. If the server is not reachable you will see a warning.
+
+![Client ollama offline](/talemate/img/0.31.0/client-ollama-offline.png)
+
+Make sure that the Ollama server is running (by default at `http://localhost:11434`) and that the model you want to use has been pulled.
+
+It may also show a yellow dot next to it, saying that there is no model loaded.
+
+![Client ollama no model](/talemate/img/0.31.0/client-ollama-no-model.png)
+
+Open the client settings by clicking the :material-cogs: icon, to select a model.
+
+![Ollama settings](/talemate/img/0.31.0/client-ollama-select-model.png)
+
+Click save and the client should have a green dot next to it, indicating that it is ready to go.
+
+![Client ollama ready](/talemate/img/0.31.0/client-ollama-ready.png)
+
+### Settings
+
+##### Client Name
+
+A unique name for the client that makes sense to you.
+
+##### API URL
+
+The base URL where the Ollama HTTP endpoint is running. Defaults to `http://localhost:11434`.
+
+##### Model
+
+Name of the Ollama model to use. Talemate will automatically fetch the list of models that are currently available in your local Ollama instance.
+
+##### API handles prompt template
+
+If enabled, Talemate will send the raw prompt and let Ollama apply its own built-in prompt template. If you are unsure leave this disabled – Talemate's own prompt template generally produces better results.
+
+##### Allow thinking
+
+If enabled Talemate will allow models that support "thinking" (`assistant:thinking` messages) to deliberate before forming the final answer. At the moment Talemate has limited support for this feature when talemate is handling the prompt template. Its probably ok to turn it on if you let Ollama handle the prompt template.
+
+!!! tip
+    You can quickly refresh the list of models by making sure the Ollama server is running and then hitting **Save** again in the client settings. 
+
+### Common issues
+
+#### Generations are weird / bad
+
+If letting talemate handle the prompt template, make sure the [correct prompt template is assigned](/talemate/user-guide/clients/prompt-templates/).
+
--- a/docs/user-guide/clients/types/openrouter.md
+++ b/docs/user-guide/clients/types/openrouter.md
@@ -0,0 +1,48 @@
+# OpenRouter Client
+
+If you want to add an OpenRouter client, change the `Client Type` to `OpenRouter`.
+
+![Client OpenRouter](/talemate/img/0.31.0/client-openrouter.png)
+
+Click `Save` to add the client.
+
+### OpenRouter API Key
+
+The client should appear in the clients list. If you haven't set up OpenRouter before, you will see a warning that the API key is missing.
+
+![Client openrouter no api key](/talemate/img/0.31.0/client-openrouter-no-api-key.png)
+
+Click the `SET API KEY` button. This will open the API settings window where you can add your OpenRouter API key.
+
+For additional instructions on obtaining and setting your OpenRouter API key, see [OpenRouter API instructions](/talemate/user-guide/apis/openrouter/).
+
+![OpenRouter settings](/talemate/img/0.31.0/openrouter-settings.png)
+
+Click `Save` and after a moment the client should have a red dot next to it, saying that there is no model loaded.
+
+Click the :material-cogs: icon to open the client settings and select a model.
+
+![OpenRouter select model](/talemate/img/0.31.0/client-openrouter-select-model.png).
+
+Click save and the client should have a green dot next to it, indicating that it is ready to go.
+
+### Ready to use
+
+![Client OpenRouter Ready](/talemate/img/0.31.0/client-openrouter-ready.png)
+
+### Settings
+
+##### Client Name
+
+A unique name for the client that makes sense to you.
+
+##### Model
+
+Choose any model available via your OpenRouter account. Talemate dynamically fetches the list of models associated with your API key so new models will show up automatically.
+
+##### Max token length
+
+Maximum context length (in tokens) that OpenRouter should consider. If you are not sure leave the default value.
+
+!!! note "Available models are fetched automatically"
+    Talemate fetches the list of available OpenRouter models when you save the configuration (if a valid API key is present). If you add or remove models to your account later, simply click **Save** in the application settings again to refresh the list. 
--- a/Show More
+++ b/Show More