# generation/context_assembler.py
# WHY THIS EXISTS: Assembles retrieved chunks into LLM-ready context. LAW 14.
# Rules:
# 1. Sort by reranker score descending
# 2. Source diversity — max 2 chunks per doc_id
# 3. Citation injection: [Source: page X, title]
# 4. Delimiter wrap: ...
# 5. Context budget: 70% chunks / 30% system prompt + query + output
import logging
from dataclasses import dataclass, field
from retrieval.hybrid_retriever import RetrievedChunk
from retrieval.crag_fallback import CRAGResult
logger = logging.getLogger(__name__)
# 70% of context window reserved for retrieved chunks
# Remaining 30% for system prompt + query + output generation
CONTEXT_BUDGET_CHARS = 12_000 # ~3000 tokens at 4 chars/token
MAX_CHUNKS_PER_SOURCE = 2 # Source diversity — LAW 14
DELIMITER_OPEN = ""
DELIMITER_CLOSE = ""
@dataclass
class AssembledContext:
"""Complete assembled context ready for system prompt injection."""
context_text: str # Final string for {context_with_citations}
cited_sources: list[dict] # Source metadata for UI panel
chunk_count: int # Total chunks in context
crag_chunks_included: int # Web search chunks included
budget_used_chars: int # Characters used of budget
budget_total_chars: int = CONTEXT_BUDGET_CHARS
@dataclass
class SourceCitation:
"""Citation metadata for a single source chunk."""
chunk_id: str
title: str
page_number: int
doc_id: str
reranker_score: float
is_crag: bool = False
url: str = ""
def _build_citation_tag(title: str, page_number: int, is_crag: bool = False) -> str:
"""
Builds citation string injected into every chunk.
Format: [Source: page X, Title] or [Web Source: Title]
"""
if is_crag:
return f"[Web Source: {title}]"
return f"[Source: page {page_number}, {title}]"
def _wrap_in_delimiter(chunk_text: str, citation: str) -> str:
"""
Wraps chunk in XML delimiters with citation.
Mandatory — prevents indirect prompt injection. LAW 10 + LAW 14.
"""
return (
f"{DELIMITER_OPEN}\n"
f"{citation}\n"
f"{chunk_text}\n"
f"{DELIMITER_CLOSE}"
)
def assemble_context(
chunks: list[RetrievedChunk],
crag_result: CRAGResult | None = None,
budget_chars: int = CONTEXT_BUDGET_CHARS,
) -> AssembledContext:
"""
Assembles retrieved chunks into context string for Sarvam-30B.
Pipeline:
1. Sort all chunks by reranker_score descending
2. Apply source diversity filter (max 2 per doc_id)
3. Add CRAG web chunks if present (appended after document chunks)
4. Inject citation tag into each chunk
5. Wrap each chunk in delimiters
6. Enforce budget: stop adding chunks when chars exceed budget
7. Return assembled context + source metadata
Args:
chunks: Reranked chunks from FlashRank (top-5)
crag_result: Optional web search results from CRAG fallback
budget_chars: Character budget for context (default: 12,000)
Returns:
AssembledContext with context_text ready for system prompt
"""
# Step 1: Sort by reranker score descending
sorted_chunks = sorted(chunks, key=lambda c: c.reranker_score, reverse=True)
# Step 2: Source diversity filter — max 2 chunks per doc_id
source_counts: dict[str, int] = {}
filtered_chunks: list[RetrievedChunk] = []
for chunk in sorted_chunks:
count = source_counts.get(chunk.doc_id, 0)
if count < MAX_CHUNKS_PER_SOURCE:
filtered_chunks.append(chunk)
source_counts[chunk.doc_id] = count + 1
assembled_parts: list[str] = []
cited_sources: list[dict] = []
chars_used = 0
crag_chunks_included = 0
# Step 3 + 4 + 5 + 6: Process document chunks
for chunk in filtered_chunks:
citation = _build_citation_tag(chunk.title, chunk.page_number, is_crag=False)
wrapped = _wrap_in_delimiter(chunk.chunk_text, citation)
if chars_used + len(wrapped) > budget_chars:
logger.debug(
"Context budget reached — stopping chunk addition",
extra={"chars_used": chars_used, "budget": budget_chars},
)
break
assembled_parts.append(wrapped)
chars_used += len(wrapped)
cited_sources.append({
"chunk_id": chunk.chunk_id,
"title": chunk.title,
"page_number": chunk.page_number,
"doc_id": chunk.doc_id,
"reranker_score": round(chunk.reranker_score, 4),
"is_crag": False,
"url": "",
})
# Step 3 cont: Add CRAG web chunks after document chunks
if crag_result and crag_result.triggered and crag_result.web_chunks:
for web_chunk in crag_result.web_chunks:
citation = _build_citation_tag(
web_chunk.get("title", "Web Source"),
page_number=0,
is_crag=True,
)
wrapped = _wrap_in_delimiter(
web_chunk.get("chunk_text", ""),
citation,
)
if chars_used + len(wrapped) > budget_chars:
break
assembled_parts.append(wrapped)
chars_used += len(wrapped)
crag_chunks_included += 1
cited_sources.append({
"chunk_id": f"crag_{crag_chunks_included}",
"title": web_chunk.get("title", "Web Source"),
"page_number": 0,
"doc_id": "web",
"reranker_score": web_chunk.get("reranker_score", 0.5),
"is_crag": True,
"url": web_chunk.get("url", ""),
})
context_text = "\n\n".join(assembled_parts)
logger.info(
"Context assembled",
extra={
"chunks_in": len(chunks),
"chunks_out": len(filtered_chunks),
"crag_chunks": crag_chunks_included,
"chars_used": chars_used,
"budget": budget_chars,
"sources": len(cited_sources),
},
)
return AssembledContext(
context_text=context_text,
cited_sources=cited_sources,
chunk_count=len(assembled_parts) - crag_chunks_included,
crag_chunks_included=crag_chunks_included,
budget_used_chars=chars_used,
)