0.40.0 (#279)
Some checks failed
ci / container-build (push) Has been cancelled
ci / deploy-docs (push) Has been cancelled
Python Tests / test (3.11) (push) Has been cancelled
Frontend Tests / test (push) Has been cancelled

- **Scene Revisions** — Revision history with one row per message, date filter and text search; fork a new save from any past revision. Replaces the Timeline, which never worked reliably.
- **Character Knowledge** — Characters only remember passages they witnessed and information shared with them. Known by, Learn and Never Learn controls, also available to the Director.
- **Character Perspectives** — Optional mode that keeps each character's own account of events and uses it for their memories and summaries. Accounts can be read and edited beside the full story. Needs a strong model and adds analysis requests.
- **Decision Model** — Optional small model (OpenRouter or a SystemOne-compatible server) that answers yes/no questions with a probability: pin conditions, skipping unchanged tracked states, portrait and background picks, Editor checks. Includes a Decision Log.
- **Themes** — Light and dark themes, custom themes (colors, message styling, editor appearance) with a live preview
- **Replay** — Step through a story one passage at a time with optional narration, auto-advance and chapter navigation; fork from any passage.
- **Scene Controls** — Configurable scene header, reusable scene tool shortcuts, and game variables pinned as sliders, choices or toggles.
- **Scene Backgrounds** — The World State agent can pick or generate a scene backdrop that fits the story; backdrop changes are recorded in the history. Off by default.
- **Help Chat** — The Help agent can create and change themes and templates, adjust settings and edit inference presets, each behind a permission that is off by default.
- **Chatterbox Turbo** — New optional voice backend with voice cloning and sound tags.

Plus 35 improvements and 35 bug fixes — see [CHANGELOG.md](https://github.com/vegu-ai/talemate/blob/prep-0.40.0/CHANGELOG.md#0400) for the full list.
This commit is contained in:
veguAI 2026-10-27 10:32:55 +02:00
parent cc28def7c6
commit 7db12b042b
1955 changed files with 256177 additions and 23764 deletions

42
.github/workflows/frontend-test.yml vendored Normal file
View file

@ -0,0 +1,42 @@
name: Frontend Tests
on:
push:
branches: [ main, 'prep-*' ]
pull_request:
branches: [ main, 'prep-*' ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# before setup-node, so it can query pnpm for the cache directory. The
# frontend steps run beside package.json, where Corepack enforces its pin.
- name: Enable corepack
run: corepack enable
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '24'
cache: 'pnpm'
cache-dependency-path: talemate_frontend/pnpm-lock.yaml
- name: Verify pnpm version
working-directory: talemate_frontend
run: test "$(pnpm --version)" = "12.4.1"
- name: Install dependencies
working-directory: talemate_frontend
run: pnpm install --frozen-lockfile
- name: Run lint
working-directory: talemate_frontend
run: pnpm lint
- name: Run tests
working-directory: talemate_frontend
run: pnpm test

50
.github/workflows/portable-pnpm.yml vendored Normal file
View file

@ -0,0 +1,50 @@
name: Portable pnpm
on:
pull_request:
branches: [ main, 'prep-*' ]
paths:
- 'install-utils/**'
- '*.bat'
- '*.sh'
- 'talemate_frontend/package.json'
- 'talemate_frontend/pnpm-lock.yaml'
- '.github/workflows/portable-pnpm.yml'
jobs:
frontend:
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
env:
COREPACK_ENABLE_NETWORK: '0'
steps:
- uses: actions/checkout@v4
- name: Download portable Node on Windows
if: runner.os == 'Windows'
shell: pwsh
run: |
$version = (Select-String -Path install.bat -Pattern 'SET "NODE_VERSION=(.+)"').Matches.Groups[1].Value
$archive = "node-v$version-win-x64"
Invoke-WebRequest "https://nodejs.org/dist/v$version/$archive.zip" -OutFile node.zip
Expand-Archive node.zip -DestinationPath node-unpacked
Move-Item "node-unpacked/$archive" embedded_node
"$pwd\embedded_node" >> $env:GITHUB_PATH
- name: Download portable Node on Linux
if: runner.os == 'Linux'
shell: bash
run: |
source install-utils/node-env.sh
install_embedded_node
echo "$PWD/embedded_node/bin" >> "$GITHUB_PATH"
- name: Provision and verify local pnpm
shell: bash
run: |
node -v
node install-utils/pnpm.cjs --version
node install-utils/pnpm.cjs --version
- name: Install frontend dependencies
run: node install-utils/pnpm.cjs install --frozen-lockfile
- name: Build frontend
run: node install-utils/pnpm.cjs build

View file

@ -38,25 +38,16 @@ jobs:
- name: Install dependencies
run: |
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
uv sync --extra dev --locked
- name: Run linting
run: |
source .venv/bin/activate
uv run pre-commit run --all-files
- 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')"
uv run python -c "import nltk; nltk.download('punkt_tab')"
- name: Run tests
run: |
source .venv/bin/activate
pytest tests/ -p no:warnings
uv run pytest tests/ -p no:warnings

5
.gitignore vendored
View file

@ -28,6 +28,7 @@ tts/voice/piper/*.json
tts/voice/kokoro/*.pt
tts/voice/xtts2/*.wav
tts/voice/chatterbox/*.wav
tts/voice/chatterbox_turbo/*.wav
tts/voice/f5tts/*.wav
tts/voice/voice-library.json
scenes/
@ -43,3 +44,7 @@ legacy-state-reinforcements.yaml
CLAUDE.md
docs/update-progress
talemate_frontend/eslint.config.cjs
/data.db
/data.db-wal
/data.db-shm

View file

@ -2,6 +2,231 @@
_Auto-generated. Do not edit by hand._
## 0.40.0
### Upgrade Notes
#### Scene Revisions (breaking change)
Upgrading from 0.39.0 starts revisions from a current save when you first load or save it, in `<project>/data.db`. The new system ignores `<project>/changelog/` and leaves it untouched; you can delete that old directory by hand. Earlier revisions are not converted.
#### OpenAI Clients
Review saved OpenAI settings after upgrading. GPT-5 and GPT-6 models keep Reasoning on; enable it for o-series models if needed. Sampling controls start off. For o1-mini or o1-preview, turn Send System Message off; turn Stream off if unavailable, and choose max_tokens for servers requiring it. Save your settings.
#### OpenRouter Reasoning
The client no longer sends a reasoning budget. With Reasoning on it sends your Reasoning Effort, or asks the model to think at its own default effort; with Reasoning off it sends nothing, and models that always think use their provider's default. A saved Reasoning Tokens number from 0.39.0 no longer controls how much the model thinks: it now means Extra Completion Tokens. If you used it to control thinking, choose a Reasoning Effort instead.
#### Compatible Voice Servers
OpenAI-compatible voice backends now request MP3 by default. Select WAV under Response format if your server cannot produce MP3.
#### Shared Worlds
Back up older shared worlds before upgrading. Missing shared entries can be recovered from a linked scene only until 0.40 first writes that world, so load the scene holding them first. Entries intentionally removed in an older version may also return. Recover overwritten text from older revisions in 0.39.0 before upgrading, or from a backup of `<project>/changelog/`.
#### Scene Context Format
The scene context format (Screenplay, Chat, Narrative, AI Aware) moved from the Conversation agent's Generation settings to the Summarizer agent's Scene History settings. A format set on the Conversation agent in an earlier version is not carried over: the format starts at Screenplay, so set it again in Scene History if you used another one.
#### Scene Backgrounds
Auto Backdrop for scene backgrounds is removed: backgrounds generated for the story always become the backdrop, and Visual Library backgrounds only go to the library. Backgrounds already attached to messages keep showing.
#### Visual Styles
Shipped visual styles moved into Talemate's template group. Back up edits to templates/world-state/visual-styles.yaml before updating; if they block the update, stash them or restore the tracked file.
### Scene Revisions
Browse a story's saved states with one row per message, filter them by date or search their text, and fork a new save from any past revision. The new save keeps the inherited revisions and the fork point. Revisions replace the Timeline, which was meant to do the same but never worked reliably.
### Character Knowledge
Characters can remember only the passages they witnessed and the information shared with them. Known by, Learn and Never Learn controls let you shape their knowledge, including through the Director. Standard mode adds no requests at its default effort; older scenes keep their existing history behavior.
### Character Perspectives
New stories can give each character their own account of events, carried into their memories and summaries. Read and edit those accounts beside the full story, and share selected information as disclosures. This optional mode needs a strong model and adds analysis requests; choose it before the story has history. An edit marks the views and summaries it affects as out of sync, and Repair rebuilds them. Views keep the passage's tense and style, and a character who sees a whisper but cannot hear it keeps the visible exchange without its words. Analyze player perspective is off by default; enable it in Settings → Agents → Summarizer → Character Perspectives to limit the player's view independently of effort.
### Decision Model
An optional decision model answers quick questions about your story with a probability instead of prose, through OpenRouter or a SystemOne-compatible server. It can answer pin conditions and queries, skip unchanged tracked states, choose existing portraits and scene backgrounds, recognize characters named by pronoun or nickname, and run the Editor decision checks. Each question sends only the part of the story it needs, so local servers stay quick. A Decision Log shows every answer and its token count, and nothing is sent while the model is off.
### Themes
Choose a light or dark theme, or create and share your own colors, message styling and editor appearance. A live preview lets you edit colors where they appear, while personal color overrides survive theme changes.
### Replay
Replay a story one passage at a time with optional narration, automatic advance and chapter navigation. Resume where you left off, or fork at the current passage to take the story in a new direction.
### Scene Controls
Customize the scene header with story statistics, character portraits, knowledge mode and effort, and quick access to the scene's writing and visual styles. Add reusable shortcuts to scene tools and pin game variables as labelled sliders, choices or toggles for use during play.
### Scene Backgrounds
The World State agent can keep the scene backdrop fitting the story, picking one of the scene's backgrounds or generating a new one. Every backdrop change, including backgrounds you generate for the story, is recorded as a Backdrop entry in the history, and Replay shows each passage with its backdrop. It is off by default.
### Help Chat
Ask the Help agent to create or change themes and templates, adjust settings and edit inference presets. Settings and template changes each require your permission, with both permissions off by default. The theme editor can start a help chat that sets up a theme from your description.
### Chatterbox Turbo
Chatterbox Turbo adds an optional voice backend with voice cloning and expressive sound tags.
### Improvements
**Scene Revisions**
- Forks keep their shared world connection at its current state; shared worlds are not rewound with a revision.
**Story and World**
- Add a selected person, object or place from the story to the world snapshot and keep it tracked.
- Character arrivals and departures appear in history, with arrival notes and optional narration when moving characters into or out of the scene.
- Prose perspective presets include examples, and the Director can help choose perspectives or reassess the scene's intent.
- Finished passages appear while follow-up summaries and voice preparation continue.
- The story keeps its place when you switch to another tab and back.
- Sequential tracked-state answers appear in the story as State Update rows you can read, edit or remove.
- The World Editor's Game State view follows changes made by the Director, nodes or the decision model, without overwriting your unsaved edits.
- Editing or deleting earlier passages warns when later story details may become inconsistent.
**Memory**
- Tune retrieval for recency, variety and relevance, with optional local reranking or AI refinement; OpenRouter embeddings are also available.
- With Refine memories with AI on, a Memories button on character replies shows the memories the character drew on.
**Director**
- Reject a proposed action with instructions for a correction, and see which actions in a batch were applied.
**Settings and Clients**
- Client and agent settings share the Settings tab's Save and Discard controls, including scene overrides and assigning one client to all agents.
- The Settings toolbar stays pinned while a long page scrolls.
- Pin inference parameters beside the client list and enter exact sampling, context and reasoning values.
- OpenAI, OpenRouter and compatible clients offer reasoning effort and completion-token options; OpenAI adds sampling and system-message controls, and OpenAI and compatible clients can stream.
- llama.cpp Router mode lets each client choose its model, including for vision and server prompt templates.
- New clients default to at least 16k context; supported hosted clients enable concurrent requests by default, while saved configurations retain their values.
- New OpenAI-compatible clients send stop sequences and thinking preferences, each with its own toggle; saved clients keep their current requests.
- The MistralAI client offers Reasoning Effort for the models that accept it, and new clients default to mistral-large-4.
- Muse Glimmer prompt formatting and newer Hugging Face template files are supported.
**Editor and Writing Styles**
- Optional Editor decision checks find repeated beats, reused descriptions and unwanted prose, then correct them in one Targeted Rewrite or Unslop call.
- Writing styles define the checks, their questions and thresholds; Add default checks covers common cases, and each check can judge all text, only dialogue or only prose.
- Writing styles include a new Polished Prose style, used by Infinity Quest and Simulation Suite, and a rewritten Adventure Game style with a mid-90s point-and-click voice.
- The World Editor's writing style menu can open the selected style in the Templates tab.
**Images**
- OpenRouter supports image-only generation and editing models, with model and provider suggestions and clearer errors for unsupported requests.
- Paste images from the clipboard, choose megapixel resolution presets, and use the Qwen image-reference prompt preset.
- Mark as reference prepares any image for later generations, analyzing and tagging it when a vision backend is available.
- Regenerate (replace) and Edit (replace) put the new image in the original's place, deleting the original only when nothing else uses it.
- The Visualizer scene tool switches automatic generation, new portraits and new backgrounds on and off.
**Voice**
- Volume and mute survive reloads; OpenAI-compatible voice backends offer audio-format selection and refresh complete voice lists without overwriting personal edits.
**Prompt Tools**
- Follow active, completed, failed and cancelled requests in the prompt viewers, with clearer action names.
- Prompt Manager flags template overrides that are incomplete or incompatible with the current default, compares them with it, and resets them to default.
- Prompts → Scene Context has its view controls in a toolbar, and the scene context format now lives in the Summarizer's Scene History settings, with global or scene override markers.
**Node Editor**
- Rewrite spoken text without changing the story, and use newline and tab escapes in String Join and Split delimiters.
- Added or edited command and agent modules become available automatically without a manual sync.
- New nodes and events cover the decision model, character knowledge and disclosures, game state, arrivals and departures, the world snapshot, reasoning effort per request and preparing images as references.
**Interface**
- Updated typography, controls and layouts follow Material Design 3.
**Bundled Stories**
- The original Simulation Suite is now hidden from new scene creation to steer new stories to Simulation Suite V2; existing saves stay available. Infinity Quest has a more concrete backstory.
### Bug Fixes
**Saves and History**
- Save As protects read-only destinations, keeps errors open for correction, and preserves pending scene-settings edits when saving is cancelled.
- Unsaved changes trigger a warning before leaving; read-only stories keep their save identity and correctly mark changes autosave cannot write.
- Revision forks preserve all recorded scene sections, including world state. A damaged snapshot reports an error without substituting another state.
- Failed revision-history writes stop the save with an error instead of leaving a save with incomplete history.
- Static history and shared entries keep their timing across reloads and time changes; deleting messages preserves summary positions.
- Shared world entries survive linked-scene loads and new episodes.
- Sequential tracked-state answers accumulate over the story without duplicates after a reload, and re-applying a template keeps a tracked state and its answer.
- Without Character Perspectives, saving or clearing a World tracked state's answer in the World Editor updates what the AI recalls.
- Pinned context survives loading a scene file from someone else, moving to a new installation, or clearing the local memory cache.
**Characters and World**
- Duplicate character names are refused, failed creation leaves no partial character, and valid character proposals apply without discarding other pending changes.
- Regenerating a snapshot's source restores an earlier snapshot or clears it with a notice; introductions and emphasized text show world highlights.
- Editing memories refreshes remembered context, and character replies avoid repeating passages already in their story context.
- New world entries and tracked states are saved only when you click Create, and Add pin works on the first click.
- Text completed with Ctrl+Enter in character and scene fields is saved when you leave the field.
- Make Player Character is unavailable while an agent is generating, so an unfinished character line cannot count as your turn.
- A new story's World Editor no longer starts with the previous story's writing style, and its templates links open the Templates tab.
**Story and Scenes**
- Director messages stay visible until you confirm their deletion, and story messages fill the scene width in Immersive mode.
- Simulation Suite V2 titles new simulations properly, follows requests a Director action writes, and treats only lines starting with the word Computer as requests.
**Director and Help**
- Director requests can update several fields, empty action results explain the outcome, and result summaries display proper line breaks.
- Cancelled actions stop the remaining calls, and failed settings application can be retried with Save.
- Director Chat no longer shows the director's reply twice after an action whose follow-up repeats it.
- Scene-category templates created in the prompt editor appear in Scene Direction's instruction template list.
**Editor**
- A running revision no longer applies stale results after the scene, message text or selected version changes.
**Settings and Clients**
- Agent quick-toggle chips and scene overrides no longer undo a change made moments earlier elsewhere, and overrides waiting for a save show Save and Discard.
- OpenRouter respects disabled reasoning and per-action overrides; OpenAI-compatible clients handle empty replies and report non-streamed generation speed correctly.
- Local clients refuse blank server URLs, unavailable clients remain visible, and Ollama honors stopping strings.
- Compatible clients in chat mode read separately returned reasoning, work without an API key, and name the real cause of a failed generation.
- Qwen3 and Qwen3.5 models get a matching prompt template automatically, so turning Reasoning off keeps their thinking out of the story.
- KoboldCpp, Text-Generation-WebUI, TabbyAPI and OpenAI-compatible servers receive all sampler and stop settings, honor Reasoning off and no longer cut responses short.
- MistralAI streaming works with reasoning models.
**Images**
- Image uploads work over plain HTTP, OpenRouter images are stored as PNG, and ComfyUI prompt inputs and workflow lists resolve correctly.
- Automatic image generations follow the Visualizer's Automatic Generation setting, and regenerating or editing an image updates the message you clicked.
- Deleting an image removes it from other images' references; generations no longer fail on it, and Director Chat shows it as removed.
- Visualizer settings list new ComfyUI workflows, vision clients and OpenRouter models when opened, without saving first.
**Voice and Startup**
- Failed voice chunks no longer stop the playback queue, and compatible servers can return playable audio and complete voice listings.
- Ctrl+C handles cancelled image-backend probes quietly and bounds shutdown to five seconds when background work stalls.
- Windows installation and frontend startup are repaired; fresh source installs start without configuration, and installed tokenizers need no startup download.
**Node Editor**
- Time nodes have valid defaults, inactive characters have no actor output, and test runs stop when switching scenes.
- Request World State outputs the world snapshot after its update.
**Security**
- Generated HTML is displayed safely across story messages, chats and previews.
## 0.39.0
### Help Agent
@ -155,6 +380,7 @@ Reusable action sets are managed as a new Visual prompt finalizer template type,
- Exporting a scene with Reset Progress checked no longer wipes the loaded scene's message history and world state — the reset applies only to the exported file.
- Deleting the save file of the currently loaded scene is refused with an error instead of being recreated by the next save.
- Applying a scene type template now actually registers the scene type on the scene, so the picked type is no longer lost.
- Forking from a message refuses a save name that is not a valid filename or that an existing save already uses, instead of writing over that save.
**Timeline**

View file

@ -1,3 +1,126 @@
0.40.0:
features:
- "Scene Revisions: Browse a story's saved states with one row per message, filter them by date or search their text, and fork a new save from any past revision. The new save keeps the inherited revisions and the fork point. Revisions replace the Timeline, which was meant to do the same but never worked reliably."
- "Character Knowledge: Characters can remember only the passages they witnessed and the information shared with them. Known by, Learn and Never Learn controls let you shape their knowledge, including through the Director. Standard mode adds no requests at its default effort; older scenes keep their existing history behavior."
- "Character Perspectives: New stories can give each character their own account of events, carried into their memories and summaries. Read and edit those accounts beside the full story, and share selected information as disclosures. This optional mode needs a strong model and adds analysis requests; choose it before the story has history. An edit marks the views and summaries it affects as out of sync, and Repair rebuilds them. Views keep the passage's tense and style, and a character who sees a whisper but cannot hear it keeps the visible exchange without its words. Analyze player perspective is off by default; enable it in Settings → Agents → Summarizer → Character Perspectives to limit the player's view independently of effort."
- "Decision Model: An optional decision model answers quick questions about your story with a probability instead of prose, through OpenRouter or a SystemOne-compatible server. It can answer pin conditions and queries, skip unchanged tracked states, choose existing portraits and scene backgrounds, recognize characters named by pronoun or nickname, and run the Editor decision checks. Each question sends only the part of the story it needs, so local servers stay quick. A Decision Log shows every answer and its token count, and nothing is sent while the model is off."
- "Themes: Choose a light or dark theme, or create and share your own colors, message styling and editor appearance. A live preview lets you edit colors where they appear, while personal color overrides survive theme changes."
- "Replay: Replay a story one passage at a time with optional narration, automatic advance and chapter navigation. Resume where you left off, or fork at the current passage to take the story in a new direction."
- "Scene Controls: Customize the scene header with story statistics, character portraits, knowledge mode and effort, and quick access to the scene's writing and visual styles. Add reusable shortcuts to scene tools and pin game variables as labelled sliders, choices or toggles for use during play."
- "Scene Backgrounds: The World State agent can keep the scene backdrop fitting the story, picking one of the scene's backgrounds or generating a new one. Every backdrop change, including backgrounds you generate for the story, is recorded as a Backdrop entry in the history, and Replay shows each passage with its backdrop. It is off by default."
- "Help Chat: Ask the Help agent to create or change themes and templates, adjust settings and edit inference presets. Settings and template changes each require your permission, with both permissions off by default. The theme editor can start a help chat that sets up a theme from your description."
- "Voice: Chatterbox Turbo adds an optional voice backend with voice cloning and expressive sound and style tags."
improvements:
- "Scene Revisions: Forks keep their shared world connection at its current state; shared worlds are not rewound with a revision."
- "Story and World: Add a selected person, object or place from the story to the world snapshot and keep it tracked."
- "Story and World: Character arrivals and departures appear in history, with arrival notes and optional narration when moving characters into or out of the scene."
- "Story and World: Prose perspective presets include examples, and the Director can help choose perspectives or reassess the scene's intent."
- "Story and World: Finished passages appear while follow-up summaries and voice preparation continue."
- "Story and World: The story keeps its place when you switch to another tab and back."
- "Story and World: Sequential tracked-state answers appear in the story as State Update rows you can read, edit or remove."
- "Story and World: The World Editor's Game State view follows changes made by the Director, nodes or the decision model, without overwriting your unsaved edits."
- "Story and World: Editing or deleting earlier passages warns when later story details may become inconsistent."
- "Memory: Tune retrieval for recency, variety and relevance, with optional local reranking or AI refinement; OpenRouter embeddings are also available."
- "Memory: With Refine memories with AI on, a Memories button on character replies shows the memories the character drew on."
- "Director: Reject a proposed action with instructions for a correction, and see which actions in a batch were applied."
- "Settings and Clients: Client and agent settings share the Settings tab's Save and Discard controls, including scene overrides and assigning one client to all agents."
- "Settings and Clients: The Settings toolbar stays pinned while a long page scrolls."
- "Settings and Clients: Pin inference parameters beside the client list and enter exact sampling, context and reasoning values."
- "Settings and Clients: OpenAI, OpenRouter and compatible clients offer reasoning effort and completion-token options; OpenAI adds sampling and system-message controls, and OpenAI and compatible clients can stream."
- "Settings and Clients: llama.cpp Router mode lets each client choose its model, including for vision and server prompt templates; the client list marks a router client with an icon beside its name."
- "Settings and Clients: llama.cpp clients can leave individual sampler parameters out of the request, so the server's own value or a router model preset applies; XTC, DRY, adaptive sampling and the repetition penalty each have one toggle."
- "Settings and Clients: The OpenAI Compatible client has an Enable Vision option, so a vision model behind a compatible server can analyze images."
- "Settings and Clients: New clients default to at least 16k context; supported hosted clients enable concurrent requests by default, while saved configurations retain their values."
- "Settings and Clients: New OpenAI-compatible clients send stop sequences and thinking preferences, each with its own toggle; saved clients keep their current requests."
- "Settings and Clients: The MistralAI client offers Reasoning Effort for the models that accept it, and new clients default to mistral-large-4."
- "Settings and Clients: Muse Glimmer prompt formatting and newer Hugging Face template files are supported."
- "Editor and Writing Styles: Optional Editor decision checks find repeated beats, reused descriptions and unwanted prose, then correct them in one Targeted Rewrite or Unslop call."
- "Editor and Writing Styles: Writing styles define the checks, their questions and thresholds; Add default checks covers common cases, and each check can judge all text, only dialogue or only prose."
- "Editor and Writing Styles: Writing styles include a new Polished Prose style, used by Infinity Quest and Simulation Suite, and a rewritten Adventure Game style with a mid-90s point-and-click voice."
- "Editor and Writing Styles: The World Editor's writing style menu can open the selected style in the Templates tab."
- "Images: OpenRouter supports image-only generation and editing models, with model and provider suggestions and clearer errors for unsupported requests."
- "Images: Paste images from the clipboard, choose megapixel resolution presets, and use the Qwen image-reference prompt preset."
- "Images: Mark as reference prepares any image for later generations, analyzing and tagging it when a vision backend is available."
- "Images: Regenerate (replace) and Edit (replace) put the new image in the original's place, deleting the original only when nothing else uses it."
- "Images: The Visualizer scene tool switches automatic generation, new portraits and new backgrounds on and off."
- "Voice: Volume and mute survive reloads; OpenAI-compatible voice backends offer audio-format selection and refresh complete voice lists without overwriting personal edits."
- "Prompt Tools: Follow active, completed, failed and cancelled requests in the prompt viewers, with clearer action names."
- "Prompt Tools: Prompt Manager flags template overrides that are incomplete or incompatible with the current default, compares them with it, and resets them to default."
- "Prompt Tools: Prompts → Scene Context has its view controls in a toolbar, and the scene context format now lives in the Summarizer's Scene History settings, with global or scene override markers."
- "Node Editor: Rewrite spoken text without changing the story, and use newline and tab escapes in String Join and Split delimiters."
- "Node Editor: Added or edited command and agent modules become available automatically without a manual sync."
- "Node Editor: New nodes and events cover the decision model, character knowledge and disclosures, game state, arrivals and departures, the world snapshot, reasoning effort per request and preparing images as references."
- "Interface: Updated typography, controls and layouts follow Material Design 3."
- "Bundled Stories: The original Simulation Suite is now hidden from new scene creation to steer new stories to Simulation Suite V2; existing saves stay available. Infinity Quest has a more concrete backstory."
- "Clients: New llama.cpp and OpenAI Compatible clients start with API handles prompt template on. Clients you saved earlier keep the value they have saved; turn the checkbox off to control the prompt template yourself."
- "Clients: The llama.cpp client chooses Reasoning Mode, an effort level (the default) or a token budget. With API handles prompt template on, the effort is sent as reasoning_effort and the budget as reasoning_budget_tokens; with it off neither is sent, so Reasoning Tokens only adds room to the response limit. The client card shows the effort dropdown when the effort is sent, and the token field otherwise; choose tokens to get the token field back."
- "Clients: The Gemma 4 prompt template follows Google's official chat template more closely, including where the answer starts after the empty thinking block when reasoning is off."
- "Anthropic Client: Added Claude Haiku 5.5, Sonnet 5 and 5.5, Opus 5 and 5.5, Fable 5 and 5.1, and Opus 4.8, with adaptive thinking. Opus 5.5 and Fable 5 cannot turn thinking off, so their Reasoning setting stays on. Models that refuse a pre-filled response (these, Opus 4.6 and 4.7, and Sonnet 4.6) now receive the start of the response as an instruction in the prompt instead of failing with HTTP 400."
- "Creator: Fast Character Generation is on by default, so new characters are generated with one consolidated prompt. Turn it off in the Creator's Character Creation settings for older or smaller models. Installs that saved agent settings in an earlier version keep their previous value; any quick toggle or Assign to all agents counts as a save."
- "Editor: Revision is on by default and Automatic revision is off, so the Revise chip is available on the latest message and nothing is revised, and no extra request is sent, until you use it or switch Automatic revision on. Installs that saved agent settings in an earlier version keep their previous values; any quick toggle or Assign to all agents counts as a save."
- "Memory: Long term memory retrieval defaults to 5 queries instead of 3 when AI-assisted retrieval is used. The default direct retrieval is unchanged and sends no extra requests. Installs that saved agent settings in an earlier version keep their previous value; any quick toggle or Assign to all agents counts as a save."
- "Visualizer: Prompts default to the Descriptive type instead of Keywords for ComfyUI, SD.Next, the Visual Prompt node and prompt-only generation. AUTOMATIC1111 keeps Keywords. Installs that saved agent settings in an earlier version keep their previous value; any quick toggle or Assign to all agents counts as a save."
fixes:
- "Clients: The bundled Gemma 4, Llama 3 and Command R prompt templates no longer start with their own beginning-of-text token. The backend adds it as the model file asks, so text completions no longer begin with it twice. This includes Llama 3 models that use the template Talemate picks automatically. A model already set to one of these templates keeps its old copy; choose the template again in the client's prompt template picker to update it."
- "Clients: The prompt template preview shows the request as the client sends it: with reasoning on, the coercion appears as an instruction to the model instead of a pre-filled answer, and the Coercion and Reason Prefill settings appear where they are sent."
- "Anthropic Client: Claude Opus 4.6 no longer offers the xhigh effort level, which it refuses with an error; a saved xhigh is sent as high."
- "Saves and History: Save As protects read-only destinations, keeps errors open for correction, and preserves pending scene-settings edits when saving is cancelled."
- "Saves and History: Unsaved changes trigger a warning before leaving; read-only stories keep their save identity and correctly mark changes autosave cannot write."
- "Saves and History: Revision forks preserve all recorded scene sections, including world state. A damaged snapshot reports an error without substituting another state."
- "Saves and History: Failed revision-history writes stop the save with an error instead of leaving a save with incomplete history."
- "Saves and History: Static history and shared entries keep their timing across reloads and time changes; deleting messages preserves summary positions."
- "Saves and History: Shared world entries survive linked-scene loads and new episodes."
- "Saves and History: Sequential tracked-state answers accumulate over the story without duplicates after a reload, and re-applying a template keeps a tracked state and its answer."
- "Saves and History: Without Character Perspectives, saving or clearing a World tracked state's answer in the World Editor updates what the AI recalls."
- "Saves and History: Pinned context survives loading a scene file from someone else, moving to a new installation, or clearing the local memory cache."
- "Characters and World: Duplicate character names are refused, failed creation leaves no partial character, and valid character proposals apply without discarding other pending changes."
- "Characters and World: Regenerating a snapshot's source restores an earlier snapshot or clears it with a notice; introductions and emphasized text show world highlights."
- "Characters and World: Editing memories refreshes remembered context, and character replies avoid repeating passages already in their story context."
- "Characters and World: New world entries and tracked states are saved only when you click Create, and Add pin works on the first click."
- "Characters and World: Text completed with Ctrl+Enter in character and scene fields is saved when you leave the field."
- "Characters and World: Make Player Character is unavailable while an agent is generating, so an unfinished character line cannot count as your turn."
- "Characters and World: A new story's World Editor no longer starts with the previous story's writing style, and its templates links open the Templates tab."
- "Story and Scenes: Director messages stay visible until you confirm their deletion, and story messages fill the scene width in Immersive mode."
- "Story and Scenes: Simulation Suite V2 titles new simulations properly, follows requests a Director action writes, and treats only lines starting with the word Computer as requests."
- "Director and Help: Director requests can update several fields, empty action results explain the outcome, and result summaries display proper line breaks."
- "Director and Help: Cancelled actions stop the remaining calls, and failed settings application can be retried with Save."
- "Director and Help: Director Chat no longer shows the director's reply twice after an action whose follow-up repeats it."
- "Director and Help: Scene-category templates created in the prompt editor appear in Scene Direction's instruction template list."
- "Editor: A running revision no longer applies stale results after the scene, message text or selected version changes."
- "Settings and Clients: Agent quick-toggle chips and scene overrides no longer undo a change made moments earlier elsewhere, and overrides waiting for a save show Save and Discard."
- "Settings and Clients: OpenRouter respects disabled reasoning and per-action overrides; OpenAI-compatible clients handle empty replies and report non-streamed generation speed correctly."
- "Settings and Clients: Local clients refuse blank server URLs, unavailable clients remain visible, and Ollama honors stopping strings."
- "Settings and Clients: Compatible clients in chat mode read separately returned reasoning, work without an API key, and name the real cause of a failed generation."
- "Settings and Clients: Qwen3 and Qwen3.5 models get a matching prompt template automatically, so turning Reasoning off keeps their thinking out of the story."
- "Settings and Clients: KoboldCpp, Text-Generation-WebUI, TabbyAPI and OpenAI-compatible servers receive all sampler and stop settings, honor Reasoning off and no longer cut responses short."
- "Settings and Clients: MistralAI streaming works with reasoning models."
- "Images: Image uploads work over plain HTTP, OpenRouter images are stored as PNG, and ComfyUI prompt inputs and workflow lists resolve correctly."
- "Images: Automatic image generations follow the Visualizer's Automatic Generation setting, and regenerating or editing an image updates the message you clicked."
- "Images: Deleting an image removes it from other images' references; generations no longer fail on it, and Director Chat shows it as removed."
- "Images: Visualizer settings list new ComfyUI workflows, vision clients and OpenRouter models when opened, without saving first."
- "Voice and Startup: Failed voice chunks no longer stop the playback queue, and compatible servers can return playable audio and complete voice listings."
- "Voice and Startup: Ctrl+C handles cancelled image-backend probes quietly and bounds shutdown to five seconds when background work stalls."
- "Voice and Startup: Windows installation and frontend startup are repaired; fresh source installs start without configuration, and installed tokenizers need no startup download."
- "Voice: With Audio tags on, voices no longer read the speaker's name aloud. If the AI changes a line's words while adding tags, the line is spoken as written, without tags."
- "Node Editor: Time nodes have valid defaults, inactive characters have no actor output, and test runs stop when switching scenes."
- "Node Editor: Request World State outputs the world snapshot after its update."
- "Security: Generated HTML is displayed safely across story messages, chats and previews."
- "Security: Updated Pillow to 13.0.0, which fixes decoder advisories that a crafted character card, uploaded image or generated image could trigger, including a card that crashed or hung the backend while it was read."
- "Security: Updated certifi to 2026.10.19, which stops trusting the emSign ECC Root CA - G3 certificate authority, whose intermediate certificate keys were compromised, for HTTPS requests to services such as Google, Cohere, Groq, Mistral, ElevenLabs and Hugging Face."
- "Security: Updated vite, which fixes advisories in the development server that start-frontend.sh / start-frontend.bat and the manual Linux install run."
- "Clients: The llama.cpp and OpenAI Compatible clients name the request that returned 404 and explain what to change when the server only offers chat completions."
- "Clients: With API handles prompt template on, the llama.cpp client sends requests to the server's chat endpoint, so Reasoning is kept apart from the answer and only the answer reaches the story."
- "Clients: The Prompt Template picker in the client editor appears and disappears as soon as you change API handles prompt template, without saving first."
- "Visualizer: Image backends set to the Keywords prompting type get the generated keywords when the image is made from references, instead of an empty prompt. The *Perform extra revision of editing prompts* request and the automatic reference analysis only apply to Descriptive prompts, so they are skipped for Keywords, and both are skipped when no usable reference image is attached. AUTOMATIC1111 applies a changed Prompting Type without a restart."
migrations:
- "Scene Revisions (breaking change): Upgrading from 0.39.0 starts revisions from a current save when you first load or save it, in `<project>/data.db`. The new system ignores `<project>/changelog/` and leaves it untouched; you can delete that old directory by hand. Earlier revisions are not converted."
- "OpenAI Clients: Review saved OpenAI settings after upgrading. GPT-5 and GPT-6 models keep Reasoning on; enable it for o-series models if needed. Sampling controls start off. For o1-mini or o1-preview, turn Send System Message off; turn Stream off if unavailable, and choose max_tokens for servers requiring it. Save your settings."
- "OpenRouter Reasoning: The client no longer sends a reasoning budget. With Reasoning on it sends your Reasoning Effort, or asks the model to think at its own default effort; with Reasoning off it sends nothing, and models that always think use their provider's default. A saved Reasoning Tokens number from 0.39.0 no longer controls how much the model thinks: it now means Extra Completion Tokens. If you used it to control thinking, choose a Reasoning Effort instead."
- "Compatible Voice Servers: OpenAI-compatible voice backends now request MP3 by default. Select WAV under Response format if your server cannot produce MP3."
- "Shared Worlds: Back up older shared worlds before upgrading. Missing shared entries can be recovered from a linked scene only until 0.40 first writes that world, so load the scene holding them first. Entries intentionally removed in an older version may also return. Recover overwritten text from older revisions in 0.39.0 before upgrading, or from a backup of `<project>/changelog/`."
- "Scene Context Format: The scene context format (Screenplay, Chat, Narrative, AI Aware) moved from the Conversation agent's Generation settings to the Summarizer agent's Scene History settings. A format set on the Conversation agent in an earlier version is not carried over: the format starts at Screenplay, so set it again in Scene History if you used another one."
- "Scene Backgrounds: Auto Backdrop for scene backgrounds is removed: backgrounds generated for the story always become the backdrop, and Visual Library backgrounds only go to the library. Backgrounds already attached to messages keep showing."
- "Visual Styles: Shipped visual styles moved into Talemate's template group. Back up edits to templates/world-state/visual-styles.yaml before updating; if they block the update, stash them or restore the tracked file."
0.39.0.dev:
features:
- "Node Reference: The documentation gained a complete node glossary covering every node available in the node editor - 400+ nodes across the engine, agent integrations and shipped node modules - organized into categorized reference pages listing each node's registry path, input/output sockets and properties. The Help Agent can search and read these pages, so asking it what a node does or how to use it now returns grounded answers. The pages are rendered from the live node registry by a new `glossary` subcommand on the node tools CLI (`python -m talemate.game.engine.nodes.tools glossary --write`), with a `--check` mode that detects when the committed reference has drifted from the code."

View file

@ -69,6 +69,25 @@ Plain `uv sync` does not just skip the extra, it *removes* it: run against a
working environment it uninstalls `pytest`, `pytest-xdist` and `pytest-asyncio`,
breaking the command above.
Some tests tokenize text with NLTK and fail with `LookupError: Resource punkt_tab
not found` until its data is downloaded once (CI runs the same step):
```bash
uv run python -c "import nltk; nltk.download('punkt_tab')"
```
Tests run against `config.example.yaml`: the root fixture loads it as the
runtime configuration and redirects configuration writes to a temporary
directory. A test must not read, write or delete your active `config.yaml`,
local scenes or user templates.
Six Compose configuration tests call `docker compose config`, so they need the
`docker compose` CLI (check with `docker compose version`), but no running Docker
daemon. Without the CLI they fail with setup guidance. To leave them out on
purpose, deselect them; pytest reports the deselected count:
```bash
uv run pytest tests/ -m "not requires_compose"
```
The suite runs distributed across your CPU cores by default (via `pytest-xdist`).
If your environment predates that — pytest installed, `pytest-xdist` not — pytest
exits with `error: unrecognized arguments: -n --dist worksteal`; install the `dev`
@ -81,6 +100,19 @@ Pass `-n0` to run serially while debugging a specific test:
uv run pytest tests/ -n0 -s -x
```
After you add or change a node (its class, docstring, sockets or properties),
regenerate the node reference pages under
`docs/user-guide/node-editor/reference/nodes/`; `--check` reports pages that
no longer match the code:
```bash
uv run python -m talemate.game.engine.nodes.tools glossary --write
uv run python -m talemate.game.engine.nodes.tools glossary --check
```
The frontend has its own suite — run `pnpm test` from `talemate_frontend/` (see
`talemate_frontend/README.md` for the pnpm setup), and `pnpm lint` for the
frontend lint rules. CI runs both suites and the lint on every pull request.
## Questions?
If you're unsure whether your contribution would be welcome, please open an issue to discuss it first. This saves everyone time and ensures alignment with the project's direction.

View file

@ -1,54 +1,63 @@
# Talemate
Roleplay with AI with a focus on strong narration and consistent world and game state tracking.
Roleplay with AI, with a focus on narration and consistent world and game state tracking.
<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">|
|<img src="docs/img/ss-1.png" width="400" height="250" alt="Scene view: AI-written dialogue between two characters with portraits, the characters, places and objects tracked in the World panel, and the Director's suggested next actions for the player">|<img src="docs/img/ss-2.png" width="400" height="250" alt="Visual library review queue: generated portraits of two characters, a scene background and a scene illustration, with the illustration's prompt and metadata">|
|------------------------------------------|------------------------------------------|
|<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">|
|<img src="docs/img/ss-3.png" width="400" height="250" alt="Node editor showing the generate-storyline module, with its stages and connected nodes">|<img src="docs/img/ss-4.png" width="400" height="250" alt="Simulation Suite: the player asks the computer to add a character, the computer adds the cabin steward to the simulation, and the narration that follows">|
</div>
## Core Features
- Multiple agents for dialogue, narration, summarization, direction, editing, world state management, character/scenario creation, text-to-speech, and visual generation
- Supports per agent API selection
- 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
- Agents for dialogue, narration, summarization, scene direction, editing, world state tracking, character and scenario creation, text-to-speech, image generation, and answering questions about Talemate itself
- A separate client and model per agent, with optional per-scene agent settings
- Long-term memory, layered history summaries and tracking of the passage of time
- Tracked character and world states, pins and game state variables that are kept in the AI's context
- [Character knowledge](https://vegu-ai.github.io/talemate/user-guide/world-editor/knowledge/): characters know only the passages they were present for and the information shared with them, with Learn / Never Learn rules for exceptions
- [Character perspectives](https://vegu-ai.github.io/talemate/user-guide/perspective-view/) (optional mode): each character keeps their own account of events, used for their memories and summaries and readable beside the story
- [Decision model](https://vegu-ai.github.io/talemate/user-guide/app-settings/decision-model/) (optional): a small model answers questions about the story with a probability, so other agents can skip or choose without a full request; every answer is listed in a Decision Log
- [Director chat](https://vegu-ai.github.io/talemate/user-guide/agents/director/chat/) to query and change the scene in conversation, and optional autonomous scene direction
- World editor for characters, world entries, history, pins and the context database, with AI-assisted character and scenario creation from templates and character card import
- Image generation for character portraits, scene illustrations and backdrops, managed in a visual library
- Text-to-speech with per-character voices and several local and remote backends
- [Node editor](https://vegu-ai.github.io/talemate/user-guide/node-editor/) for scene logic and reusable modules
- [Scene revisions](https://vegu-ai.github.io/talemate/user-guide/restoring-scenes/) to browse saved states per message and fork a new save from any of them, and [replay](https://vegu-ai.github.io/talemate/user-guide/replay/) to step through a story one passage at a time
- [Prompt manager](https://vegu-ai.github.io/talemate/user-guide/prompts/): every prompt is a Jinja2 template that can be overridden
- [Themes](https://vegu-ai.github.io/talemate/user-guide/templates/themes/): light and dark themes, and your own themes edited with a live preview
- [Help agent](https://vegu-ai.github.io/talemate/user-guide/agents/help/) that answers questions about Talemate from the bundled documentation and, with your permission, changes settings, themes and templates
## Documentation
- [Installation and Getting started](https://vegu-ai.github.io/talemate/)
- [Model expectations](https://vegu-ai.github.io/talemate/getting-started/model-expectations/) - what Talemate needs from your model
- [User Guide](https://vegu-ai.github.io/talemate/user-guide/interacting/)
## Discord Community
Need help? Join the new [Discord community](https://discord.gg/8bGNRmFxMj)
Need help? Join the [Discord community](https://discord.gg/8bGNRmFxMj)
## Supported APIs
- [OpenAI](https://platform.openai.com/overview)
- [Anthropic](https://www.anthropic.com/)
- [Google Gemini](https://ai.google.dev/) (Gemini API key or Vertex AI)
- [mistral.ai](https://mistral.ai/)
- [Cohere](https://www.cohere.com/)
- [Groq](https://www.groq.com/)
- [Google Gemini](https://console.cloud.google.com/)
- [Cohere](https://cohere.com/)
- [Groq](https://groq.com/)
- [DeepSeek](https://platform.deepseek.com/)
- [OpenRouter](https://openrouter.ai/)
Supported self-hosted APIs:
- [llama.cpp](https://github.com/ggml-org/llama.cpp) (`llama-server`)
- [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/)
- [llamacpp](https://github.com/ggerganov/llama.cpp) with the `api_like_OAI.py` wrapper
- let me know if you have tested any other implementations and they failed / worked or landed somewhere in between
Other clients:
- [OpenAI compatible](https://vegu-ai.github.io/talemate/user-guide/clients/types/openai-compatible/) - any server with an OpenAI-style completions or chat completions API, for example [DeepInfra](https://deepinfra.com/)
- [Pi Bridge](https://vegu-ai.github.io/talemate/user-guide/clients/types/pi-bridge/) - runs generations through the [pi coding agent](https://github.com/earendil-works/pi), which handles provider authentication and model selection

View file

@ -1,5 +1,4 @@
nav:
- Home: index.md
- Getting started: getting-started
- User guide: user-guide
- Developer guide: dev
- User guide: user-guide

View file

@ -1,166 +0,0 @@
# 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'},
]
```

View file

@ -1,3 +0,0 @@
# Coming soon
Developer documentation is coming soon. Stay tuned!

View file

@ -1,24 +0,0 @@
# Node reference glossary
The [node reference](/talemate/user-guide/node-editor/reference/nodes/) in the user guide — one page per node category, listing every node's registry path, input/output sockets and properties — is not written by hand. It is rendered from the live node registry by the `glossary` subcommand of the node tools CLI.
## Regenerating the pages
After adding, removing or changing nodes (or their docstrings, sockets or properties), regenerate the reference:
```bash
uv run python -m talemate.game.engine.nodes.tools glossary --write
```
This rewrites the generated portion of every page under `docs/user-guide/node-editor/reference/nodes/`. Anything above the `<!-- glossary:generated -->` marker in a page is a hand-editable intro and is preserved across regenerations — everything below the marker is overwritten.
## Checking for drift
```bash
uv run python -m talemate.game.engine.nodes.tools glossary --check
```
compares the committed pages against a fresh render and exits non-zero when they have drifted from the code (missing pages, stale pages, or generated content that no longer matches). Run it before shipping node changes to catch a forgotten `--write`.
!!! note
Loading the full node registry takes a while — both commands import every node module before rendering.

View file

@ -1,85 +0,0 @@
# Template Overrides
!!! warning "Old documentation"
This is old documentation and needs to be updated, however may still contain useful information.
## Introduction to Templates
In Talemate, templates are used to generate dynamic content for various agents involved in roleplaying scenarios. These templates leverage the Jinja2 templating engine, allowing for the inclusion of variables, conditional logic, and custom functions to create rich and interactive narratives.
## Template Structure
A typical template in Talemate consists of several sections, each enclosed within special section tags (`<|SECTION:NAME|>` and `<|CLOSE_SECTION|>`). These sections can include character details, dialogue examples, scenario overviews, tasks, and additional context. Templates utilize loops and blocks to iterate over data and render content conditionally based on the task requirements.
## Overriding Templates
Users can customize the behavior of Talemate by overriding the default templates. To override a template, create a new template file with the same name in the `./templates/prompts/{agent}/` directory. When a custom template is present, Jinja2 will prioritize it over the default template located in the `./src/talemate/prompts/templates/{agent}/` directory.
## Creator Agent Templates
The creator agent templates allow for the creation of new characters within the character creator. Following the naming convention `character-attributes-*.jinja2`, `character-details-*.jinja2`, and `character-example-dialogue-*.jinja2`, users can add new templates that will be available for selection in the character creator.
### Requirements for Creator Templates
- All three types (`attributes`, `details`, `example-dialogue`) need to be available for a choice to be valid in the character creator.
- Users can check the human templates for an understanding of how to structure these templates.
### Example Templates
- `src/talemate/prompts/templates/creator/character-attributes-human.jinja2`
- `src/talemate/prompts/templates/creator/character-details-human.jinja2`
- `src/talemate/prompts/templates/creator/character-example-dialogue-human.jinja2`
These example templates can serve as a guide for users to create their own custom templates for the character creator.
### Extending Existing Templates
Jinja2's template inheritance feature allows users to extend existing templates and add extra information. By using the `{% extends "template-name.jinja2" %}` tag, a new template can inherit everything from an existing template and then add or override specific blocks of content.
#### Example
To add a description of a character's hairstyle to the human character details template, you could create a new template like this:
```jinja2
{% extends "character-details-human.jinja2" %}
{% block questions %}
{% if character_details.q("what does "+character.name+"'s hair look like?") -%}
Briefly describe {{ character.name }}'s hair-style using a narrative writing style that reminds of mid 90s point and click adventure games. (2 - 3 sentences).
{% endif %}
{% endblock %}
```
This example shows how to extend the `character-details-human.jinja2` template and add a block for questions about the character's hair. The `{% block questions %}` tag is used to define a section where additional questions can be inserted or existing ones can be overridden.
## Advanced Template Topics
### Jinja2 Functions in Talemate
Talemate exposes several functions to the Jinja2 template environment, providing utilities for data manipulation, querying, and controlling content flow. Here's a list of available functions:
1. `set_prepared_response(response, prepend)`: Sets the prepared response with an optional prepend string. This function allows the template to specify the beginning of the LLM response when processing the rendered template. For example, `set_prepared_response("Certainly!")` will ensure that the LLM's response starts with "Certainly!".
2. `set_prepared_response_random(responses, prefix)`: Chooses a random response from a list and sets it as the prepared response with an optional prefix.
3. `set_eval_response(empty)`: Prepares the response for evaluation, optionally initializing a counter for an empty string.
4. `set_json_response(initial_object, instruction, cutoff)`: Prepares for a JSON response with an initial object and optional instruction and cutoff.
5. `set_question_eval(question, trigger, counter, weight)`: Sets up a question for evaluation with a trigger, counter, and weight.
6. `disable_dedupe()`: Disables deduplication of the response text.
7. `random(min, max)`: Generates a random integer between the specified minimum and maximum.
8. `query_scene(query, at_the_end, as_narrative)`: Queries the scene with a question and returns the formatted response.
9. `query_text(query, text, as_question_answer)`: Queries a text with a question and returns the formatted response.
10. `query_memory(query, as_question_answer, **kwargs)`: Queries the memory with a question and returns the formatted response.
11. `instruct_text(instruction, text)`: Instructs the text with a command and returns the result.
12. `retrieve_memories(lines, goal)`: Retrieves memories based on the provided lines and an optional goal.
13. `uuidgen()`: Generates a UUID string.
14. `to_int(x)`: Converts the given value to an integer.
15. `config`: Accesses the configuration settings.
16. `len(x)`: Returns the length of the given object.
17. `count_tokens(x)`: Counts the number of tokens in the given text.
18. `print(x)`: Prints the given object (mainly for debugging purposes).
These functions enhance the capabilities of templates, allowing for dynamic and interactive content generation.
### Error Handling
Errors encountered during template rendering are logged and propagated to the user interface. This ensures that users are informed of any issues that may arise, allowing them to troubleshoot and resolve problems effectively.
By following these guidelines, users can create custom templates that tailor the Talemate experience to their specific storytelling needs.# Template Overrides in Talemate

View file

@ -1,14 +0,0 @@
## 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)

View file

@ -1,6 +1,8 @@
nav:
- 1. Installation: installation
- 2. Setup Wizard: setup-wizard.md
- 3. Connect a client: connect-a-client.md
- 4. Load a scene: load-a-scene.md
- 3. Model expectations: model-expectations.md
- 4. Connect a client: connect-a-client.md
- 5. Load a scene: load-a-scene.md
- 6. Upgrade Notes: upgrading.md
- ...

View file

@ -61,22 +61,29 @@ The file is opened the first time a prompt is logged after startup and kept open
!!! info "`logs/prompt_log.jsonl` vs `logs/prompt_log.json`"
The JSON-Lines file described here is written by the server while it runs.
The similarly named `logs/prompt_log.json` is a separate, one-shot snapshot produced by the **Export** button in the Debug Tools → Prompts tab and is independent of this environment variable.
The similarly named `logs/prompt_log.json` is a separate, one-shot snapshot produced by the **Dump to file** button in the Debug Tools → Prompts tab and is independent of this environment variable.
## Record schema
Each line in `prompt_log.jsonl` is a single JSON object with the fields below. Field order inside the object is not guaranteed.
The server writes one terminal record per logical request, including failures and cancellations. Retries share its identity. The in-app viewers additionally receive active snapshots as the request progresses; a one-shot dump can therefore contain active records with null pending fields.
| Field | Type | Description |
|-------|------|-------------|
| `request_id` | string | Unique identity of the logical request, shared by its lifecycle updates. |
| `status` | string | `active`, `completed`, `failed` or `cancelled`. JSONL records are terminal. |
| `started_at` | number | Unix timestamp when the request began. |
| `attempts` | int | Number of provider attempts, including retries. Zero while preparing or waiting to start. |
| `error` | string or null | Failure/cancellation information, or the current retry/error-dialog reason while active. |
| `kind` | string | Prompt kind identifier (e.g. `conversation`, `narrate_scene`, `summarize`). Corresponds to the template/system-prompt kind used for the call. |
| `prompt` | string | The full finalized prompt text sent to the model, after template rendering and any client-side formatting. |
| `response` | string | The full model response text, after stop-string trimming and smart-quote normalization. |
| `response` | string or null | The full model response text, after stop-string trimming and smart-quote normalization; null if none was received. |
| `prompt_tokens` | int | Prompt token count. Uses the client's own counter unless the backend returned an explicit prompt-token count, in which case that value is preferred. |
| `response_tokens` | int | Response token count. Uses the backend-reported count when available, otherwise the client's tokenizer. |
| `client_name` | string | Name of the client that produced the prompt (as configured on the Clients screen). |
| `client_type` | string | Client type identifier (e.g. `openai`, `anthropic`, `koboldcpp`). |
| `time` | number | Wall-clock seconds spent on the generation, measured around the backend call. |
| `time` | number or null | Elapsed seconds for the logical request, including preparation, waiting and retries; null while active. |
| `agent_stack` | list of strings | The agent call stack at the time of the prompt, outermost first. The final entry is the agent that actually issued the call (e.g. `["director", "conversation"]`). Empty if no agent context was active. |
| `generation_parameters` | object | Final generation parameters passed to the backend for this call (temperature, top-p, max tokens, etc. — contents vary by client type). |
| `inference_preset` | string or null | Name of the active inference preset, if any. |
@ -84,7 +91,9 @@ Each line in `prompt_log.jsonl` is a single JSON object with the fields below. F
| `reasoning` | string or null | The extracted reasoning / thinking trace for this response, when the client supports reasoning tokens. |
| `template_uid` | string or null | UID of the Jinja prompt template that produced the prompt. Useful for correlating a log line back to a specific template in the Prompt Manager. |
The record is the same `PromptData` structure that Talemate emits over the websocket to populate the in-app [Debug Tools](../../user-guide/debug-tools.md#prompts) Prompts tab, so anything visible there is also in the log file.
Token counts can be null when unavailable. Input tokens initially use the local estimate and are replaced by provider usage when supplied. Explicit zero counts remain zero. Response usage is pending during generation and unavailable after a failure or cancellation if the provider supplied none.
The record uses the same `PromptData` structure that Talemate emits over the websocket to populate the in-app [Debug Tools](../../user-guide/debug-tools.md#prompts) Prompts tab.
## Quick inspection

View file

@ -7,6 +7,9 @@ Once Talemate is up and running and you are connected, the Home screen shows a w
Talemate uses client(s) to connect to local or remote AI text generation APIs like koboldcpp, text-generation-webui or OpenAI.
!!! note "Which model?"
Talemate expects a current reasoning model with reliable structured output and 16k or more context. See [Model expectations](model-expectations.md) for the bar, known good examples and what still works with an older model.
## Add a new client
On the right hand side click the **:material-plus-box: ADD CLIENT** button.
@ -18,9 +21,11 @@ On the right hand side click the **:material-plus-box: ADD CLIENT** button.
![open clients](/talemate/img/0.26.0/open-clients.png)
The client configuration window will appear. Here you can choose the type of client you want to add.
This takes you to **Settings → Connections → Clients** with the **Client type** menu open. Pick the type of client you want to add and it is created right away, with its editor next to the list.
![connect a client add client modal](/talemate/img/0.39.0/connect-a-client-add-client-modal.png)
![connect a client add client](/talemate/img/0.40.0/connect-a-client-add-client.png)
Fill in the client's settings and click **:material-check-circle-outline: Save** in the toolbar at the top to apply them. Nothing is connected until you save.
## Choose an API / Client Type
@ -60,7 +65,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.30.0/connect-a-client-ready.png)
![Connect a client assigned](/talemate/img/0.40.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.
@ -70,4 +75,6 @@ You can tell the client is assigned to the agent by checking the tag beneath the
If for some reason the client is not assigned to the agent, you can manually assign it to all agents by clicking the **:material-transit-connection-variant: Assign to all agents** button.
![Connect a client assign to all agents](/talemate/img/0.26.0/connect-a-client-assign-to-all-agents.png)
![Connect a client assign to all agents](/talemate/img/0.40.0/connect-a-client-assign-to-all-agents.png)
The same action is available on the [Clients settings page](/talemate/user-guide/clients/client-configuration/), above the client editor. There it is applied when you save, and it is disabled while the client itself is disabled — enable the client first.

View file

@ -80,6 +80,14 @@ services:
## General
### Stopping Talemate
Press Ctrl+C once in the backend terminal. Talemate closes frontend connections and gives background work up to five seconds to finish.
If shutdown stalls, Talemate prints `Shutdown exceeded 5 seconds; forcing process exit` and ends the backend with a nonzero exit status. This forced exit abandons unfinished work. Any stop discards unsaved changes. Save your scene before you stop Talemate.
If Talemate reports that it cannot start the shutdown watchdog, shutdown has no time limit; press Ctrl+C again to end the backend.
### Running behind reverse proxy with SSL
To run Talemate behind a reverse proxy with SSL:

View file

@ -21,4 +21,6 @@
| **`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. |
No system-wide Python or Node.js is required – Talemate uses the embedded runtimes it downloads automatically. The bundled Node.js is version 22, which is required by the frontend's package manager (pnpm).
No system-wide Python or Node.js is required – Talemate uses the embedded runtimes it downloads automatically. The bundled Node.js is version 22, which is required by the frontend's package manager (pnpm).
pnpm is installed locally under `embedded_node/pnpm` at the version pinned by Talemate. Installation, updates, and frontend startup reuse this copy, so a global pnpm installation or Corepack cache is not required. The first run and a change of pnpm version require an internet connection.

View file

@ -4,7 +4,7 @@ Once you've set up a client and assigned it to all the agents, you will be prese
To load the introductory `Infinity Quest` scenario, simply click on its entry in the `Quick load` section.
![Load infinity quest](/talemate/img/0.39.0/getting-started-load-screen.png)
![Load infinity quest](/talemate/img/0.40.0/getting-started-load-screen.png)
!!! info "First time may take a moment"
When you load the a scenario for the first time, Talemate will need to initialize the long term memory model. Which likely means a download. Just be patient and it will be ready soon.

View file

@ -0,0 +1,51 @@
# Model expectations
Talemate is built for current reasoning and agentic models. The director chats with function calling, focal actions make several calls in a row, perception analysis returns strict JSON, knowledge extraction and planning return structured output. A model from the pre-agentic era (a small local instruct model, an older hosted model without reasoning) fails these steps, and the failures look like Talemate bugs.
This page states what Talemate needs for the full experience and what still works without it. It is not a list of supported models: an unknown model name is never judged, and nothing below blocks you.
## The bar
Check your model against these three points:
- A current reasoning-capable model
- Reliable JSON and tool-call output
- A usable context of 16k tokens or more (32k recommended for Character perspectives)
The **Context Length** setting of a client is the only one of the three that Talemate can check itself. A new client starts at 16384 tokens. When a client's Context Length sits below 16384, the client settings editor shows a warning under the field; raise the setting if your model allows it.
A bigger context is not better by itself. Talemate is made to work well with smaller context sizes: its summarization layers keep the story context compact, so 16k to 48k is usually enough. The [Setup Wizard](setup-wizard.md) says so when you add a client, and when a client's Context Length is above 65536 the client settings editor shows a short note under the field. A larger context still works; set one if your model and budget allow it.
## Known good examples
These are examples, updated with each release. They are never used as a check.
| Provider type | Examples |
|---|---|
| Hosted | gemini-3.8-flash, glm-5.2 |
| Self-hosted | Qwen 3.8 27B (reasoning on), Gemma 4 31B (reasoning on), Gemma 4 26B (reasoning on, lower VRAM) |
The self-hosted examples are the smallest models that run the full agentic workflow reliably. Turn reasoning on for them in the [client settings](/talemate/user-guide/clients/reasoning/).
## What still works without it
Basic conversation and narration work with older or smaller models. Expect failures in the director, planning, knowledge and Character perspectives features and in other analytical requests.
A story in **Standard** mode asks less of the model than a story with **Character perspectives**, which adds one analytical request per passage and pauses generation when that analysis fails. See [Choosing a mode](/talemate/user-guide/world-editor/knowledge/#choosing-a-mode) before you create your first story.
## Symptoms you will see with an older model
Before you file a bug, check these signs of a model below the bar:
- Function calls do not happen: the director answers in prose instead of acting, or an action completes without any change.
- The director replies with a `report_issue` fallback instead of the action you asked for.
- Perception analysis fails in a Character perspectives story, and the generation error dialog offers **Retry** again and again.
- Structured output comes back empty or malformed (broken JSON or YAML), and a generation error dialog reports a parse failure.
- Reasoning models drift or loop when reasoning is off; turn it on in the client settings.
The bundled [Model Testing Harness](/talemate/user-guide/clients/model-testing-harness/) scene runs these checks against the clients assigned to your agents. Load it after you configure a new client.
## Where this shows in the app
- The [Setup Wizard](setup-wizard.md) shows this bar on its first step, before you pick a provider.
- The client editor, in the wizard and on **Settings → Connections → Clients**, links to this page. The Clients page editor also shows the Context Length setting, warns when it is below 16384 and notes when it is above 65536 that a smaller context is usually enough.

View file

@ -25,22 +25,29 @@ Choose this if you want to use a cloud-based AI service. This requires an API ke
- Anthropic
- And others
![Setup wizard step 1 - choose provider type](../img/0.35.0/setup-wizard-step1-provider-type.png)
Below the two options, the wizard shows **What Talemate expects from your model**: the bar a model has to meet for the full experience, known good examples for each provider type, and what still works without it. Read it before you pick a model; the [Model expectations](model-expectations.md) page has the details and the symptoms of a model below the bar.
![Setup wizard step 1 - choose provider type](../img/0.40.0/setup-wizard-step1-provider-type.png)
## Step 2: Add Your Client
After selecting your provider type, you will choose a specific client to configure.
For **Hosted API** users, OpenRouter is selected by default. For **Self-hosted** users, KoboldCpp is selected by default.
For **Hosted API** users, OpenRouter is selected by default. For **Self-hosted** users, llama.cpp is selected by default.
Select your preferred client from the dropdown and click **Add Client** to open the client configuration dialog.
Select your preferred client from the dropdown. Returning to this step keeps your selected client and edited configuration. The essential settings for that client type — its name, API URL and key, and the model — appear right below the dropdown. Fill them in and click **Add Client** to create the client.
![Setup wizard step 2 - add client](../img/0.35.0/setup-wizard-step2-add-client.png)
A one-line pointer above the settings links to the [Model expectations](model-expectations.md) page. A new client starts with a Context Length of 16384 tokens. The wizard does not show that setting; the editor on **Settings → Connections → Clients** shows the value and warns when it sits below the floor.
Once you complete the client configuration, the wizard will automatically advance to the next step.
![Setup wizard step 2 - add client](../img/0.40.0/setup-wizard-step2-add-client.png)
Once the client has been created, the wizard will automatically advance to the next step.
!!! info "Reasoning Models"
If you are using a reasoning model (like DeepSeek R1 or GLM), you will need to enable reasoning in the client settings after setup. For OpenRouter users, new clients have reasoning enabled by default with a budget of 2048 reasoning tokens, so the default model selected during the wizard (Gemini 3.6 Flash) and other reasoning models work out of the box. If you switch to a model that does not reason, you can turn reasoning off in the client settings.
If you are using a reasoning model (like DeepSeek R1 or GLM), you will need to enable reasoning in the client settings after setup. For OpenRouter users, new clients have reasoning on by default at the model's default effort, so the default model selected during the wizard (Gemini 3.8 Flash) and other reasoning models work out of the box. If you switch to a model that does not reason, you can turn reasoning off in the client settings.
!!! info "Context size"
Talemate is made to work well with smaller context sizes: its summarization layers keep the story context compact, so 16k to 48k is usually enough. A larger context works, but is usually not needed. See [Model expectations](model-expectations.md).
## Step 3: Configure Long-term Memory
@ -70,7 +77,7 @@ Faster performance on NVIDIA GPUs. Recommended if you have an NVIDIA GPU with su
Works on any system. Use this if you do not have an NVIDIA GPU or prefer not to use GPU memory for embeddings.
![Setup wizard step 3 - memory configuration](../img/0.35.0/setup-wizard-step3-memory.png)
![Setup wizard step 3 - memory configuration](../img/0.40.0/setup-wizard-step3-memory.png)
The wizard will automatically detect your system capabilities and suggest appropriate defaults based on your available hardware.

View file

@ -0,0 +1,51 @@
<!-- Generated from the changelog build. Do not edit by hand. -->
# Upgrading
Each release below lists the changes that may need something from you when you update: a setting to review, a file to back up, or a value that now means something else. Releases without such changes are not listed. The newest release comes first.
## 0.40.0
### Scene Revisions (breaking change)
Upgrading from 0.39.0 starts revisions from a current save when you first load or save it, in `<project>/data.db`. The new system ignores `<project>/changelog/` and leaves it untouched; you can delete that old directory by hand. Earlier revisions are not converted.
### OpenAI Clients
Review saved OpenAI settings after upgrading. GPT-5 and GPT-6 models keep Reasoning on; enable it for o-series models if needed. Sampling controls start off. For o1-mini or o1-preview, turn Send System Message off; turn Stream off if unavailable, and choose max_tokens for servers requiring it. Save your settings.
### OpenRouter Reasoning
The client no longer sends a reasoning budget. With Reasoning on it sends your Reasoning Effort, or asks the model to think at its own default effort; with Reasoning off it sends nothing, and models that always think use their provider's default. A saved Reasoning Tokens number from 0.39.0 no longer controls how much the model thinks: it now means Extra Completion Tokens. If you used it to control thinking, choose a Reasoning Effort instead.
### Compatible Voice Servers
OpenAI-compatible voice backends now request MP3 by default. Select WAV under Response format if your server cannot produce MP3.
### Shared Worlds
Back up older shared worlds before upgrading. Missing shared entries can be recovered from a linked scene only until 0.40 first writes that world, so load the scene holding them first. Entries intentionally removed in an older version may also return. Recover overwritten text from older revisions in 0.39.0 before upgrading, or from a backup of `<project>/changelog/`.
### Scene Context Format
The scene context format (Screenplay, Chat, Narrative, AI Aware) moved from the Conversation agent's Generation settings to the Summarizer agent's Scene History settings. A format set on the Conversation agent in an earlier version is not carried over: the format starts at Screenplay, so set it again in Scene History if you used another one.
### Scene Backgrounds
Auto Backdrop for scene backgrounds is removed: backgrounds generated for the story always become the backdrop, and Visual Library backgrounds only go to the library. Backgrounds already attached to messages keep showing.
### Visual Styles
Shipped visual styles moved into Talemate's template group. Back up edits to templates/world-state/visual-styles.yaml before updating; if they block the update, stash them or restore the tracked file.
## 0.37.0
- Default frontend port changed from 8080 to 8082. Update any bookmarks or reverse-proxy configs that pointed at `localhost:8080`. To keep the old port, set `TALEMATE_FRONTEND_PORT=8080` before launching.
- Docker compose variable `FRONTEND_PORT` renamed to `TALEMATE_FRONTEND_PORT`. If you had `FRONTEND_PORT` set in a `.env` file or your shell, rename it. The new variable controls both the published host port and the port uvicorn binds inside the container.
- Docker compose variable `BACKEND_PORT` renamed to `TALEMATE_BACKEND_PORT`. Same migration as above — rename in any `.env` files or shell environments. The new variable controls both the published host port and the port uvicorn binds inside the container.
## 0.32.0
- XTTS2 TTS support has been removed. Switch to one of the new local backends (F5-TTS, Chatterbox, Kokoro) or a remote backend (ElevenLabs, Google Gemini-TTS, OpenAI) via the voice library.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.1 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.5 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.6 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.5 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 49 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.1 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 53 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.8 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 54 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 72 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 107 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 71 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 346 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 35 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 52 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 48 KiB

Some files were not shown because too many files have changed in this diff Show more