feature: allow a watch or group to append to the inherited AI Change Summary prompt

Author: snowyukitty

changedetectionio/blueprint/tags/form.py

@@ -1,5 +1,6 @@
 from wtforms import (
     Form,
+    RadioField,
     StringField,
     SubmitField,
     TextAreaField,
@@ -10,7 +11,11 @@
 
 from changedetectionio.processors.restock_diff.forms import processor_settings_form as restock_settings_form
 from changedetectionio.llm.ui_strings import LLM_INTENT_TAG_PLACEHOLDER
-from changedetectionio.llm.evaluator import DEFAULT_CHANGE_SUMMARY_PROMPT
+from changedetectionio.llm.evaluator import (
+    DEFAULT_CHANGE_SUMMARY_PROMPT,
+    LLM_PROMPT_MODE_APPEND,
+    LLM_PROMPT_MODE_REPLACE,
+)
 
 class group_restock_settings_form(restock_settings_form):
     overrides_watch = BooleanField(_l('Activate for individual watches in this tag/group?'), default=False)
@@ -26,6 +31,15 @@ class group_restock_settings_form(restock_settings_form):
                                render_kw={"rows": "5", "placeholder": DEFAULT_CHANGE_SUMMARY_PROMPT},
                                default='')
 
+    llm_change_summary_mode = RadioField(
+        _l('How this prompt combines with the inherited one'),
+        choices=[
+            (LLM_PROMPT_MODE_REPLACE, _l('Replace the inherited prompt')),
+            (LLM_PROMPT_MODE_APPEND,  _l('Append to the inherited prompt')),
+        ],
+        default=LLM_PROMPT_MODE_REPLACE,
+    )
+
 class SingleTag(Form):
 
     name = StringField(_l('Tag name'), [validators.InputRequired()], render_kw={"placeholder": _l("Name")})

changedetectionio/forms.py

@@ -6,7 +6,13 @@
 
 from changedetectionio.blueprint.rss import RSS_FORMAT_TYPES, RSS_TEMPLATE_TYPE_OPTIONS, RSS_TEMPLATE_HTML_DEFAULT
 from changedetectionio.llm.ui_strings import LLM_INTENT_WATCH_PLACEHOLDER
-from changedetectionio.llm.evaluator import DEFAULT_CHANGE_SUMMARY_PROMPT, LLM_DEFAULT_MAX_SUMMARY_TOKENS, LLM_DEFAULT_THINKING_BUDGET
+from changedetectionio.llm.evaluator import (
+    DEFAULT_CHANGE_SUMMARY_PROMPT,
+    LLM_DEFAULT_MAX_SUMMARY_TOKENS,
+    LLM_DEFAULT_THINKING_BUDGET,
+    LLM_PROMPT_MODE_APPEND,
+    LLM_PROMPT_MODE_REPLACE,
+)
 from changedetectionio.conditions.form import ConditionFormRow
 from changedetectionio.notification_service import NotificationContextData
 from changedetectionio.strtobool import strtobool
@@ -886,6 +892,15 @@ class processor_text_json_diff_form(commonSettingsForm):
                                render_kw={"rows": "5", "placeholder": DEFAULT_CHANGE_SUMMARY_PROMPT},
                                default='')
 
+    llm_change_summary_mode = RadioField(
+        _l('How this prompt combines with the inherited one'),
+        choices=[
+            (LLM_PROMPT_MODE_REPLACE, _l('Replace the inherited prompt')),
+            (LLM_PROMPT_MODE_APPEND,  _l('Append to the inherited prompt')),
+        ],
+        default=LLM_PROMPT_MODE_REPLACE,
+    )
+
     include_filters = StringListField(_l('CSS/JSONPath/JQ/XPath Filters'), [ValidateCSSJSONXPATHInput()], default='')
 
     subtractive_selectors = StringListField(_l('Remove elements'), [ValidateCSSJSONXPATHInput(allow_json=False)])

changedetectionio/llm/evaluator.py

@@ -149,6 +149,13 @@ def _cached_system(text: str, model: str = '') -> dict:
     "Do not give partial listings such as 'Examples include:', always be thorough."
 )
 
+# How a watch's or tag's llm_change_summary combines with the prompt it inherits.
+# 'replace' is the default and the historical behaviour; 'append' lets a watch add a line
+# or two to the inherited prompt instead of holding a full private copy of it, so later
+# edits to the global prompt still reach that watch. Re #4251.
+LLM_PROMPT_MODE_REPLACE = 'replace'
+LLM_PROMPT_MODE_APPEND = 'append'
+
 
 def _summary_max_tokens(diff: str, max_cap: int = LLM_DEFAULT_MAX_SUMMARY_TOKENS) -> int:
     """Scale completion tokens to diff size: floor 400, ~1 token per 4 chars, ceiling max_cap."""
@@ -539,16 +546,54 @@ def run_setup(watch, datastore, snapshot_text: str) -> None:
 # AI Change Summary — human-readable description of what changed
 # ---------------------------------------------------------------------------
 
+def _first_tag_with_field(watch, datastore, field: str):
+    """Return (value, tag) for the first linked tag with a non-empty `field`, else ('', None).
+
+    Same first-match-wins order as resolve_llm_field(); this variant also hands back the
+    tag itself so the caller can read sibling keys such as the prompt mode.
+    """
+    for tag_uuid in watch.get('tags', []):
+        tag = datastore.data['settings']['application'].get('tags', {}).get(tag_uuid)
+        if tag:
+            value = (tag.get(field) or '').strip()
+            if value:
+                return value, tag
+    return '', None
+
+
+def _apply_prompt_layer(inherited: str, value: str, mode: str) -> str:
+    """Fold one cascade level's prompt onto what it inherited.
+
+    'append' keeps the inherited prompt and adds `value` after it, so a watch can add a
+    sentence or two without pinning a private copy of the prompt above it (see #4251).
+    Anything else replaces, which is the historical behaviour and stays the default.
+    """
+    if not value:
+        return inherited
+    if mode == LLM_PROMPT_MODE_APPEND and inherited:
+        return f"{inherited}\n\n{value}"
+    return value
+
+
 def get_effective_summary_prompt(watch, datastore) -> str:
     """Return the prompt that summarise_change will use.
 
-    Cascade: watch → tag → global settings default → hardcoded fallback.
+    Cascade: hardcoded fallback → global settings default → tag → watch. Each level with a
+    value either replaces what it inherited or appends to it, per its own
+    `llm_change_summary_mode`. With every level left on the default 'replace' this reduces
+    to the original watch → tag → global → hardcoded first-non-empty-wins behaviour.
     """
-    prompt, _ = resolve_llm_field(watch, datastore, 'llm_change_summary')
-    if prompt:
-        return prompt
-    global_default = get_llm_settings(datastore).change_summary_default.strip()
-    return global_default or DEFAULT_CHANGE_SUMMARY_PROMPT
+    prompt = get_llm_settings(datastore).change_summary_default.strip() or DEFAULT_CHANGE_SUMMARY_PROMPT
+
+    tag_value, tag = _first_tag_with_field(watch, datastore, 'llm_change_summary')
+    if tag_value:
+        prompt = _apply_prompt_layer(prompt, tag_value, tag.get('llm_change_summary_mode'))
+
+    watch_value = (watch.get('llm_change_summary') or '').strip()
+    if watch_value:
+        prompt = _apply_prompt_layer(prompt, watch_value, watch.get('llm_change_summary_mode'))
+
+    return prompt
 
 
 def compute_summary_cache_key(diff_text: str, prompt: str) -> str:

changedetectionio/model/__init__.py

@@ -191,6 +191,7 @@ def __init__(self, *arg, **kw):
             # LLM intent-based evaluation
             'llm_intent': '',                # Plain-English description of what the user cares about (change filter)
             'llm_change_summary': '',        # Prompt for AI Change Summary — replaces {{ diff }} in notifications
+            'llm_change_summary_mode': 'replace',  # 'replace' the inherited prompt, or 'append' to it
             'llm_prefilter': None,           # CSS selector derived at setup time (semantic only, e.g. "footer")
             'llm_evaluation_cache': {},      # {sha256(intent+diff): {important, summary}} - evaluated once, cached
             'fetch_backend': 'system',  # plaintext, playwright etc

changedetectionio/templates/edit/include_llm_intent.html

@@ -97,6 +97,23 @@ <h4 style="margin: 0 0 0.3em 0;">{{ _('AI Change Summary') }}</h4>
     <div style="margin-top: 0.3em;">
         <a href="#" class="pure-button button-xsmall" onclick="var t=document.getElementById('llm_change_summary'); if(!t.value&amp;&amp;t.placeholder) t.value=t.placeholder; return false;">{{ _('Modify default prompt') }}</a>
     </div>
+    <div class="pure-control-group" style="margin-top: 0.6em;">
+        <label>{{ form.llm_change_summary_mode.label.text }}</label>
+        <div>
+            {% for subfield in form.llm_change_summary_mode %}
+            <label class="pure-radio" style="display:block; font-weight:normal; margin-bottom:0.3em;">
+                {{ subfield() }} {{ subfield.label.text }}
+            </label>
+            {% endfor %}
+        </div>
+        <span class="pure-form-message-inline">
+        {% if watch is defined and watch %}
+            {{ _('Appending keeps the prompt inherited from the group or from global settings and adds your text after it, so later edits to that prompt still reach this watch.') }}
+        {% else %}
+            {{ _('Appending keeps the prompt inherited from global settings and adds your text after it, so later edits to that prompt still reach this group.') }}
+        {% endif %}
+        </span>
+    </div>
     {% if watch is defined and watch %}
     <div class="pure-form-message-inline">
         <strong>{{ _('Examples:') }}</strong>

changedetectionio/tests/llm/test_evaluator.py

@@ -556,3 +556,87 @@ def test_get_effective_prompt_cascades_from_tag(self):
         ds = _make_datastore(tags={'t1': tag})
         watch = _make_watch(llm_change_summary='', tags=['t1'])
         assert get_effective_summary_prompt(watch, ds) == 'tag-level prompt'
+
+
+# ---------------------------------------------------------------------------
+# llm_change_summary_mode — append vs replace (#4251)
+# ---------------------------------------------------------------------------
+
+class TestSummaryPromptAppendMode:
+    """A watch/tag may add to the prompt it inherits instead of holding a private copy.
+
+    Everything here must leave the legacy 'replace' path byte-identical — that is what
+    the TestSummaryCacheKey cases above pin.
+    """
+
+    def test_global_default_used_as_base_when_nothing_else_set(self):
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'})
+        assert get_effective_summary_prompt(_make_watch(), ds) == 'GLOBAL'
+
+    def test_watch_appends_to_global_default(self):
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'})
+        watch = _make_watch(llm_change_summary='Also mention the SKU.')
+        watch['llm_change_summary_mode'] = 'append'
+        assert get_effective_summary_prompt(watch, ds) == 'GLOBAL\n\nAlso mention the SKU.'
+
+    def test_watch_appends_to_hardcoded_default_when_no_global_set(self):
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt, DEFAULT_CHANGE_SUMMARY_PROMPT
+        ds = _make_datastore()
+        watch = _make_watch(llm_change_summary='Also mention the SKU.')
+        watch['llm_change_summary_mode'] = 'append'
+        result = get_effective_summary_prompt(watch, ds)
+        assert result == f'{DEFAULT_CHANGE_SUMMARY_PROMPT}\n\nAlso mention the SKU.'
+
+    def test_watch_append_targets_the_tag_prompt_when_a_tag_supplies_one(self):
+        """The watch appends to what it would otherwise have inherited — here the tag."""
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt
+        tag = {'title': 'grp', 'llm_change_summary': 'TAG'}
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'}, tags={'t1': tag})
+        watch = _make_watch(llm_change_summary='WATCH', tags=['t1'])
+        watch['llm_change_summary_mode'] = 'append'
+        assert get_effective_summary_prompt(watch, ds) == 'TAG\n\nWATCH'
+
+    def test_tag_and_watch_can_both_append_forming_a_chain(self):
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt
+        tag = {'title': 'grp', 'llm_change_summary': 'TAG', 'llm_change_summary_mode': 'append'}
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'}, tags={'t1': tag})
+        watch = _make_watch(llm_change_summary='WATCH', tags=['t1'])
+        watch['llm_change_summary_mode'] = 'append'
+        assert get_effective_summary_prompt(watch, ds) == 'GLOBAL\n\nTAG\n\nWATCH'
+
+    def test_tag_appends_while_watch_replaces(self):
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt
+        tag = {'title': 'grp', 'llm_change_summary': 'TAG', 'llm_change_summary_mode': 'append'}
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'}, tags={'t1': tag})
+        watch = _make_watch(llm_change_summary='WATCH', tags=['t1'])
+        assert get_effective_summary_prompt(watch, ds) == 'WATCH'
+
+    def test_append_mode_with_empty_text_changes_nothing(self):
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'})
+        watch = _make_watch(llm_change_summary='')
+        watch['llm_change_summary_mode'] = 'append'
+        assert get_effective_summary_prompt(watch, ds) == 'GLOBAL'
+
+    def test_missing_mode_key_behaves_as_replace(self):
+        """Watches stored before this feature have no mode key at all."""
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'})
+        watch = _make_watch(llm_change_summary='WATCH')
+        assert 'llm_change_summary_mode' not in watch
+        assert get_effective_summary_prompt(watch, ds) == 'WATCH'
+
+    def test_append_changes_the_cache_key(self):
+        """Toggling the mode must invalidate cached summaries, not silently reuse them."""
+        from changedetectionio.llm.evaluator import get_effective_summary_prompt, compute_summary_cache_key
+        ds = _make_datastore(llm_cfg={'change_summary_default': 'GLOBAL'})
+
+        replacing = _make_watch(llm_change_summary='WATCH')
+        appending = _make_watch(llm_change_summary='WATCH')
+        appending['llm_change_summary_mode'] = 'append'
+
+        key_replace = compute_summary_cache_key('diff', get_effective_summary_prompt(replacing, ds))
+        key_append = compute_summary_cache_key('diff', get_effective_summary_prompt(appending, ds))
+        assert key_replace != key_append

changedetectionio/tests/test_llm_change_summary.py

@@ -319,6 +319,99 @@ def test_watch_prompt_overrides_tag_and_global(
     delete_all_watches(client)
 
 
+def test_append_mode_saved_via_edit_form_and_applied(
+        client, live_server, measure_memory_usage, datastore_path):
+    """
+    Choosing "add to the end of the inherited prompt" in the watch edit form persists,
+    and the watch's text is then appended to the global default rather than replacing it.
+    Re #4251.
+    """
+    from changedetectionio.llm.evaluator import get_effective_summary_prompt
+
+    _set_response(datastore_path, HTML_V1)
+    _configure_llm(client)
+    ds = client.application.config.get('DATASTORE')
+    _set_global_default(ds, 'Global: summarise as one sentence.')
+
+    test_url = url_for('test_endpoint', _external=True)
+    uuid = ds.add_watch(url=test_url)
+
+    res = client.post(
+        url_for("ui.ui_edit.edit_page", uuid=uuid),
+        data={
+            "url": test_url,
+            "fetch_backend": "html_requests",
+            "time_between_check_use_default": "y",
+            "llm_change_summary": "Also flag anything mentioning a recall.",
+            "llm_change_summary_mode": "append",
+        },
+        follow_redirects=True,
+    )
+    assert b"Updated watch." in res.data
+
+    watch = ds.data['watching'][uuid]
+    assert watch.get('llm_change_summary_mode') == 'append'
+    assert get_effective_summary_prompt(watch, ds) == (
+        'Global: summarise as one sentence.\n\nAlso flag anything mentioning a recall.'
+    )
+
+    delete_all_watches(client)
+
+
+def test_edit_form_defaults_to_replace_preserving_old_behaviour(
+        client, live_server, measure_memory_usage, datastore_path):
+    """
+    A form submitted without the mode field (the pre-#4251 shape) must still replace,
+    so upgrading does not silently change what existing watches send to the LLM.
+    """
+    from changedetectionio.llm.evaluator import get_effective_summary_prompt
+
+    _set_response(datastore_path, HTML_V1)
+    _configure_llm(client)
+    ds = client.application.config.get('DATASTORE')
+    _set_global_default(ds, 'Global: summarise as one sentence.')
+
+    test_url = url_for('test_endpoint', _external=True)
+    uuid = ds.add_watch(url=test_url)
+
+    res = client.post(
+        url_for("ui.ui_edit.edit_page", uuid=uuid),
+        data={
+            "url": test_url,
+            "fetch_backend": "html_requests",
+            "time_between_check_use_default": "y",
+            "llm_change_summary": "Only tell me the new price.",
+        },
+        follow_redirects=True,
+    )
+    assert b"Updated watch." in res.data
+
+    watch = ds.data['watching'][uuid]
+    assert get_effective_summary_prompt(watch, ds) == 'Only tell me the new price.'
+
+    delete_all_watches(client)
+
+
+def test_edit_page_renders_the_prompt_mode_radio(
+        client, live_server, measure_memory_usage, datastore_path):
+    """Both radio options must be present on the watch edit page."""
+    _set_response(datastore_path, HTML_V1)
+    _configure_llm(client)
+    ds = client.application.config.get('DATASTORE')
+
+    test_url = url_for('test_endpoint', _external=True)
+    uuid = ds.add_watch(url=test_url)
+
+    res = client.get(url_for("ui.ui_edit.edit_page", uuid=uuid))
+    body = res.data.decode('utf-8', errors='replace')
+
+    assert 'name="llm_change_summary_mode"' in body
+    assert 'value="replace"' in body
+    assert 'value="append"' in body
+
+    delete_all_watches(client)
+
+
 def test_hardcoded_fallback_when_nothing_set(
         client, live_server, measure_memory_usage, datastore_path):
     """