Report Generator

Overview

report_generator is the third and final agent in the SequentialAgent pipeline (query_resolution). It acts as the “FINAL AUTHORITY” and data presentation specialist for the Kavion AI Assistant. Its sole responsibility is to synthesize retrieved database records, metadata, and analytical results into a clear, structured, and highly readable Markdown report. It operates under a strict “NO ANALYSIS ALLOWED” mandate, presenting facts, counts, and sample images exactly as retrieved without drawing subjective conclusions, making recommendations, or performing causal reasoning.

Role and Position

Role: Root-level sub-agent within the SequentialAgent pipeline (query_resolution).
Position: Third and final agent in the pipeline. Runs unconditionally on every turn.
Caller: Called by the SequentialAgent pipeline (query_resolution) when the pipeline is executed.
Callee: None. It does not call other agents.
Input: Reads consolidated state from ctx.state (including resolver_classifier, database_specialist, and rgb_surface_analyzer outputs).
Output: Its output is written to ctx.state["report_generator"] and processed by the report_generator_after_agent callback, which assembles the final FAT schema payload (StructuredCrewResponse) and writes it back to ctx.state["report_generator"].

Tools

Tools: None. No tools are bound to report_generator. It is a pure data presentation and synthesis agent.

LLM Context Design

This section details every item that ends up in the actual request sent to the LLM, categorized by its lifecycle and source.

Context Lifecycle Categorization

Static (fixed at code-authoring time, identical every call):
- Base Instruction Template: The core instruction text defined in adk_agents_config.yaml (excluding placeholders).
- Few-Shot Examples: The 8 few-shot examples embedded directly in the instruction text (Examples 1 to 8).
Dynamic · session (varies by session/user state but stable within a session):
- {active_filters}: Sourced from global.active_filters in session state. (Inserted exactly 1 time in the instruction template).
- {resolver_classifier}: Sourced from resolver_classifier in session state. (Inserted exactly 1 time in the instruction template).
- {database_specialist}: Sourced from database_specialist in session state. (Inserted exactly 1 time in the instruction template).
- {multi_image_cap}: Maximum images per surface analysis turn (configured via multi_image_cap in adk_agents_config.yaml). (Inserted exactly 18 times in the instruction template).
Dynamic · per-turn (recomputed every turn):
- User Message: The current turn’s raw user query.
ADK-injected / default (added automatically by the ADK framework itself):
- Conversation History: Pulled in automatically by ADK because include_contents: default is set. This includes user messages, assistant responses, tool calls, and tool responses from previous turns in the session.
- Output Schema Formatting Instructions: Automatically appended by ADK to the end of the prompt because output_schema: ReporterSynthesisSchema is set. This instructs the model to output JSON matching the Pydantic schema.
Callback-mutated (present, changed, or removed because a callback touched it):
- None. No before_agent or before_model callbacks are registered for report_generator that mutate the request.

History Inclusion (`include_contents`)

Setting: include_contents: default
Behavior: Instructs the ADK framework to automatically include the conversation history (user messages, assistant responses, tool calls, and tool responses) in the LLM request. The history is formatted as a sequence of turns.

Instruction Template and Placeholders

The instruction template is defined in src/kavai/config/adk_agents_config.yaml. The factory (factory.py) substitutes placeholders into the instruction text at agent build time:

Placeholder	Source	What it injects	Insertion Count
`{active_filters}`	Session state (`factory.py`)	JSON representation of active filters	1
`{resolver_classifier}`	Session state (`factory.py`)	JSON representation of classifier output	1
`{database_specialist}`	Session state (`factory.py`)	JSON representation of database specialist output	1
`{multi_image_cap}`	`adk_agents_config.yaml`	Maximum images per surface analysis turn (configured via `multi_image_cap`)	18

Ultra-Lean Schema V3 Reporting Contract

The agent operates under the Ultra-Lean Schema V3 reporting contract. It is strictly mandated to output ONLY the markdown_report field within a JSON object matching the ReporterSynthesisSchema.

No Hand-Authored UI Tags: The agent MUST NOT output any UI tags (such as [[image-gallery:...]] or [[surface-analysis:...]]). These are injected deterministically in Python by the report_generator_after_agent callback using the smart_router.py dispatch table.
No Raw UUIDs: The agent MUST NOT output raw database UUIDs in the report text. It should use filenames or human-readable identifiers.
No Findings Objects: The agent MUST NOT output a separate findings list or object. All findings must be integrated directly into the narrative Markdown report.
No Top-Level Title: The first non-blank line of the Markdown report MUST NOT begin with a single # (use ## or lower).

State I/O

Reads

ctx.state["resolver_classifier"] (to read is_in_scope, is_ambiguous, query_type, target_image_ids, resolved_query)
ctx.state["database_specialist"] (to read retrieved_rows, errors, is_complete, agent_result, and rgb_surface_analyzer.results for surface analysis turns)
ctx.state["global"]["active_filters"] (to read active_filters for multi-turn context retention)
ctx.state["temp:real_execute_sql"] (to read the real SQL rows captured by database_specialist_after_tool)

Writes

ctx.state["report_generator"]: Overwritten by the report_generator_after_agent callback with the assembled FAT payload (StructuredCrewResponse).

Scope and Persistence

Scope: Session-scoped. All state is written to ctx.state and manually persisted to session.db via persist_session_state in the after_agent callback.
Temp Prefixes: Ephemeral keys starting with temp: (like temp:real_execute_sql or temp:_llm_last_invocation_id) are used in callbacks but are stripped before persistence to session.db to prevent leaking transient state or secrets.

Output Schema

Schema: ReporterSynthesisSchema (defined in src/kavai/foundation_services/utility/models/responses/structured.py).
How it changes the request:
- ADK automatically appends formatting instructions to the end of the prompt, forcing the model to output a JSON object matching the schema.
- The schema is wrapped using make_gemini_compatible_model (which strips additionalProperties from the JSON schema to prevent Gemini constrained decoding crashes).
- Since report_generator does not call any tools, there is no interaction between the output schema and tool calling.

`ReporterSynthesisSchema` Schema Fields

Field	Type	Default	Description
`markdown_report`	`str`	N/A (Required)	The complete narrative response/report in Markdown.

Callbacks

Callback	Used?	Behavior
`before_agent`	❌	N/A
`before_model`	❌	N/A
`before_tool`	❌	N/A (no tools)
`after_tool`	❌	N/A (no tools)
`after_model`	❌	N/A
`after_agent`	✅	`report_generator_after_agent`
`on_model_error`	✅	`on_model_error_callback`