124 lines
4.8 KiB
Python
124 lines
4.8 KiB
Python
"""Document summarizer (phase 30, task 03).
|
|
|
|
Builds the ``SUMMARY_MODE`` prompt for one document, calls the aipi
|
|
``lite`` model through the one-shot ``LLMClient.chat`` (phase 30,
|
|
task 01), and returns the validated summary text with a
|
|
**code-deterministic** pointer line back to the source::
|
|
|
|
Source: <source>/<path>
|
|
|
|
The pointer is appended by this module, never model-generated — the
|
|
model is told what to summarize, not to cite.
|
|
|
|
Quality contracts enforced here:
|
|
|
|
* **Capped input** — the document content is cut at
|
|
``BOR_SUMMARY_MAX_CHARS`` (default 12 000) before the single model
|
|
call; overflow is cut exactly at the cap and the shared
|
|
``TRUNCATION_MARKER`` (``[…truncated…]``) is appended, so the model
|
|
never sees more than the cap and the cut is visible.
|
|
* **No silent summaries** — a reply that is empty after trimming raises
|
|
:class:`LLMError` (the client already rejects empty content; the
|
|
summarizer re-asserts defensively and never hands the importer a
|
|
pointer-only row).
|
|
|
|
The ``SUMMARY_MODE`` marker follows the ``DEFLECT_MODE`` convention:
|
|
the deterministic E2E mock LLM keys on it in the system prompt
|
|
(``tests/e2e/mock_llm.py`` — wired in task 06).
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
from typing import Protocol
|
|
|
|
from app.config import Settings, get_settings
|
|
from app.rag.llm import LLMError
|
|
from app.rag.retriever import TRUNCATION_MARKER
|
|
|
|
#: System-prompt marker for summary generation — the E2E mock LLM keys on
|
|
#: it (same convention as ``DEFLECT_MODE``, PLAN §6).
|
|
SUMMARY_MODE = "SUMMARY_MODE"
|
|
|
|
#: Locked instruction for the ``lite`` model (phase 30): the summary is a
|
|
#: natural-language retrieval target, so it must be plain, concrete, and
|
|
#: strictly grounded in the document.
|
|
SUMMARY_INSTRUCTION = (
|
|
"Write a 3-6 sentence plain-text summary of this document in natural "
|
|
"language. Cover what it configures/defines and its most important "
|
|
"values. Do not use markdown. Do not invent anything that is not in "
|
|
"the document."
|
|
)
|
|
|
|
#: Full system prompt: marker first (the mock's key), then the instruction.
|
|
SYSTEM_PROMPT = f"{SUMMARY_MODE}: {SUMMARY_INSTRUCTION}"
|
|
|
|
|
|
class SummaryLLM(Protocol):
|
|
"""The one-shot chat surface the summarizer needs.
|
|
|
|
:class:`app.rag.llm.LLMClient` satisfies it; unit tests pass a
|
|
duck-typed fake (``chat`` + ``settings``) instead — same pattern as
|
|
the importer's ``Embedder`` protocol.
|
|
"""
|
|
|
|
settings: Settings
|
|
|
|
async def chat(
|
|
self, messages: list[dict[str, str]], model: str | None = None
|
|
) -> str: ...
|
|
|
|
|
|
def _capped_content(content: str, max_chars: int | None) -> str:
|
|
"""Document content for the user message, capped at *max_chars*.
|
|
|
|
The default cap is ``BOR_SUMMARY_MAX_CHARS``. Overflow is cut exactly
|
|
at the cap and the shared ``TRUNCATION_MARKER`` is appended on its
|
|
own line; content that fits (length ≤ cap) passes through unchanged.
|
|
"""
|
|
limit = max_chars if max_chars is not None else get_settings().summary_max_chars
|
|
if len(content) <= limit:
|
|
return content
|
|
return content[:limit] + "\n" + TRUNCATION_MARKER
|
|
|
|
|
|
def build_summary_prompt(
|
|
source: str, path: str, content: str, max_chars: int | None = None
|
|
) -> tuple[str, str]:
|
|
"""The ``(system, user)`` message pair for one summary call.
|
|
|
|
* ``system`` — :data:`SYSTEM_PROMPT`: the ``SUMMARY_MODE`` marker +
|
|
the locked instruction.
|
|
* ``user`` — the document content, capped (see :func:`_capped_content`).
|
|
|
|
*source* and *path* are part of the signature so the call site reads
|
|
like the document it summarizes (and for :func:`generate_summary`'s
|
|
pointer) — the pointer is built in code and deliberately **not** part
|
|
of the prompt, so the model cannot echo or mangle it.
|
|
"""
|
|
return SYSTEM_PROMPT, _capped_content(content, max_chars)
|
|
|
|
|
|
async def generate_summary(
|
|
llm: SummaryLLM, *, source: str, path: str, content: str
|
|
) -> str:
|
|
"""One-shot ``lite`` summary of *content*, ending in the pointer line.
|
|
|
|
Returns the model's text (trimmed) plus the deterministic
|
|
``Source: <source>/<path>`` line — the pointer is appended by code,
|
|
never model-generated. Raises :class:`LLMError` when the model
|
|
returns nothing usable after trimming, and propagates any
|
|
:class:`LLMError` the client raises (the importer's fail-soft path
|
|
turns that into a logged, counted ``summary_errors`` entry).
|
|
"""
|
|
system, user = build_summary_prompt(source, path, content)
|
|
raw = await llm.chat(
|
|
[{"role": "system", "content": system}, {"role": "user", "content": user}],
|
|
model=llm.settings.llm_summary_model,
|
|
)
|
|
summary = raw.strip()
|
|
if not summary:
|
|
raise LLMError(
|
|
f"summary model returned empty content for {source}/{path} — "
|
|
"refusing to store a silent summary"
|
|
)
|
|
return f"{summary}\nSource: {source}/{path}"
|