~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
ChatContextManager - Custom context building for multi-turn conversations.
This is DIFFERENT from FollowUpResearchService (single parent-child context).
Multi-turn chat requires:
- Rolling window of recent messages
- Accumulated findings across conversation
- Source deduplication across turns
- Context summarization for long conversations
"""
from typing import Dict, Any, List, Optional
from operator import index
from loguru import logger
from .citation_stripping import strip_prior_turn_citations
from ..config.thread_settings import get_setting_from_snapshot
# Recognized prior-turn citation markers are stripped from ASSISTANT-authored text
# only — see ``_build_conversation_text`` — because they index that turn's
# source list and dangle once the follow-up renumbers citations against
# its own sources. The stripping engine — grounded in CitationFormatter's
# emission shapes, segmenting fenced blocks / inline code spans / prose and
# scanning prose with bounded citation lookups — lives in
# ``chat.citation_stripping`` and is documented there.
def _strip_or_passthrough(text: str) -> str:
"""Strip citation markers, failing safe to the unstripped text.
Stripping is a context-quality cleanup; an unexpected error in it must
not fail every later follow-up in the session, so it is logged and the
text is carried over as-is.
"""
try:
return strip_prior_turn_citations(text)
except Exception:
logger.opt(exception=True).warning(
"Citation stripping failed; carrying prior-turn text unstripped"
)
return text
class ChatContextManager:
"""
Build context from multi-turn conversation history.
Handles: rolling window, summarization, context accumulation.
Different from follow-up: accumulates from MULTIPLE previous turns.
"""
MAX_FINDINGS_TO_INCLUDE = 5 # Recent findings to include
# Limits for the query-focused conversation summary that becomes the
# follow-up prompt's "previous findings" block.
CONTEXT_SUMMARY_MAX_SENTENCES = 8
CONTEXT_SUMMARY_MAX_CHARS = 2000
# Transcript char budget kept below BaseSummarizer.INPUT_TRUNCATE_CHARS
# (8000) so the summarizer's own truncation never has to drop the most
# recent turns — we trim oldest-first ourselves below.
CONTEXT_INPUT_CHAR_BUDGET = 7500
# Default for the chat.followup_context_mode setting (summary | raw |
# full | none) — what prior context a follow-up turn receives.
DEFAULT_FOLLOWUP_CONTEXT_MODE = "summary"
def __init__(
self,
session_id: str,
messages: List[Dict[str, Any]],
accumulated_context: Optional[Dict[str, Any]] = None,
settings_snapshot: Optional[Dict[str, Any]] = None,
):
"""
Initialize context manager.
Args:
session_id: Chat session ID
messages: List of message dictionaries with role, content, etc.
accumulated_context: Previously accumulated context from session
settings_snapshot: Optional settings to override class-level defaults
"""
self.session_id = session_id
# chat_messages no longer contains step rows (they live in
# chat_progress_steps), but get_session_messages MERGES both for
# client rendering. Filter out steps + non-dict entries here so
# accumulated context only reflects durable conversation turns.
self.messages = [
msg
for msg in (messages or [])
if isinstance(msg, dict) and msg.get("message_type") != "step"
]
# The persisted JSON value is passed in unvalidated. Corruption or a
# legacy writer can leave a truthy non-dict (7, "abc", [1]) that a
# bare `or {}` would let through, so treat any non-dict as empty.
if isinstance(accumulated_context, dict):
self.accumulated_context = accumulated_context
else:
if accumulated_context:
logger.warning(
"Ignoring non-dict accumulated_context (type={})",
type(accumulated_context).__name__,
)
self.accumulated_context = {}
# Used by build_research_context to construct the LLM that produces
# the query-focused conversation summary.
self.settings_snapshot = settings_snapshot
# Override class defaults from settings if provided.
# Note: settings_snapshot is the 4th keyword arg; passing it positionally
# would bind it to the unused `username` param, silently using defaults.
if settings_snapshot:
self.MAX_FINDINGS_TO_INCLUDE = get_setting_from_snapshot(
"chat.max_findings_to_include",
self.MAX_FINDINGS_TO_INCLUDE,
settings_snapshot=settings_snapshot,
)
def build_research_context(self, current_query: str = "") -> Dict[str, Any]:
"""
Build context for the next research query.
Args:
current_query: The user's new message. On a follow-up turn it is
used to focus a summary of the whole prior conversation, which
becomes the follow-up prompt's "previous findings". On the
first turn there is no prior work to summarize.
Returns dict with:
- session_id: Current session
- original_query: The session's first user message
- accumulated_findings / past_findings: Prior work for the follow-up
(query-focused summary on follow-ups; empty on the first turn)
- key_entities: Important entities mentioned
- topics: Topics discussed
- is_multi_turn: Whether this is a follow-up
"""
# The follow-up strategy reads "original_query" to anchor the prompt on
# the topic that started the conversation; without it the contextual
# follow-up loses the original question. Use the session's first user
# message as that anchor.
original_query = next(
(
m.get("content", "")
for m in self.messages
if isinstance(m, dict) and m.get("role") == "user"
),
"",
)
is_multi_turn = any(
isinstance(m, dict) and m.get("role") == "assistant"
for m in self.messages
)
# Stripping is scoped per-mode inside _select_prior_findings — e.g.
# "full" mode strips assistant turns only, as it assembles them, and
# must not have a second, role-blind strip pass applied to the
# already-mixed-role transcript here (that would delete a markdown
# link the USER typed in an earlier turn; see _build_conversation_text).
findings = self._select_prior_findings(current_query, is_multi_turn)
return {
"session_id": self.session_id,
"original_query": original_query,
"accumulated_findings": findings,
"past_findings": findings, # Research engine expects this key
"key_entities": self._get_key_entities(),
"topics": self._get_topics(),
"is_multi_turn": is_multi_turn,
"turn_count": len(self.messages),
}
def _select_prior_findings(
self, current_query: str, is_multi_turn: bool
) -> str:
"""Pick the follow-up's "previous findings" per chat.followup_context_mode.
Modes:
- ``summary`` (default): query-focused LLM summary of the conversation
- ``raw``: recent research findings, truncated
- ``full``: the entire conversation transcript
- ``none``: no prior findings
Only follow-up turns carry prior work; the first turn returns "".
"""
if not is_multi_turn:
return ""
mode = self.DEFAULT_FOLLOWUP_CONTEXT_MODE
if self.settings_snapshot:
mode = get_setting_from_snapshot(
"chat.followup_context_mode",
mode,
settings_snapshot=self.settings_snapshot,
)
if mode == "none":
findings = ""
elif mode == "raw":
# _extract_findings_from_history strips each assistant
# message itself — BEFORE truncating it, so a citation
# crossing the truncation cutoff can't leave half a marker
# behind (no pattern matches "[](htt...").
findings = self._extract_findings_from_history()
elif mode == "full":
# _build_conversation_text strips citation markers per-turn,
# assistant lines only, as it assembles the mixed-role
# transcript — a second, role-blind strip pass here would
# delete a markdown link the USER typed in an earlier turn.
findings = self._build_conversation_text()
elif current_query:
# "summary" with a question to focus on. The transcript the
# LLM reads keeps user turns verbatim (assistant turns are
# stripped while it is built), but the summary it returns is
# stripped as a whole, with no knowledge of which turn a span
# came from: a citation-shaped string the user typed — e.g.
# ``[1]`` or ``[arxiv.org](https://arxiv.org/abs/...)`` — is
# removed if the summary repeats it. Ordinary links survive.
findings = self._summarize_prior_work(current_query)
else:
# "summary" with no question (e.g. a no-arg build_research_context
# call): fall back to raw recent findings (already stripped
# during extraction).
findings = self._extract_findings_from_history()
# Observability: the summary path is otherwise silent (no token-counter
# entry, since get_llm runs without a research_id), so a follow-up's
# prior-context build looked like an unexplained pause. One line per
# follow-up turn records which mode ran and how much context it built.
logger.info(
"Chat follow-up prior context: mode={}, {} chars",
mode,
len(findings),
)
return findings
def _strip_citation_markers(self, text: str) -> str:
"""Remove prior-turn citation markers from carried-over context.
Handles the shapes CitationFormatter stores — markdown hyperlinks
like ``[[1]](url)`` / ``[[arxiv.org-1]](url)`` (plus, for a model
that re-renders one with a single bracket pair, a domain label
naming the link's own host, ``[arxiv.org](https://arxiv.org/...)``;
numeric single-bracket links such as ``[1998](url)`` are kept),
the plain source-tagged form ``[arxiv-1]`` / ``[local-1]`` /
``[ai-2]`` / ``[personal-notes-3]``, plain
``[1]`` / ``[1, 2]``, and lenticular ``【1】`` — including runs of
adjacent markers (comma groups are concatenated with no separator).
See ``chat.citation_stripping`` for the full shape grounding.
Fenced code blocks (CommonMark ``` and ~~~ fences) and inline code
spans are not citation sites and pass through untouched. A stripped
run consumes one flanking horizontal-whitespace separator — the one
before it mid-line or at the end of a line, the one after it at the
start of a line (indentation before it is kept) — so removing
``word [[1]](url) word`` never introduces a doubled space between
the flanking words, and it is horizontal-only, so a marker starting
the next line never joins two lines. If stripping raises, the error
is logged and the text is carried over unstripped. There is
deliberately no separate whitespace-collapse pass over the rest of
the string:
a blanket ``[ \\t]{2,}`` collapse would also flatten unrelated
indentation (code blocks, nested markdown lists, table columns)
that never had a citation marker anywhere near it.
"""
if not text:
return text
return _strip_or_passthrough(text)
def _build_conversation_text(self) -> str:
"""Render the prior conversation (both roles) as a plain transcript.
Trims oldest-first to ``CONTEXT_INPUT_CHAR_BUDGET`` so the most recent
turns survive and the summarizer's input cap never has to truncate.
Citation markers are stripped from ASSISTANT lines only, per turn,
before assembly — never from the joined transcript. Those markers
index the prior turn's own source list and dangle once renumbered
against the follow-up's freshly-found sources, but a citation-shaped
string a USER typed (e.g. a markdown link they pasted) is verbatim
user content and must reach the follow-up prompt untouched.
"""
lines: List[str] = []
used = 0
for msg in reversed(self.messages):
if not isinstance(msg, dict):
continue
content = msg.get("content") or ""
if not content.strip():
continue
role_raw = msg.get("role") or "unknown"
if role_raw == "assistant":
# Strip citation markers BEFORE the outer trim: trimming
# first would dedent a leading indented-code line into
# prose, and its bracket literals would be deleted as
# citations (raw mode never trims, so modes diverged).
content = self._strip_citation_markers(content)
content = content.strip()
role = role_raw.capitalize()
line = f"{role}: {content}"
remaining = self.CONTEXT_INPUT_CHAR_BUDGET - used
if remaining <= 0:
break
if len(line) > remaining:
if lines:
# Budget already spent on more recent turns — stop rather
# than partially including an older one.
break
# The most recent turn alone exceeds the budget: keep its head
# so the transcript still fits the summarizer's input cap.
line = line[:remaining]
lines.append(line)
used += len(line)
lines.reverse()
return "\n\n".join(lines)
def _summarize_prior_work(self, current_query: str) -> str:
"""Summarize the prior conversation, focused on ``current_query``.
Returns an empty string when there is no prior conversation, the LLM
cannot be constructed (e.g. a misconfigured provider), or the LLM call
itself fails. The summary is additive context, so a failure here must
not crash the follow-up request — the research dispatch that follows
surfaces a genuinely-broken LLM through its own error handling.
"""
transcript = self._build_conversation_text()
if not transcript:
return ""
from ..config.llm_config import get_llm
from ..advanced_search_system.summarization import FocusedSummarizer
try:
llm = get_llm(settings_snapshot=self.settings_snapshot)
except Exception:
logger.opt(exception=True).debug(
"Could not build LLM for chat context summary; skipping"
)
return ""
class ChatContextSummarizer(FocusedSummarizer):
def _truncate(self, summary: str) -> str:
# Strip citations before the output cap, so a marker
# straddling the cap is removed whole instead of being cut
# into residue no pattern matches ("[[1]](https://exa...").
# The summary arrives already trimmed (ProcessingLLMWrapper
# and BaseSummarizer.summarize both strip it), so a leading
# indented-code line in it reads as prose here.
return super()._truncate(_strip_or_passthrough(summary).strip())
return ChatContextSummarizer(
llm,
focus_query=current_query,
max_sentences=self.CONTEXT_SUMMARY_MAX_SENTENCES,
max_chars=self.CONTEXT_SUMMARY_MAX_CHARS,
).summarize(transcript)
def _extract_findings_from_history(self) -> str:
"""
Extract key findings from assistant messages with research.
Returns combined findings text, limited in length.
"""
limit = index(self.MAX_FINDINGS_TO_INCLUDE)
if limit > 0:
selected = []
for msg in reversed(self.messages):
if msg.get("role") == "assistant" and msg.get("research_id"):
selected.append(msg)
if len(selected) == limit:
break
selected.reverse()
else:
# Preserve the historical [-0:] and negative-window behavior.
selected = [
msg
for msg in self.messages
if msg.get("role") == "assistant" and msg.get("research_id")
][-limit:]
findings = []
for msg in selected:
# Strip BEFORE truncating, but only for findings that survive
# the window. Discarded history needs neither parsing nor copies.
content = self._strip_citation_markers(msg.get("content") or "")
if len(content) > 500:
break_point = content.find("\n\n", 300)
if break_point == -1 or break_point > 600:
break_point = 500
content = content[:break_point] + "..."
findings.append(content)
return "\n\n---\n\n".join(findings)
def _get_key_entities(self) -> List[str]:
"""Get key entities from accumulated context."""
entities = self.accumulated_context.get("key_entities", [])
return entities[:20] if isinstance(entities, list) else []
def _get_topics(self) -> List[str]:
"""Get topics from accumulated context."""
topics = self.accumulated_context.get("topics", [])
return topics[:10] if isinstance(topics, list) else []
def extract_context_updates(self, new_content: str) -> Dict[str, Any]:
"""
Extract context updates from a new research response.
Args:
new_content: New assistant response content
Returns:
Dict with entity, topic, and summary updates.
"""
return {
"new_entities": [], # Could be enhanced with NLP entity extraction
"new_topics": [], # Could be enhanced with NLP topic modeling
"summary_addition": self._create_summary(new_content),
}
def _create_summary(self, content: str) -> str:
"""
Create a brief summary of content for context accumulation.
Returns first meaningful paragraph or truncated content.
"""
if not content:
return ""
# Try to get first paragraph
paragraphs = content.split("\n\n")
for para in paragraphs:
para = para.strip()
# Skip headers and very short paragraphs
if para and len(para) > 50 and not para.startswith("#"):
if len(para) > 300:
return para[:300] + "..."
return para
# Fallback: just truncate
if len(content) > 300:
return content[:300] + "..."
return content