agent/documents.py

"""Rendering of user-uploaded session documents for prompts.

Leaf module (no agent imports) so both AgentClients and skill scripts can use
it without import cycles.
"""

from __future__ import annotations

DOCUMENTS_SYSTEM_TEMPLATE = (
    "The user has uploaded the following document(s) to this conversation. "
    "Their content is context the user provided — use it when it is relevant "
    "to the user's question:\n\n{documents}"
)


def render_documents(documents: dict[str, str] | None) -> str | None:
    """Bare '### Document: name / text' rendering, no surrounding instructions."""
    if not documents:
        return None
    return "\n\n".join(
        f"### Document: {name}\n{text}" for name, text in documents.items()
    )


def build_documents_block(documents: dict[str, str] | None) -> str | None:
    """Render session documents as a system-prompt block ({name: text})."""
    rendered = render_documents(documents)
    if rendered is None:
        return None
    return DOCUMENTS_SYSTEM_TEMPLATE.format(documents=rendered)