report¶

report ¶

Report generation — three-phase pipeline producing professional markdown reports.

phase1_analyze ¶

phase1_analyze(turns: list[dict], topic: str = '') -> dict

Phase 1: Analyze session history and produce a research plan.

Uses the LLM to identify relevant turns, extract key themes, detect knowledge gaps, and generate Tavily search queries. Retries once on JSON parse failure.

Parameters:

Name	Type	Description	Default
`turns`	`list[dict]`	List of turn dictionaries from the session.	required
`topic`	`str`	Optional topic filter. If empty or "all", includes all turns. Otherwise filters turns related to the topic.	`''`

Returns:

Type	Description
`dict`	Dictionary with keys: relevant_turn_indices, report_title,
`dict`	key_themes, knowledge_gaps, search_queries.

Raises:

Type	Description
`RuntimeError`	If the LLM fails to produce valid JSON after 2 attempts.

phase3_synthesize ¶

phase3_synthesize(
    plan: dict,
    filtered_turns: list[dict],
    rag_results: str,
    search_results: str,
    session_id: str,
) -> str

Phase 3: Synthesize a complete political analysis report.

Combines session history, RAG retrieval results, and Tavily web search results into a structured markdown report following a predefined template with executive summary, methodology, situation analysis, research findings, political analysis, strategic recommendations, and references sections.

Parameters:

Name	Type	Description	Default
`plan`	`dict`	Phase 1 analysis result dict with report_title and search_queries.	required
`filtered_turns`	`list[dict]`	Session turns filtered to relevant indices.	required
`rag_results`	`str`	Markdown-formatted RAG retrieval results.	required
`search_results`	`str`	Markdown-formatted Tavily search results.	required
`session_id`	`str`	Session identifier for the references section.	required

Returns:

Type	Description
`str`	Complete markdown report string.

generate_report ¶

generate_report(
    session_turns: list[dict],
    topic: str,
    embedder,
    kb,
    session_id: str = "",
) -> str

Generate a professional political analysis report from a session.

Orchestrates the three-phase pipeline: 1. Phase 1: LLM analyzes session → research plan with search queries. 2. Phase 2: RAG retrieval + Tavily web searches execute in parallel. 3. Phase 3: LLM synthesizes everything into a structured report.

The report is saved to REPORTS_DIR as a timestamped markdown file.

Parameters:

Name	Type	Description	Default
`session_turns`	`list[dict]`	List of turn dictionaries from the session.	required
`topic`	`str`	Optional topic filter for the report scope.	required
`embedder`		Fitted Embedder instance for RAG retrieval.	required
`kb`		KnowledgeBase instance with loaded vectors.	required
`session_id`	`str`	Session identifier for the report references.	`''`

Returns:

Type	Description
`str`	Complete markdown report string. Returns an error message
`str`	string (prefixed with "Error:") if prerequisites are not met.