Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Run prompt variable substitution after the append step so appended text honours placeholders too

Murtaza Nasirbfe63411fa7c
diff --git a/docs/user-guide/settings.md b/docs/user-guide/settings.md
index f90a5fa3..7b8c6379 100644
--- a/docs/user-guide/settings.md
+++ b/docs/user-guide/settings.md
@@ -209,7 +209,17 @@ Tag prompts stack intelligently when multiple tags are applied. If you tag a rec
### Prompt Variables
-Tag and folder custom prompts may contain `{{name}}` placeholders that are filled in per recording at upload time. A "Council Meetings" tag whose prompt reads `Generate minutes for this council meeting. Agenda: {{agenda}}. Attendees: {{attendees}}.` will cause Speakr's upload form to display two input fields ("Agenda", "Attendees") whenever that tag is selected. The values are stored on the recording and substituted into the prompt at summarisation time, including on reprocessing. Variable names follow identifier rules (letters, digits, and underscores; must start with a letter or underscore). Labels are derived from the name automatically (`meeting_date` becomes "Meeting date").
+Tag and folder custom prompts may contain `{{name}}` placeholders that are filled in per recording at upload time. A "Council Meetings" tag whose prompt reads `Generate minutes for this council meeting. Agenda: {{agenda}}. Attendees: {{attendees}}.` will cause Speakr's upload form to display two input fields ("Agenda", "Attendees") whenever that tag is selected. The values are stored on the recording and substituted into the prompt at summarisation time, including on reprocessing.
+
+**Naming rules.** Variable names use ASCII identifier characters only (letters, digits, and underscores; must start with a letter or underscore). Names with non-ASCII characters such as `{{дата}}` are not recognised as placeholders and remain in the prompt as literal text. Labels in the upload form are derived automatically (`meeting_date` becomes "Meeting date").
+
+**Limits.** Up to 50 variables per recording, 8000 characters per value, 32000 characters total. Excess input is truncated server-side.
+
+**Single-pass substitution.** Variables are replaced once. A value that itself contains `{{anothervar}}` is treated as literal text rather than recursively expanded.
+
+**Drop-folder uploads.** Recordings ingested through the auto-process watch directory bypass the upload form and therefore have no opportunity to fill variables. Their stored `prompt_variables` is empty and any placeholders substitute to empty strings on the first summary run. Reprocess after upload to fill values, or use only non-templated prompts on tags applied to drop-folder content.
+
+**Editing values after upload.** Stored variable values are not yet editable from the recording detail or reprocess modal. To change a value, re-upload the recording or wait for that capability in a future release.
### ASR Defaults
diff --git a/src/tasks/processing.py b/src/tasks/processing.py
index e2d56ed1..5d4947c6 100644
--- a/src/tasks/processing.py
+++ b/src/tasks/processing.py
@@ -541,10 +541,26 @@ def generate_summary_only_task(app_context, recording_id, custom_prompt_override
- **Action Items**: A bulleted list of tasks assigned, including who is responsible if mentioned"""
current_app.logger.info(f"Using hardcoded default prompt for recording {recording_id}")
- # Substitute {{variable}} placeholders in the resolved prompt with the
- # values the user supplied at upload time (or via a later edit). This
- # turns tag/folder prompts that contain `{{agenda}}` etc. into concrete
- # instructions for this specific recording.
+ # Append the user's per-run additions on top of the resolved default
+ # (issue / discussion #253). This is how a user supplies a meeting agenda
+ # or one-off context without rewriting their saved summary prompt.
+ # The append must happen BEFORE variable substitution so the appended
+ # text's own placeholders get substituted along with the resolved
+ # prompt's placeholders.
+ if custom_prompt_override and custom_prompt_append:
+ current_app.logger.info(
+ f"Appending custom prompt to resolved default for recording {recording_id} "
+ f"(append length: {len(custom_prompt_override)})"
+ )
+ summarization_instructions = (
+ f"{summarization_instructions}\n\n"
+ f"Additional context for this recording:\n{custom_prompt_override}"
+ )
+
+ # Substitute {{variable}} placeholders in the final composed prompt
+ # with the values the user supplied at upload time (or via a later
+ # edit). Running this AFTER the append step lets the appended text
+ # use the same variables as the resolved prompt.
from src.utils.prompt_variables import (
extract_template_variables,
substitute_template_variables,
@@ -563,19 +579,6 @@ def generate_summary_only_task(app_context, recording_id, custom_prompt_override
summarization_instructions, prompt_variables
)
- # Append the user's per-run additions on top of the resolved default
- # (issue / discussion #253). This is how a user supplies a meeting agenda
- # or one-off context without rewriting their saved summary prompt.
- if custom_prompt_override and custom_prompt_append:
- current_app.logger.info(
- f"Appending custom prompt to resolved default for recording {recording_id} "
- f"(append length: {len(custom_prompt_override)})"
- )
- summarization_instructions = (
- f"{summarization_instructions}\n\n"
- f"Additional context for this recording:\n{custom_prompt_override}"
- )
-
# Build context information
current_date = datetime.now().strftime("%B %d, %Y")
context_parts = []
diff --git a/tests/test_prompt_variables_integration.py b/tests/test_prompt_variables_integration.py
new file mode 100644
index 00000000..0c1e861c
--- /dev/null
+++ b/tests/test_prompt_variables_integration.py
@@ -0,0 +1,143 @@
+"""
+Integration test for prompt variable substitution in the summary task.
+
+Exercises `generate_summary_only_task` end to end (with the LLM client
+patched out) and asserts that:
+
+1. Variables in the resolved tag/folder/user/admin prompt are substituted.
+2. Variables appearing in the appended `custom_prompt_override` (issue #253
+ append mode) are also substituted, since substitution must happen on the
+ final composed prompt rather than on the resolved chain only.
+
+A regression of the substitution order (substituting before append) would
+produce a final prompt with literal `{{quarter}}` left in the appended
+section. This test catches that.
+"""
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+
+def app_with_db():
+ """Provide a Flask app context with a clean recording + tag."""
+ from src.app import app, db
+ from src.models import User, Recording, Tag
+
+ with app.app_context():
+ user = User.query.filter_by(username="prompt_var_test_user").first()
+ created_user = False
+ if not user:
+ user = User(username="prompt_var_test_user", email="[email protected]")
+ user.password = "unused"
+ db.session.add(user)
+ db.session.commit()
+ created_user = True
+
+ tag = Tag(
+ name=f"prompt_var_test_tag_{user.id}",
+ user_id=user.id,
+ color="#000000",
+ custom_prompt="Generate minutes for {{agenda}}.",
+ )
+ db.session.add(tag)
+ db.session.commit()
+
+ recording = Recording(
+ user_id=user.id,
+ title="Prompt Variable Test",
+ original_filename="test_prompt_vars.wav",
+ transcription='Hello world. This is a long enough transcription to satisfy the length check.',
+ status="COMPLETED",
+ prompt_variables={"agenda": "Budget review", "quarter": "Q3"},
+ )
+ db.session.add(recording)
+ db.session.commit()
+
+ # Apply tag to recording
+ from src.models import RecordingTag
+ rt = RecordingTag(recording_id=recording.id, tag_id=tag.id, order=1)
+ db.session.add(rt)
+ db.session.commit()
+
+ try:
+ yield app, db, user, recording, tag, created_user
+ finally:
+ try:
+ from src.models import RecordingTag
+ RecordingTag.query.filter_by(recording_id=recording.id).delete()
+ db.session.delete(recording)
+ db.session.delete(tag)
+ if created_user:
+ db.session.delete(user)
+ db.session.commit()
+ except Exception:
+ db.session.rollback()
+
+
+def _capture_summary_prompt(app):
+ """Patch `call_llm_completion` and return a holder that captures the
+ user-message content of the first call. The mock returns a stub
+ completion that yields a one-line summary so the task completes
+ without further side-effects."""
+ captured = {"user_prompt": None}
+
+ def _fake_completion(messages=None, **kwargs):
+ for msg in messages or []:
+ if msg.get("role") == "user":
+ captured["user_prompt"] = msg.get("content", "")
+ break
+ stub = MagicMock()
+ stub.choices = [MagicMock()]
+ stub.choices[0].message.content = "Test summary."
+ stub.usage = MagicMock()
+ stub.usage.prompt_tokens = 1
+ stub.usage.completion_tokens = 1
+ stub.usage.total_tokens = 2
+ return stub
+
+ return captured, _fake_completion
+
+
+def test_variables_substitute_in_resolved_prompt(app_with_db):
+ """A `{{name}}` in a tag's custom_prompt is replaced with the recording's stored value."""
+ app, db, user, recording, tag, created_user = app_with_db
+ from src.tasks.processing import generate_summary_only_task
+
+ captured, fake_completion = _capture_summary_prompt(app)
+ with patch("src.tasks.processing.call_llm_completion", side_effect=fake_completion), \
+ patch("src.tasks.processing.client", new=MagicMock()):
+ generate_summary_only_task(app.app_context(), recording.id, user_id=user.id)
+
+ prompt = captured["user_prompt"] or ""
+ assert "Budget review" in prompt, f"agenda value missing from prompt: {prompt[:500]}"
+ assert "{{agenda}}" not in prompt, f"placeholder leaked into prompt: {prompt[:500]}"
+
+
+def test_variables_substitute_in_appended_custom_prompt(app_with_db):
+ """A `{{name}}` in `custom_prompt_override` (append mode) is also substituted.
+
+ This is the regression test for the order-of-operations bug where the
+ substitution step ran before the append step, leaving placeholders in
+ the appended text intact.
+ """
+ app, db, user, recording, tag, created_user = app_with_db
+ from src.tasks.processing import generate_summary_only_task
+
+ captured, fake_completion = _capture_summary_prompt(app)
+ with patch("src.tasks.processing.call_llm_completion", side_effect=fake_completion), \
+ patch("src.tasks.processing.client", new=MagicMock()):
+ generate_summary_only_task(
+ app.app_context(),
+ recording.id,
+ custom_prompt_override="Also discuss strategic priorities for {{quarter}}.",
+ custom_prompt_append=True,
+ user_id=user.id,
+ )
+
+ prompt = captured["user_prompt"] or ""
+ # Both the resolved-chain variable and the append-text variable must substitute.
+ assert "Budget review" in prompt, f"agenda value missing: {prompt[:500]}"
+ assert "Q3" in prompt, f"quarter value (from append text) missing: {prompt[:500]}"
+ assert "{{agenda}}" not in prompt, f"agenda placeholder leaked: {prompt[:500]}"
+ assert "{{quarter}}" not in prompt, f"quarter placeholder leaked from append text: {prompt[:500]}"