LCORE-1570: utils/compaction: additive summarize_chunk + Red Hat prompt

Add the additive summarization primitive of compaction (spike
decision 2). One call to summarize_chunk produces one
ConversationSummary; the caller accumulates them. The function does
not mutate the conversation, does not write to the cache, does not
acquire any lock — those side effects live in LCORE-1571 / 1572.

SUMMARIZATION_PROMPT is a module constant carrying the five
preservation directives required by the spec doc and the JIRA AC
(user question + environment; errors + commands + outcomes;
decisions + rationale; resolved vs open; user-vs-assistant
attribution). It is scoped to Red Hat product support so the LLM
keeps the operator-relevant signal that a generic summarizer
typically prunes. Exposing it as a constant lets tests assert
directive presence and centralizes future tuning.

summarize_chunk takes summarized_through_turn from the caller
rather than deriving it from old_items alone — additive compaction
spans multiple invocations whose chunk boundaries do not start at
zero, and the running total is the caller's bookkeeping.

The function uses store=False on the responses.create call. The
summarization request is a one-shot; its output is not stored as a
conversation item by Llama Stack. Injecting the produced summary
into the user's conversation under some marker scheme is LCORE-1572's
responsibility — this module just produces the value.

A LLM call that returns no extractable text raises ValueError
rather than constructing an empty ConversationSummary. The
PositiveInt token_count would refuse a zero-token summary anyway,
and a useless context wrapper is worse than a clear error.

Tests cover:
* All five JIRA-required preservation directives present in the
  prompt constant.
* Prompt body construction concatenates prompt and transcript.
* Happy path: ConversationSummary is fully populated; token_count
  is positive; model_used is preserved; created_at is non-empty.
* The LLM call uses store=False and stream=False.
* Empty LLM response raises ValueError.
* Additive AC ("second compaction appends a new summary chunk,
  does not re-summarize the first"): two sequential calls produce
  two independent records and the second call's prompt does not
  include the first chunk.

Tests for partition_conversation now also run alongside the new
ones in the same module.

Author: max-svistunov

src/utils/compaction.py

@@ -13,7 +13,6 @@
 * ``summarize_chunk`` — call the LLM once to summarize a chunk of items
   and return a :class:`ConversationSummary`. This is the *additive*
   primitive of decision 2: each chunk is summarized once and kept.
-  Lives in a later commit.
 
 * ``recursively_resummarize`` — fall back to a single-summary collapse
   when the cumulative size of existing summaries itself approaches the
@@ -28,8 +27,37 @@
 to disentangle a tangle of side effects.
 """
 
+from datetime import datetime, timezone
 from typing import Any
 
+from llama_stack_client import AsyncLlamaStackClient
+
+from log import get_logger
+from models.compaction import ConversationSummary
+
+logger = get_logger(__name__)
+
+
+SUMMARIZATION_PROMPT = (
+    "Summarize this conversation history for an AI assistant that helps with\n"
+    "Red Hat product support. Preserve:\n"
+    "1. The user's original question and environment details.\n"
+    "2. All error messages, commands run, and their outcomes.\n"
+    "3. Key decisions and their rationale.\n"
+    "4. What was resolved and what remains open.\n"
+    "5. Clear attribution (what the user reported vs what the assistant"
+    " suggested).\n"
+    "\n"
+    "Be concise but complete. The assistant will use this summary as its only\n"
+    "memory of older conversation turns.\n"
+)
+"""Domain-specific summarization prompt.
+
+Includes the five preservation directives required by the spec doc and
+the JIRA acceptance criteria. Exposed as a module constant so tests can
+assert directive presence and so future tuning is visible in one place.
+"""
+
 
 def is_message_item(item: Any) -> bool:
     """Return True when *item* is a chat-message-shaped conversation item.
@@ -194,3 +222,135 @@ def partition_conversation(
     # the buffer-fully-degraded branch so the function has a single
     # well-defined behavior in every reachable state.
     return items, []
+
+
+def _build_summarization_prompt_body(items: list[Any]) -> str:
+    """Render the full prompt body sent to the summarization LLM call.
+
+    Concatenates the system-style summarization prompt with a
+    ``role: text``-formatted transcript of the items being summarized.
+
+    Parameters:
+        items: The chunk to summarize.
+
+    Returns:
+        Full prompt body string.
+    """
+    transcript = format_conversation_for_summary(items)
+    return f"{SUMMARIZATION_PROMPT}\nConversation:\n{transcript}"
+
+
+def _extract_response_text(response: Any) -> str:
+    """Pull the human-readable text out of a Responses-API result.
+
+    Walks ``response.output`` and concatenates the ``.text`` field of
+    every content part that has one. Mirrors the shape-handling done
+    by :func:`utils.responses.extract_text_from_response_items` but is
+    kept local here so the compaction module does not depend on the
+    response-handling utility module that LCORE-1572 will eventually
+    integrate with.
+
+    Parameters:
+        response: The result of ``client.responses.create``.
+
+    Returns:
+        Concatenated response text, or the empty string when nothing
+        could be extracted.
+    """
+    parts: list[str] = []
+    output = getattr(response, "output", None) or []
+    for output_item in output:
+        content = getattr(output_item, "content", None)
+        if not content:
+            continue
+        for content_part in content:
+            text = getattr(content_part, "text", None)
+            if text:
+                parts.append(text)
+    return "".join(parts)
+
+
+async def summarize_chunk(
+    client: AsyncLlamaStackClient,
+    model: str,
+    old_items: list[Any],
+    summarized_through_turn: int,
+    encoding_name: str,
+) -> ConversationSummary:
+    """Summarize *old_items* via one LLM call and return a ConversationSummary.
+
+    This is the additive primitive of compaction decision 2. The
+    function:
+
+    1. Renders the summarization prompt against the transcript of
+       *old_items*.
+    2. Calls ``client.responses.create`` once with ``store=False`` (the
+       summarization call is a one-shot — its output is not stored as
+       a conversation item by Llama Stack; the caller in LCORE-1572 is
+       responsible for injecting the summary into the conversation
+       under whatever marker scheme it chooses).
+    3. Wraps the resulting text in a :class:`ConversationSummary` with
+       a freshly-computed token count and a UTC ISO 8601 timestamp.
+
+    The function does **not** mutate the caller's conversation, does
+    not write to the cache, does not acquire any lock. Concurrency
+    control and persistence belong to LCORE-1572 / LCORE-1571.
+
+    Parameters:
+        client: Llama Stack client to call.
+        model: Fully-qualified model identifier (e.g.,
+            ``"openai/gpt-4o-mini"``). The spec mandates the same
+            model as the user's query (spike decision 3); the choice
+            is the caller's, this function only records it.
+        old_items: Conversation items to summarize. Non-message items
+            are filtered out by the transcript renderer.
+        summarized_through_turn: Running total of items the caller has
+            already summarized at the moment this chunk completes —
+            this value is stored on the returned ConversationSummary
+            so the caller can advance the partition boundary on the
+            next compaction. Caller-tracked; not derived from
+            ``old_items`` alone because additive compaction can span
+            multiple invocations whose chunk boundaries do not start
+            at zero.
+        encoding_name: Tiktoken encoding name used to count tokens in
+            the produced summary. Should match the encoding used to
+            decide the compaction trigger.
+
+    Returns:
+        A populated ConversationSummary.
+
+    Raises:
+        ValueError: When the LLM call returns no extractable text and
+            the resulting summary would be empty. A zero-token summary
+            cannot be persisted (PositiveInt) and is also useless as
+            context, so propagating an error is the honest behavior.
+    """
+    from utils.token_estimator import estimate_tokens
+
+    prompt = _build_summarization_prompt_body(old_items)
+    logger.info(
+        "Summarizing %d conversation items (%d messages) for model %s.",
+        len(old_items),
+        sum(1 for item in old_items if is_message_item(item)),
+        model,
+    )
+    response = await client.responses.create(
+        input=prompt,
+        model=model,
+        stream=False,
+        store=False,
+    )
+    summary_text = _extract_response_text(response).strip()
+    if not summary_text:
+        raise ValueError(
+            "Summarization LLM call returned no extractable text; "
+            "cannot construct ConversationSummary."
+        )
+    token_count = estimate_tokens(summary_text, encoding_name=encoding_name)
+    return ConversationSummary(
+        summary_text=summary_text,
+        summarized_through_turn=summarized_through_turn,
+        token_count=token_count,
+        created_at=datetime.now(timezone.utc).isoformat(),
+        model_used=model,
+    )