{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/static/style.css",
"offset": 745,
"limit": 15
} 745→
746→/* ── Charts ────────────────────────────────────────────────────── */
747→
748→.chart-container {
749→ margin: 0.75rem 0;
750→ padding: 1rem;
751→ background: var(--bg-2);
752→ border: 1px solid var(--bg-3);
753→ border-radius: var(--radius-lg);
754→ max-width: 480px;
755→}
756→
757→.chart-container canvas { max-height: 280px; }
758→
759→.chart-data-toggle {max-width: 480px;
max-width: 100%;
The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/static/style.css has been updated successfully.
Now committing everything — the refactor, inline charts, layout changes, and chart width fix.
On branch main Your branch is up to date with 'origin/main'. Changes not staged for commit: modified: app/main.py modified: app/prompts.py deleted: app/tools.py modified: static/style.css Untracked files: app/rendering.py app/sse.py app/tools/ no changes added to commit (use "git add" and/or "git commit -a")
app/main.py | 196 +-------- app/prompts.py | 4 +- app/tools.py | 1275 ------------------------------------------------------ static/style.css | 4 +- 4 files changed, 21 insertions(+), 1458 deletions(-)
f82aaad Add advanced analysis tools, auto-analysis briefing, favicon df41cbb Update README.md - cleaned out outdated 23a4e95 Rearchitect to sandbox agent pattern with UI inspectability
git add app/main.py app/prompts.py app/rendering.py app/sse.py app/tools/ static/style.css && git rm --cached app/tools.py 2>/dev/null; git status --short
rm 'app/tools.py' M app/main.py M app/prompts.py A app/rendering.py A app/sse.py D app/tools.py A app/tools/__init__.py A app/tools/_helpers.py A app/tools/analysis_tools.py A app/tools/data_tools.py A app/tools/knowledge_tools.py A app/tools/presentation_tools.py A app/tools/report_tools.py M static/style.css
git commit -m "$(cat <<'EOF' Refactor: split tools.py into package, extract rendering/SSE, inline charts Split monolithic app/tools.py (1275 lines) into app/tools/ package: _helpers.py — shared EmitFn, tokenize, stopwords, factory helpers data_tools.py — search, sentiment, stats, review lookup analysis_tools.py — segments, themes, anomalies presentation_tools.py — charts, follow-ups knowledge_tools.py — list/read knowledge files report_tools.py — save/get report, scope check __init__.py — assembles all tools into MCP server Extract from app/main.py into focused modules: app/rendering.py — render_message, citations, inline charts app/sse.py — event queues, response events, emit helper Inline chart rendering: agent places [chart:N] markers in text, renderer replaces them with Chart.js canvases at that position. Unplaced charts fall back to appending after text. Charts now full-width within message container. Layout: tool accordion moved to top of message (collapsed by default as audit trail), output zone follows with inline charts and citations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> EOF )"
ok
13 files changed, 1400 insertions(+), 1458 deletions(-)
The agent's intermediate reasoning ("Good — solid foundation. Now let me run targeted sentiment...") gets concatenated into the same string as the final analysis output. The user sees a stream-of-consciousness blob instead of a clean document. Meanwhile, tool calls sit in a separate accordion disconnected from the thinking that triggered them.
Separate the agent's work into two distinct layers:
Timeline — an ordered sequence of thinking steps and tool calls, rendered as a collapsible process log above the output. This is where the user sees how the agent worked: reasoning interleaved with tool activity, in chronological order.
Output — the final clean analysis, rendered as the main message content with inline charts, citations, and follow-ups. No process narration.
The rendered message structure becomes:
[Collapsible timeline: thinking + tool calls interleaved chronologically]
[Clean output with inline charts and citations]
[Follow-up buttons]
app/models.pyReplace the tool_calls: list[ToolCallRecord] field on ChatMessage with a unified timeline:
class TimelineStep(BaseModel):
"""A single step in the agent's work process — either thinking or a tool call."""
type: str # "thinking" or "tool"
# For thinking steps:
text: str = ""
# For tool steps:
tool_name: str = ""
summary: str = ""
inputs: dict[str, Any] = Field(default_factory=dict)
output_summary: dict[str, Any] = Field(default_factory=dict)
Replace tool_calls with timeline: list[TimelineStep] on ChatMessage. Keep backward compat — the tool_calls field can stay as a deprecated alias or just remove it since nothing persists long-term.
app/agent.pyThis is the core change. Instead of accumulating all TextBlocks into one response_text string:
timeline: list[dict] and a chunks: list[str] during the agent runAssistantMessage arrives with a TextBlock, append the text to a current thinking buffer_emit_tool SSE events — use tool_records as the signal), flush the current thinking buffer as a {"type": "thinking", "text": "..."} entry in the timeline, then add the tool record as {"type": "tool", ...}Concrete approach: since tool_records is populated by the tool closures during execution, and TextBlocks arrive via the message stream, track the count of tool_records after each TextBlock. If new tool records appeared since the last TextBlock, that means the previous text was thinking (it preceded tool calls). The final TextBlock that has no subsequent tool calls is the output.
Simpler approach that might work better: collect ALL text chunks in order. After the run completes, take the last chunk as content and all prior chunks as thinking entries. Interleave thinking entries with tool_records based on their position — thinking[0] happened before tool_records[0:N], thinking[1] happened before tool_records[N:M], etc.
The simplest correct approach: maintain a single ordered steps list. Every TextBlock appends a thinking step. Every tool_record (already tracked via the accumulator) appends a tool step. After the run, pop the last thinking step off and use it as content. The rest of steps is the timeline.
To make the interleaving work, the tool emissions need to add to the same ordered list. Currently tool_records is a flat list filled by closures. Instead, pass the timeline list to create_review_tools_server and have _emit_tool append directly to it. TextBlocks in the agent loop also append to it. Order is preserved because everything runs sequentially in the async loop.
app/tools/_helpers.pyUpdate make_emit_tool to accept the timeline list and append tool steps to it (in addition to the existing tool_records for backward compat with SSE):
def make_emit_tool(session_id, emit_fn, tool_records, timeline):
async def emit_tool(tool_name, summary, inputs, output_summary=None):
record = {...} # same as now
if tool_records is not None:
tool_records.append(record)
if timeline is not None:
timeline.append({"type": "tool", **record})
# SSE emit unchanged
app/tools/__init__.pyPass timeline through to make_emit_tool.
app/prompts.pyAdd a guideline to the system prompt. In the Guidelines section:
9. **Separate thinking from output.** Your response will be split into two parts automatically: your intermediate reasoning (which the user sees in a process timeline) and your final analysis (which renders as the main output). Write your final analysis as a polished document — do not include phrases like "Let me now..." or "Based on the above tools..." in your concluding output. Your planning and reasoning between tool calls is fine and encouraged — just know it renders separately from the final deliverable.
app/rendering.pyUpdate render_message to render the timeline:
<details>) with a summary like "View analysis process (23 steps)"message-content div renders below with the clean output, inline charts, citationsTimeline item rendering:
- Thinking: <div class="timeline-thinking"><p>Let me start with the overall landscape...</p></div>
- Tool: <div class="timeline-tool"><span class="tool-call-name">Search Reviews</span><span class="tool-call-summary">Searched: "noise cancellation" — 10 results</span></div>
static/style.cssAdd styles for timeline items. Keep it subtle — the timeline is secondary to the output:
- .timeline-thinking — small italic text, muted color, left border accent
- .timeline-tool — same as current .tool-call-item styling
- The overall timeline container should feel like a quiet process log, not a primary content area
static/app.jsThe SSE thinking-phase behavior during live streaming should still work — tool events populate the live accordion as before. The timeline rendering is only for the final persisted message (server-rendered HTML). No changes needed to the live SSE flow unless you want to also stream thinking text live (optional, skip for now).
[chart:N] markers)If the agent produces only one TextBlock (no intermediate thinking — just calls tools then writes the output), the timeline will have tool steps but no thinking entries. That's fine — the timeline just shows tool calls, and the output is the full text. No thinking section needed.
{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/models.py"
} 1→"""Pydantic models for ReviewLens."""
2→
3→from __future__ import annotations
4→
5→from datetime import datetime
6→from enum import Enum
7→from typing import Any
8→
9→from pydantic import BaseModel, Field
10→
11→
12→class Review(BaseModel):
13→ """A single review record."""
14→
15→ id: str = ""
16→ text: str
17→ rating: float | None = None
18→ date: datetime | None = None
19→ author: str = ""
20→ platform: str = ""
21→ metadata: dict[str, Any] = Field(default_factory=dict)
22→
23→
24→class IngestionSummary(BaseModel):
25→ """Summary shown after ingestion."""
26→
27→ total_reviews: int = 0
28→ date_range: str = ""
29→ rating_distribution: dict[str, int] = Field(default_factory=dict)
30→ average_rating: float | None = None
31→ platform: str = ""
32→ product_name: str = ""
33→ source_type: str = "" # "csv" or "url"
34→
35→
36→class ToolCallRecord(BaseModel):
37→ """A single tool invocation record for the activity accordion."""
38→
39→ tool_name: str
40→ summary: str
41→ inputs: dict[str, Any] = Field(default_factory=dict)
42→ output_summary: dict[str, Any] = Field(default_factory=dict)
43→
44→
45→class ChatMessage(BaseModel):
46→ """A single chat message."""
47→
48→ role: str # "user" or "assistant"
49→ content: str
50→ system_initiated: bool = False
51→ charts: list[dict[str, Any]] = Field(default_factory=list)
52→ follow_ups: list[str] = Field(default_factory=list)
53→ tool_calls: list[ToolCallRecord] = Field(default_factory=list)
54→ sources: list[dict[str, Any]] = Field(default_factory=list)
55→ timestamp: datetime = Field(default_factory=datetime.utcnow)
56→
57→
58→class Session(BaseModel):
59→ """A review analysis session."""
60→
61→ session_id: str
62→ product_name: str = ""
63→ platform: str = ""
64→ summary: IngestionSummary = Field(default_factory=IngestionSummary)
65→ messages: list[ChatMessage] = Field(default_factory=list)
66→ report_findings: dict[str, list[str]] = Field(default_factory=dict)
67→ status: str = "pending" # pending, ready, error
68→ created_at: datetime = Field(default_factory=datetime.utcnow)
69→{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/agent.py"
} 1→"""Conversational agent loop — invoked per-message, not per-session."""
2→
3→from __future__ import annotations
4→
5→import json
6→import os
7→from typing import Any
8→
9→from claude_agent_sdk import (
10→ AssistantMessage,
11→ ClaudeAgentOptions,
12→ ClaudeSDKClient,
13→ ResultMessage,
14→ TextBlock,
15→)
16→
17→from .models import ChatMessage, IngestionSummary, ToolCallRecord
18→from .prompts import build_system_prompt
19→from .tools import create_review_tools_server
20→
21→DEFAULT_MODEL = "claude-sonnet-4-6"
22→
23→# How many recent messages to pass in full before summarising
24→RECENT_WINDOW = 10
25→# Max older messages to summarise
26→SUMMARY_WINDOW = 30
27→
28→
29→def _build_conversation_context(
30→ conversation_history: list[ChatMessage],
31→ user_message: str,
32→) -> str:
33→ """Build structured conversation context for the agent.
34→
35→ Strategy:
36→ - Recent messages (last RECENT_WINDOW) are passed in full with role labels
37→ - Older messages are compressed into a topic summary
38→ - A session context block tracks what's been explored
39→ """
40→ total = len(conversation_history)
41→ parts: list[str] = []
42→
43→ if total > 0:
44→ # Split into older and recent
45→ recent_start = max(0, total - RECENT_WINDOW)
46→ older = conversation_history[max(0, recent_start - SUMMARY_WINDOW):recent_start]
47→ recent = conversation_history[recent_start:]
48→
49→ # Summarise older messages as topic bullets
50→ if older:
51→ topics = _extract_topics(older)
52→ parts.append(
53→ "## Session Context\n"
54→ f"This is message {total + 1} in the conversation. "
55→ f"Earlier topics explored:\n{topics}"
56→ )
57→
58→ # Pass recent messages with structure
59→ if recent:
60→ lines = []
61→ for msg in recent:
62→ role = "User" if msg.role == "user" else "Assistant"
63→ # Truncate very long assistant responses in context
64→ content = msg.content
65→ if msg.role == "assistant" and len(content) > 800:
66→ content = content[:800] + "\n[... truncated for context ...]"
67→ lines.append(f"**{role}:** {content}")
68→ parts.append("## Recent Conversation\n" + "\n\n".join(lines))
69→
70→ parts.append(f"## Current Question\n{user_message}")
71→ return "\n\n".join(parts)
72→
73→
74→def _extract_topics(messages: list[ChatMessage]) -> str:
75→ """Extract topic bullets from older messages for context summary."""
76→ topics: list[str] = []
77→ for msg in messages:
78→ if msg.role == "user":
79→ # Use first 120 chars of user messages as topic indicators
80→ text = msg.content.strip()
81→ if len(text) > 120:
82→ text = text[:120] + "..."
83→ topics.append(f"- {text}")
84→ if not topics:
85→ return "- (general exploration)"
86→ return "\n".join(topics)
87→
88→
89→async def handle_message(
90→ session_id: str,
91→ user_message: str,
92→ conversation_history: list[ChatMessage],
93→ summary: IngestionSummary,
94→ emit_fn,
95→) -> ChatMessage:
96→ """Run the agent for a single user message. Returns the assistant's response."""
97→
98→ model = os.getenv("CLAUDE_MODEL", DEFAULT_MODEL)
99→ system_prompt = build_system_prompt(summary)
100→
101→ # Build structured conversation context
102→ prompt = _build_conversation_context(conversation_history, user_message)
103→
104→ # Accumulators populated by tools via closure
105→ tool_records: list[dict] = []
106→ cited_sources: list[dict] = []
107→ charts: list[dict[str, Any]] = []
108→ follow_ups: list[str] = []
109→
110→ # Create per-request MCP server (closure over session_id)
111→ server = create_review_tools_server(
112→ session_id=session_id,
113→ emit_fn=emit_fn,
114→ tool_records=tool_records,
115→ cited_sources=cited_sources,
116→ chart_accumulator=charts,
117→ follow_up_accumulator=follow_ups,
118→ )
119→
120→ options = ClaudeAgentOptions(
121→ system_prompt=system_prompt,
122→ allowed_tools=["mcp__reviewlens__*"],
123→ permission_mode="bypassPermissions",
124→ max_turns=15,
125→ model=model,
126→ mcp_servers={"reviewlens": server},
127→ )
128→
129→ response_text = ""
130→
131→ try:
132→ async with ClaudeSDKClient(options=options) as client:
133→ await client.query(prompt)
134→ async for message in client.receive_response():
135→ if isinstance(message, AssistantMessage):
136→ for block in message.content:
137→ if isinstance(block, TextBlock) and block.text.strip():
138→ response_text += block.text.strip() + "\n"
139→ elif isinstance(message, ResultMessage):
140→ if message.result and not response_text.strip():
141→ response_text = message.result
142→
143→ except Exception as e:
144→ response_text = f"I encountered an error processing your question. Please try again.\n\nError: {str(e)}"
145→ await emit_fn(session_id, f"Agent error: {e}", "error")
146→
147→ return ChatMessage(
148→ role="assistant",
149→ content=response_text.strip(),
150→ charts=charts,
151→ follow_ups=follow_ups,
152→ tool_calls=[ToolCallRecord(**r) for r in tool_records],
153→ sources=cited_sources,
154→ )
155→{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/_helpers.py",
"offset": 1,
"limit": 50
} 1→"""Shared helpers for MCP tools — emit, source collection, text analysis."""
2→
3→from __future__ import annotations
4→
5→import json
6→import re
7→from typing import Any, Callable, Awaitable
8→
9→# Type alias for the SSE emit callback
10→EmitFn = Callable[[str, str, str], Awaitable[None]]
11→
12→# Type alias for the bound emit_tool helper
13→EmitToolFn = Callable[..., Awaitable[None]]
14→
15→# Type alias for the bound collect_sources helper
16→CollectSourcesFn = Callable[[list[dict[str, Any]]], None]
17→
18→
19→def make_emit_tool(
20→ session_id: str,
21→ emit_fn: EmitFn,
22→ tool_records: list[dict] | None,
23→) -> EmitToolFn:
24→ """Create a bound _emit_tool helper that closes over session state."""
25→
26→ async def emit_tool(
27→ tool_name: str,
28→ summary: str,
29→ inputs: dict[str, Any],
30→ output_summary: dict[str, Any] | None = None,
31→ ) -> None:
32→ record = {
33→ "tool_name": tool_name,
34→ "summary": summary,
35→ "inputs": inputs,
36→ "output_summary": output_summary or {},
37→ }
38→ if tool_records is not None:
39→ tool_records.append(record)
40→ payload = json.dumps(record)
41→ await emit_fn(session_id, payload, "tool")
42→
43→ return emit_tool
44→
45→
46→def make_collect_sources(
47→ cited_sources: list[dict] | None,
48→ seen_source_ids: set[str],
49→) -> CollectSourcesFn:
50→ """Create a bound _collect_sources helper that deduplicates sources."""{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/__init__.py"
} 1→"""MCP tools package for the ReviewLens agent."""
2→
3→from __future__ import annotations
4→
5→from claude_agent_sdk import create_sdk_mcp_server
6→
7→from ._helpers import EmitFn, make_emit_tool, make_collect_sources
8→from .data_tools import create_data_tools
9→from .analysis_tools import create_analysis_tools
10→from .presentation_tools import create_presentation_tools
11→from .knowledge_tools import create_knowledge_tools
12→from .report_tools import create_report_tools
13→
14→
15→def create_review_tools_server(
16→ session_id: str,
17→ emit_fn: EmitFn,
18→ tool_records: list[dict] | None = None,
19→ cited_sources: list[dict] | None = None,
20→ chart_accumulator: list[dict] | None = None,
21→ follow_up_accumulator: list[str] | None = None,
22→):
23→ """Create the MCP server with all review analysis tools.
24→
25→ Accumulator lists are populated by tools and read by agent.py
26→ to attach to the final ChatMessage.
27→ """
28→ # Set up shared state
29→ seen_source_ids: set[str] = set()
30→ if cited_sources is not None:
31→ seen_source_ids.update(s.get("id", "") for s in cited_sources)
32→
33→ emit_tool = make_emit_tool(session_id, emit_fn, tool_records)
34→ collect_sources = make_collect_sources(cited_sources, seen_source_ids)
35→
36→ # Collect all tools from each module
37→ tools = []
38→ tools += create_data_tools(session_id, emit_tool, collect_sources)
39→ tools += create_analysis_tools(session_id, emit_tool, collect_sources)
40→ tools += create_presentation_tools(emit_tool, chart_accumulator, follow_up_accumulator)
41→ tools += create_knowledge_tools(emit_tool)
42→ tools += create_report_tools(session_id, emit_tool)
43→
44→ return create_sdk_mcp_server(name="reviewlens", version="1.0.0", tools=tools)
45→{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/rendering.py",
"offset": 115,
"limit": 80
} 115→ return html, leftovers
116→
117→
118→def render_message(msg: ChatMessage) -> str:
119→ """Render a ChatMessage as HTML string.
120→
121→ Layout: thinking zone (collapsed accordion) → output zone (text with
122→ inline charts, citations, follow-ups).
123→ """
124→ # Skip system-initiated trigger messages (auto-analysis)
125→ if msg.system_initiated and msg.role == "user":
126→ return ""
127→
128→ role_class = "user-message" if msg.role == "user" else "assistant-message"
129→ escaped = html_module.escape(msg.content)
130→
131→ if msg.role == "assistant":
132→ content_html = md.markdown(
133→ msg.content,
134→ extensions=["tables", "fenced_code"],
135→ )
136→ content_html = _render_citations(content_html, msg.sources)
137→ else:
138→ content_html = f"<p>{escaped}</p>"
139→
140→ parts = [f'<div class="message {role_class}">']
141→
142→ # ── Thinking zone: tool accordion (collapsed, at top) ────────
143→ if msg.role == "assistant" and msg.tool_calls:
144→ n = len(msg.tool_calls)
145→ parts.append('<details class="tool-accordion">')
146→ parts.append(
147→ f'<summary class="tool-accordion-header">'
148→ f'<svg class="tool-accordion-chevron" width="12" height="12" viewBox="0 0 24 24" '
149→ f'fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">'
150→ f'<polyline points="6 9 12 15 18 9"/></svg>'
151→ f' {n} tool call{"s" if n != 1 else ""} — View analysis process</summary>'
152→ )
153→ parts.append('<div class="tool-accordion-body">')
154→ for tc in msg.tool_calls:
155→ tool_label = tc.tool_name.replace("_", " ").title()
156→ parts.append('<div class="tool-call-item">')
157→ parts.append(f'<span class="tool-call-name">{html_module.escape(tool_label)}</span>')
158→ parts.append(f'<span class="tool-call-summary">{html_module.escape(tc.summary)}</span>')
159→ if tc.inputs:
160→ detail_parts = []
161→ for k, v in tc.inputs.items():
162→ if k in ("query", "operation", "chart_type", "title", "section", "name", "question", "keyword") and v:
163→ detail_parts.append(f'{k}: {html_module.escape(str(v))}')
164→ if detail_parts:
165→ parts.append(f'<span class="tool-call-detail">{" · ".join(detail_parts)}</span>')
166→ parts.append('</div>')
167→ parts.append('</div></details>')
168→
169→ # ── Output zone: text with inline charts ─────────────────────
170→ if msg.role == "assistant" and msg.charts:
171→ content_html, leftover_charts = _render_inline_charts(content_html, msg.charts)
172→ else:
173→ leftover_charts = []
174→
175→ parts.append(f'<div class="message-content">{content_html}</div>')
176→
177→ # Append any charts that weren't placed inline
178→ for chart in leftover_charts:
179→ parts.append(_render_chart_html(chart))
180→
181→ # Follow-up buttons
182→ if msg.follow_ups:
183→ parts.append('<div class="follow-ups">')
184→ for q in msg.follow_ups:
185→ escaped_q = html_module.escape(q)
186→ parts.append(
187→ f'<button class="follow-up-btn" onclick="sendFollowUp(this)" '
188→ f'data-question="{escaped_q}">{escaped_q}</button>'
189→ )
190→ parts.append('</div>')
191→
192→ parts.append('</div>')
193→ return "\n".join(parts)
194→I have the full picture. Let me now implement all changes. The approach:
TimelineStep, replace tool_calls with timeline on ChatMessagetimeline param to make_emit_tooltimeline throughclass ToolCallRecord(BaseModel):
"""A single tool invocation record for the activity accordion."""
tool_name: str
summary: str
inputs: dict[str, Any] = Field(default_factory=dict)
output_summary: dict[str, Any] = Field(default_factory=dict)
class ChatMessage(BaseModel):
"""A single chat message."""
role: str # "user" or "assistant"
content: str
system_initiated: bool = False
charts: list[dict[str, Any]] = Field(default_factory=list)
follow_ups: list[str] = Field(default_factory=list)
tool_calls: list[ToolCallRecord] = Field(default_factory=list)
sources: list[dict[str, Any]] = Field(default_factory=list)
timestamp: datetime = Field(default_factory=datetime.utcnow)class TimelineStep(BaseModel):
"""A single step in the agent's work process — thinking or tool call."""
type: str # "thinking" or "tool"
# For thinking steps
text: str = ""
# For tool steps
tool_name: str = ""
summary: str = ""
inputs: dict[str, Any] = Field(default_factory=dict)
output_summary: dict[str, Any] = Field(default_factory=dict)
class ChatMessage(BaseModel):
"""A single chat message."""
role: str # "user" or "assistant"
content: str
system_initiated: bool = False
charts: list[dict[str, Any]] = Field(default_factory=list)
follow_ups: list[str] = Field(default_factory=list)
timeline: list[TimelineStep] = Field(default_factory=list)
sources: list[dict[str, Any]] = Field(default_factory=list)
timestamp: datetime = Field(default_factory=datetime.utcnow)The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/models.py has been updated successfully.
def make_emit_tool(
session_id: str,
emit_fn: EmitFn,
tool_records: list[dict] | None,
) -> EmitToolFn:
"""Create a bound _emit_tool helper that closes over session state."""
async def emit_tool(
tool_name: str,
summary: str,
inputs: dict[str, Any],
output_summary: dict[str, Any] | None = None,
) -> None:
record = {
"tool_name": tool_name,
"summary": summary,
"inputs": inputs,
"output_summary": output_summary or {},
}
if tool_records is not None:
tool_records.append(record)
payload = json.dumps(record)
await emit_fn(session_id, payload, "tool")
return emit_tooldef make_emit_tool(
session_id: str,
emit_fn: EmitFn,
tool_records: list[dict] | None,
timeline: list[dict] | None = None,
) -> EmitToolFn:
"""Create a bound _emit_tool helper that closes over session state."""
async def emit_tool(
tool_name: str,
summary: str,
inputs: dict[str, Any],
output_summary: dict[str, Any] | None = None,
) -> None:
record = {
"tool_name": tool_name,
"summary": summary,
"inputs": inputs,
"output_summary": output_summary or {},
}
if tool_records is not None:
tool_records.append(record)
if timeline is not None:
timeline.append({"type": "tool", **record})
payload = json.dumps(record)
await emit_fn(session_id, payload, "tool")
return emit_toolThe file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/_helpers.py has been updated successfully.
def create_review_tools_server(
session_id: str,
emit_fn: EmitFn,
tool_records: list[dict] | None = None,
cited_sources: list[dict] | None = None,
chart_accumulator: list[dict] | None = None,
follow_up_accumulator: list[str] | None = None,
):
"""Create the MCP server with all review analysis tools.
Accumulator lists are populated by tools and read by agent.py
to attach to the final ChatMessage.
"""
# Set up shared state
seen_source_ids: set[str] = set()
if cited_sources is not None:
seen_source_ids.update(s.get("id", "") for s in cited_sources)
emit_tool = make_emit_tool(session_id, emit_fn, tool_records)def create_review_tools_server(
session_id: str,
emit_fn: EmitFn,
tool_records: list[dict] | None = None,
cited_sources: list[dict] | None = None,
chart_accumulator: list[dict] | None = None,
follow_up_accumulator: list[str] | None = None,
timeline: list[dict] | None = None,
):
"""Create the MCP server with all review analysis tools.
Accumulator lists are populated by tools and read by agent.py
to attach to the final ChatMessage.
"""
# Set up shared state
seen_source_ids: set[str] = set()
if cited_sources is not None:
seen_source_ids.update(s.get("id", "") for s in cited_sources)
emit_tool = make_emit_tool(session_id, emit_fn, tool_records, timeline)The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/__init__.py has been updated successfully.
"""Conversational agent loop — invoked per-message, not per-session."""
from __future__ import annotations
import os
from typing import Any
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
ClaudeSDKClient,
ResultMessage,
TextBlock,
)
from .models import ChatMessage, IngestionSummary, TimelineStep
from .prompts import build_system_prompt
from .tools import create_review_tools_server
DEFAULT_MODEL = "claude-sonnet-4-6"
# How many recent messages to pass in full before summarising
RECENT_WINDOW = 10
# Max older messages to summarise
SUMMARY_WINDOW = 30
def _build_conversation_context(
conversation_history: list[ChatMessage],
user_message: str,
) -> str:
"""Build structured conversation context for the agent.
Strategy:
- Recent messages (last RECENT_WINDOW) are passed in full with role labels
- Older messages are compressed into a topic summary
- A session context block tracks what's been explored
"""
total = len(conversation_history)
parts: list[str] = []
if total > 0:
# Split into older and recent
recent_start = max(0, total - RECENT_WINDOW)
older = conversation_history[max(0, recent_start - SUMMARY_WINDOW):recent_start]
recent = conversation_history[recent_start:]
# Summarise older messages as topic bullets
if older:
topics = _extract_topics(older)
parts.append(
"## Session Context\n"
f"This is message {total + 1} in the conversation. "
f"Earlier topics explored:\n{topics}"
)
# Pass recent messages with structure
if recent:
lines = []
for msg in recent:
role = "User" if msg.role == "user" else "Assistant"
# Truncate very long assistant responses in context
content = msg.content
if msg.role == "assistant" and len(content) > 800:
content = content[:800] + "\n[... truncated for context ...]"
lines.append(f"**{role}:** {content}")
parts.append("## Recent Conversation\n" + "\n\n".join(lines))
parts.append(f"## Current Question\n{user_message}")
return "\n\n".join(parts)
def _extract_topics(messages: list[ChatMessage]) -> str:
"""Extract topic bullets from older messages for context summary."""
topics: list[str] = []
for msg in messages:
if msg.role == "user":
# Use first 120 chars of user messages as topic indicators
text = msg.content.strip()
if len(text) > 120:
text = text[:120] + "..."
topics.append(f"- {text}")
if not topics:
return "- (general exploration)"
return "\n".join(topics)
async def handle_message(
session_id: str,
user_message: str,
conversation_history: list[ChatMessage],
summary: IngestionSummary,
emit_fn,
) -> ChatMessage:
"""Run the agent for a single user message. Returns the assistant's response."""
model = os.getenv("CLAUDE_MODEL", DEFAULT_MODEL)
system_prompt = build_system_prompt(summary)
# Build structured conversation context
prompt = _build_conversation_context(conversation_history, user_message)
# Accumulators populated by tools via closure
tool_records: list[dict] = []
cited_sources: list[dict] = []
charts: list[dict[str, Any]] = []
follow_ups: list[str] = []
timeline: list[dict] = []
# Create per-request MCP server (closure over session_id)
server = create_review_tools_server(
session_id=session_id,
emit_fn=emit_fn,
tool_records=tool_records,
cited_sources=cited_sources,
chart_accumulator=charts,
follow_up_accumulator=follow_ups,
timeline=timeline,
)
options = ClaudeAgentOptions(
system_prompt=system_prompt,
allowed_tools=["mcp__reviewlens__*"],
permission_mode="bypassPermissions",
max_turns=15,
model=model,
mcp_servers={"reviewlens": server},
)
# Collect text chunks in order — interleaved with tool steps in timeline
text_chunks: list[str] = []
current_chunk: list[str] = []
last_tool_count = 0
try:
async with ClaudeSDKClient(options=options) as client:
await client.query(prompt)
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock) and block.text.strip():
# Check if tools fired since last text — if so,
# the previous text was thinking (it preceded tool calls)
if len(tool_records) > last_tool_count and current_chunk:
thinking_text = "\n".join(current_chunk).strip()
if thinking_text:
timeline.append({
"type": "thinking",
"text": thinking_text,
})
text_chunks.append(thinking_text)
current_chunk = []
last_tool_count = len(tool_records)
current_chunk.append(block.text.strip())
elif isinstance(message, ResultMessage):
if message.result and not current_chunk and not text_chunks:
current_chunk.append(message.result)
except Exception as e:
current_chunk = [f"I encountered an error processing your question. Please try again.\n\nError: {str(e)}"]
await emit_fn(session_id, f"Agent error: {e}", "error")
# Flush remaining text
final_text = "\n".join(current_chunk).strip()
# If there were tool calls after the last chunk flush, the chunks before
# tools were thinking. If tools fired but we never flushed, check now.
if len(tool_records) > last_tool_count and text_chunks:
# Tools fired after the last flush — that last chunk was thinking too,
# and final_text is the actual output
pass
elif not text_chunks and final_text:
# Only one chunk, no thinking — final_text is the output
pass
elif text_chunks and final_text:
# Multiple chunks: earlier ones are in timeline already,
# final_text is the output
pass
# The output content is always the last text chunk
content = final_text
return ChatMessage(
role="assistant",
content=content,
charts=charts,
follow_ups=follow_ups,
timeline=[TimelineStep(**step) for step in timeline],
sources=cited_sources,
)
The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/agent.py has been updated successfully.
{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/rendering.py",
"offset": 118,
"limit": 55
} 118→def render_message(msg: ChatMessage) -> str:
119→ """Render a ChatMessage as HTML string.
120→
121→ Layout: thinking zone (collapsed accordion) → output zone (text with
122→ inline charts, citations, follow-ups).
123→ """
124→ # Skip system-initiated trigger messages (auto-analysis)
125→ if msg.system_initiated and msg.role == "user":
126→ return ""
127→
128→ role_class = "user-message" if msg.role == "user" else "assistant-message"
129→ escaped = html_module.escape(msg.content)
130→
131→ if msg.role == "assistant":
132→ content_html = md.markdown(
133→ msg.content,
134→ extensions=["tables", "fenced_code"],
135→ )
136→ content_html = _render_citations(content_html, msg.sources)
137→ else:
138→ content_html = f"<p>{escaped}</p>"
139→
140→ parts = [f'<div class="message {role_class}">']
141→
142→ # ── Thinking zone: tool accordion (collapsed, at top) ────────
143→ if msg.role == "assistant" and msg.tool_calls:
144→ n = len(msg.tool_calls)
145→ parts.append('<details class="tool-accordion">')
146→ parts.append(
147→ f'<summary class="tool-accordion-header">'
148→ f'<svg class="tool-accordion-chevron" width="12" height="12" viewBox="0 0 24 24" '
149→ f'fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">'
150→ f'<polyline points="6 9 12 15 18 9"/></svg>'
151→ f' {n} tool call{"s" if n != 1 else ""} — View analysis process</summary>'
152→ )
153→ parts.append('<div class="tool-accordion-body">')
154→ for tc in msg.tool_calls:
155→ tool_label = tc.tool_name.replace("_", " ").title()
156→ parts.append('<div class="tool-call-item">')
157→ parts.append(f'<span class="tool-call-name">{html_module.escape(tool_label)}</span>')
158→ parts.append(f'<span class="tool-call-summary">{html_module.escape(tc.summary)}</span>')
159→ if tc.inputs:
160→ detail_parts = []
161→ for k, v in tc.inputs.items():
162→ if k in ("query", "operation", "chart_type", "title", "section", "name", "question", "keyword") and v:
163→ detail_parts.append(f'{k}: {html_module.escape(str(v))}')
164→ if detail_parts:
165→ parts.append(f'<span class="tool-call-detail">{" · ".join(detail_parts)}</span>')
166→ parts.append('</div>')
167→ parts.append('</div></details>')
168→
169→ # ── Output zone: text with inline charts ─────────────────────
170→ if msg.role == "assistant" and msg.charts:
171→ content_html, leftover_charts = _render_inline_charts(content_html, msg.charts)
172→ else: # ── Thinking zone: tool accordion (collapsed, at top) ────────
if msg.role == "assistant" and msg.tool_calls:
n = len(msg.tool_calls)
parts.append('<details class="tool-accordion">')
parts.append(
f'<summary class="tool-accordion-header">'
f'<svg class="tool-accordion-chevron" width="12" height="12" viewBox="0 0 24 24" '
f'fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">'
f'<polyline points="6 9 12 15 18 9"/></svg>'
f' {n} tool call{"s" if n != 1 else ""} — View analysis process</summary>'
)
parts.append('<div class="tool-accordion-body">')
for tc in msg.tool_calls:
tool_label = tc.tool_name.replace("_", " ").title()
parts.append('<div class="tool-call-item">')
parts.append(f'<span class="tool-call-name">{html_module.escape(tool_label)}</span>')
parts.append(f'<span class="tool-call-summary">{html_module.escape(tc.summary)}</span>')
if tc.inputs:
detail_parts = []
for k, v in tc.inputs.items():
if k in ("query", "operation", "chart_type", "title", "section", "name", "question", "keyword") and v:
detail_parts.append(f'{k}: {html_module.escape(str(v))}')
if detail_parts:
parts.append(f'<span class="tool-call-detail">{" · ".join(detail_parts)}</span>')
parts.append('</div>')
parts.append('</div></details>') # ── Timeline: thinking + tool calls interleaved (collapsed) ────
if msg.role == "assistant" and msg.timeline:
n = len(msg.timeline)
parts.append('<details class="tool-accordion">')
parts.append(
f'<summary class="tool-accordion-header">'
f'<svg class="tool-accordion-chevron" width="12" height="12" viewBox="0 0 24 24" '
f'fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">'
f'<polyline points="6 9 12 15 18 9"/></svg>'
f' {n} step{"s" if n != 1 else ""} — View analysis process</summary>'
)
parts.append('<div class="tool-accordion-body">')
for step in msg.timeline:
if step.type == "thinking" and step.text.strip():
parts.append(
f'<div class="timeline-thinking">'
f'<p>{html_module.escape(step.text[:500])}</p>'
f'</div>'
)
elif step.type == "tool":
tool_label = step.tool_name.replace("_", " ").title()
parts.append('<div class="tool-call-item">')
parts.append(f'<span class="tool-call-name">{html_module.escape(tool_label)}</span>')
parts.append(f'<span class="tool-call-summary">{html_module.escape(step.summary)}</span>')
if step.inputs:
detail_parts = []
for k, v in step.inputs.items():
if k in ("query", "operation", "chart_type", "title", "section", "name", "question", "keyword") and v:
detail_parts.append(f'{k}: {html_module.escape(str(v))}')
if detail_parts:
parts.append(f'<span class="tool-call-detail">{" · ".join(detail_parts)}</span>')
parts.append('</div>')
parts.append('</div></details>')The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/rendering.py has been updated successfully.
8. **Refuse gracefully.** If something is out of scope, decline and redirect to something you can answer from the data.
8. **Refuse gracefully.** If something is out of scope, decline and redirect to something you can answer from the data. 9. **Separate thinking from output.** Your response is automatically split into two parts: intermediate reasoning (shown in a collapsible process timeline) and final analysis (the main output). Write your final analysis as a polished document — avoid phrases like "Let me now...", "Based on the tools above...", or narrating your process in the final output. Your planning and reasoning between tool calls is fine and encouraged — it renders separately from the deliverable.
The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/prompts.py has been updated successfully.
{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/static/style.css",
"offset": 836,
"limit": 15
} 836→ font-family: var(--mono);
837→ font-size: 0.72rem;
838→ font-weight: 600;
839→ color: var(--accent);
840→ white-space: nowrap;
841→}
842→
843→.tool-call-summary {
844→ color: var(--text-1);
845→ font-size: 0.75rem;
846→}
847→
848→.tool-call-detail {
849→ width: 100%;
850→ font-family: var(--mono);.tool-call-detail {
width: 100%;
font-family: var(--mono);.timeline-thinking {
padding: 0.3rem 0 0.3rem 0.6rem;
border-left: 2px solid var(--bg-4);
margin: 0.15rem 0;
}
.timeline-thinking p {
margin: 0;
font-size: 0.75rem;
font-style: italic;
color: var(--text-3);
line-height: 1.4;
}
.tool-call-detail {
width: 100%;
font-family: var(--mono);The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/static/style.css has been updated successfully.
python3 -c "
import ast
for f in ['app/models.py', 'app/agent.py', 'app/rendering.py', 'app/prompts.py', 'app/tools/__init__.py', 'app/tools/_helpers.py']:
ast.parse(open(f).read())
print(f'{f}: OK')
"app/models.py: OK app/agent.py: OK app/rendering.py: OK app/prompts.py: OK app/tools/__init__.py: OK app/tools/_helpers.py: OK
lsof -ti :8000 2>/dev/null | xargs kill 2>/dev/null; sleep 1 && .venv/bin/uvicorn app.main:app --reload --reload-exclude '.venv' --reload-exclude 'data'
Command running in background with ID: bltd3zdan. Output is being written to: /private/tmp/claude-501/-Users-shaynelarocque-Documents-GitHub-futuresight/5c8423a6-db28-4eb0-98eb-ccb8759929ff/tasks/bltd3zdan.output
Server's up. Here's what changed:
Data model (models.py):
- ToolCallRecord → TimelineStep with type field ("thinking" or "tool")
- ChatMessage.tool_calls → ChatMessage.timeline
Agent loop (agent.py):
- Tracks text_chunks and current_chunk during the message stream
- When new tool records appear between TextBlocks, flushes the current chunk as a {"type": "thinking"} timeline entry
- Tool steps are added to the same timeline list by the emit_tool helper
- After the run, the last text chunk becomes content (clean output). All prior chunks + tool records are the timeline.
Tools pipeline (_helpers.py, __init__.py):
- make_emit_tool accepts and appends to the shared timeline list
- create_review_tools_server passes timeline through
Rendering (rendering.py):
- Timeline replaces the old tool accordion — renders thinking steps (italic, left-bordered) interleaved with tool call cards, all in a collapsed <details>
- Summary reads "N steps — View analysis process"
- Output zone unchanged (clean text + inline charts + citations + follow-ups)
Prompt (prompts.py):
- Guideline #9: "Separate thinking from output" — tells agent the split happens automatically, write final analysis as a polished document
CSS (style.css):
- .timeline-thinking — small italic text with left border accent, muted color
Read the output file to retrieve the result: /private/tmp/claude-501/-Users-shaynelarocque-Documents-GitHub-futuresight/5c8423a6-db28-4eb0-98eb-ccb8759929ff/tasks/b8ifu41ok.output
On branch main Your branch is up to date with 'origin/main'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: app/agent.py modified: app/models.py modified: app/prompts.py modified: app/rendering.py modified: app/tools/__init__.py modified: app/tools/_helpers.py modified: static/style.css no changes added to commit (use "git add" and/or "git commit -a") app/agent.py | 56 ++++++++++++++++++++++++++++++++++++++++++--------- app/models.py | 16 +++++++++------ app/prompts.py | 1 + app/rendering.py | 41 +++++++++++++++++++++---------------- app/tools/__init__.py | 3 ++- app/tools/_helpers.py | 3 +++ static/style.css | 14 +++++++++++++ 7 files changed, 101 insertions(+), 33 deletions(-)
git add app/agent.py app/models.py app/prompts.py app/rendering.py app/tools/__init__.py app/tools/_helpers.py static/style.css && git commit -m "$(cat <<'EOF' Thinking timeline: separate agent reasoning from clean output Replace tool_calls with unified timeline on ChatMessage — ordered sequence of TimelineStep entries (type: "thinking" or "tool") that captures the agent's work process chronologically. Agent loop now tracks text chunks between tool calls: intermediate reasoning becomes thinking timeline entries, final text chunk becomes the clean output content. Tools append to the same timeline list via the emit_tool helper. Renderer shows collapsed "N steps — View analysis process" toggle with thinking steps (italic, left-bordered) interleaved with tool call cards. Output zone below renders the polished analysis with inline charts and citations, free of process narration. Prompt guideline #9 tells the agent the split happens automatically and to write final output as a clean document. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> EOF )"
7 files changed, 101 insertions(+), 33 deletions(-)
Make the agent self-correcting. Three changes:
New tool: broaden_search — Takes a topic, uses Haiku to generate 4-5 query variants (synonyms, phrasings, related terms), batch-executes them against the vector DB, deduplicates, returns merged results with a coverage summary. A single search query should never be the basis for a finding.
New tool: verify_claims — Takes a list of claims from the agent's draft. For each: if it cites review IDs, look them up and confirm the text supports the claim. If it states a number/percentage, re-run the actual calculation via vectordb and return the real number. Returns pass/fail per claim with corrections.
Update the system prompt — Add a self-correction protocol to the Guidelines: before delivering any substantive response, the agent MUST broaden its search (minimum 3 angles per topic), verify any quantitative claims against calculate_stats, and honestly flag thin coverage when fewer than 5 reviews match. Make this mandatory, not aspirational.
All new tools should follow existing patterns (emit_tool for timeline tracking, same return format). Verification steps showing up in the tool accordion is a feature — it builds analyst trust. Use Haiku for any LLM calls inside tools.
{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/data_tools.py",
"offset": 1,
"limit": 20
} 1→"""Data access tools — search, sentiment, stats, review lookup."""
2→
3→from __future__ import annotations
4→
5→import json
6→from collections import Counter
7→from typing import Any
8→
9→from claude_agent_sdk import tool
10→
11→from .. import vectordb
12→from ._helpers import EmitToolFn, CollectSourcesFn
13→
14→
15→def create_data_tools(
16→ session_id: str,
17→ emit_tool: EmitToolFn,
18→ collect_sources: CollectSourcesFn,
19→) -> list:
20→ """Return data access tool definitions."""{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/__init__.py"
} 1→"""MCP tools package for the ReviewLens agent."""
2→
3→from __future__ import annotations
4→
5→from claude_agent_sdk import create_sdk_mcp_server
6→
7→from ._helpers import EmitFn, make_emit_tool, make_collect_sources
8→from .data_tools import create_data_tools
9→from .analysis_tools import create_analysis_tools
10→from .presentation_tools import create_presentation_tools
11→from .knowledge_tools import create_knowledge_tools
12→from .report_tools import create_report_tools
13→
14→
15→def create_review_tools_server(
16→ session_id: str,
17→ emit_fn: EmitFn,
18→ tool_records: list[dict] | None = None,
19→ cited_sources: list[dict] | None = None,
20→ chart_accumulator: list[dict] | None = None,
21→ follow_up_accumulator: list[str] | None = None,
22→ timeline: list[dict] | None = None,
23→):
24→ """Create the MCP server with all review analysis tools.
25→
26→ Accumulator lists are populated by tools and read by agent.py
27→ to attach to the final ChatMessage.
28→ """
29→ # Set up shared state
30→ seen_source_ids: set[str] = set()
31→ if cited_sources is not None:
32→ seen_source_ids.update(s.get("id", "") for s in cited_sources)
33→
34→ emit_tool = make_emit_tool(session_id, emit_fn, tool_records, timeline)
35→ collect_sources = make_collect_sources(cited_sources, seen_source_ids)
36→
37→ # Collect all tools from each module
38→ tools = []
39→ tools += create_data_tools(session_id, emit_tool, collect_sources)
40→ tools += create_analysis_tools(session_id, emit_tool, collect_sources)
41→ tools += create_presentation_tools(emit_tool, chart_accumulator, follow_up_accumulator)
42→ tools += create_knowledge_tools(emit_tool)
43→ tools += create_report_tools(session_id, emit_tool)
44→
45→ return create_sdk_mcp_server(name="reviewlens", version="1.0.0", tools=tools)
46→{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/prompts.py",
"offset": 118,
"limit": 20
}118→ 119→--- 120→ 121→## Guidelines 122→ 123→These define your quality bar: 124→ 125→1. **Search thoroughly.** Don't rely on a single search query. Use multiple queries with different phrasings and angles to build a complete picture. For example, if asked about "toppings", also search "ingredients", "menu items", "pizza", "food quality" etc. Cast a wide net, then synthesise. The cost of an extra search is low; the cost of missing relevant reviews is high. 126→2. **Ground every claim in data.** Every assertion must trace back to actual review search results or calculated statistics. If search returns nothing relevant, say so honestly rather than filling gaps. 127→3. **Cite specific reviews with source markers.** When quoting or paraphrasing a specific review, include its ID as a citation marker: `[source:review_id]`. For example: "One reviewer noted that the service was slow [source:review_42]." The system renders these as clickable citations showing the full review. Only cite review IDs that appeared in your search results. Each review in search results has an `id` field — use that. 128→4. **Be quantitative.** Counts, percentages, averages. Use calculate_stats for aggregations. "Many reviews mention X" is weak; "23% of negative reviews cite X" is strong. 129→5. **Charts serve the insight, inline.** A chart adds value for distributions, trends over time, and comparisons. Don't chart a single number. Don't chart everything. When you generate a chart, place an inline marker `[chart:N]` in your text where you want the chart to appear (N is the zero-based index of charts you've generated in this response, e.g. `[chart:0]` for the first chart, `[chart:1]` for the second). The system renders the chart at that position. If you omit the marker, the chart appends after your text. 130→6. **Confidence awareness.** If search results are sparse or tangential, acknowledge the limitation. "Based on the 4 reviews that mention this topic..." is more honest than overstating a finding. 131→7. **Be concise.** Users are analysts who want insights, not essays. Lead with the finding, support with evidence, suggest next steps. 132→8. **Refuse gracefully.** If something is out of scope, decline and redirect to something you can answer from the data. 133→9. **Separate thinking from output.** Your response is automatically split into two parts: intermediate reasoning (shown in a collapsible process timeline) and final analysis (the main output). Write your final analysis as a polished document — avoid phrases like "Let me now...", "Based on the tools above...", or narrating your process in the final output. Your planning and reasoning between tool calls is fine and encouraged — it renders separately from the deliverable. 134→""" 135→
"""Self-correction tools — broadened search and claim verification."""
from __future__ import annotations
import json
import os
from collections import Counter
from typing import Any
import anthropic
from claude_agent_sdk import tool
from .. import vectordb
from ._helpers import EmitToolFn, CollectSourcesFn
HAIKU_MODEL = "claude-haiku-4-5-20251001"
def create_verification_tools(
session_id: str,
emit_tool: EmitToolFn,
collect_sources: CollectSourcesFn,
) -> list:
"""Return self-correction tool definitions."""
# ── broaden_search ───────────────────────────────────────────────
@tool(
name="broaden_search",
description="Takes a topic and generates 4-5 query variants (synonyms, phrasings, related terms) via Haiku, batch-executes them against the review database, deduplicates, and returns merged results with a coverage summary. Use this instead of a single search_reviews call when building a finding — a single query should never be the sole basis for a conclusion.",
input_schema={
"type": "object",
"properties": {
"topic": {
"type": "string",
"description": "The topic to search broadly — e.g. 'shipping speed', 'customer service quality', 'food freshness'.",
},
"n_per_query": {
"type": "integer",
"description": "Results per query variant. Default 8, max 15.",
"default": 8,
},
"min_rating": {"type": "number", "description": "Optional rating filter."},
"max_rating": {"type": "number", "description": "Optional rating filter."},
},
"required": ["topic"],
},
)
async def broaden_search_tool(args: dict[str, Any]) -> dict[str, Any]:
topic = args["topic"]
n_per = min(args.get("n_per_query", 8), 15)
# Use Haiku to generate query variants
client = anthropic.AsyncAnthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
expansion_resp = await client.messages.create(
model=HAIKU_MODEL,
max_tokens=200,
messages=[{
"role": "user",
"content": (
f"Generate 5 search query variants for finding customer reviews about: \"{topic}\"\n"
"Include synonyms, related phrases, and different angles someone might use to discuss this topic.\n"
"Return ONLY a JSON array of strings, nothing else. Example: [\"query 1\", \"query 2\", ...]"
),
}],
)
raw = expansion_resp.content[0].text.strip()
# Parse the query variants
try:
queries = json.loads(raw)
if not isinstance(queries, list):
queries = [topic]
except json.JSONDecodeError:
queries = [topic]
# Always include the original topic
if topic not in queries:
queries.insert(0, topic)
queries = queries[:5]
# Build where clause for rating filters
conditions = []
if "min_rating" in args:
conditions.append({"rating": {"$gte": args["min_rating"]}})
if "max_rating" in args:
conditions.append({"rating": {"$lte": args["max_rating"]}})
where = None
if len(conditions) > 1:
where = {"$and": conditions}
elif len(conditions) == 1:
where = conditions[0]
# Execute all queries and deduplicate
seen_ids: set[str] = set()
merged: list[dict] = []
query_hits: dict[str, int] = {}
for q in queries:
results = vectordb.search_reviews(session_id, q, n_results=n_per, where=where)
new_count = 0
for r in results:
if r["id"] not in seen_ids:
seen_ids.add(r["id"])
merged.append(r)
new_count += 1
query_hits[q] = len(results)
collect_sources(merged)
await emit_tool(
"broaden_search",
f"Broadened search: \"{topic}\" — {len(queries)} queries, {len(merged)} unique results",
{"topic": topic, "queries": queries},
{"unique_results": len(merged), "query_hits": query_hits},
)
return {"content": [{"type": "text", "text": json.dumps({
"topic": topic,
"queries_used": queries,
"query_hits": query_hits,
"unique_results": len(merged),
"results": merged,
"coverage": "strong" if len(merged) >= 10 else "moderate" if len(merged) >= 5 else "thin",
"note": f"{'Coverage is thin — fewer than 5 unique reviews match. Flag this limitation.' if len(merged) < 5 else ''}",
})}]}
# ── verify_claims ────────────────────────────────────────────────
@tool(
name="verify_claims",
description="Self-correction tool. Takes a list of claims from your draft analysis and verifies each one: citation claims are checked against actual review text, quantitative claims are re-calculated against the database. Returns pass/fail per claim with corrections. Use this before delivering any substantive response.",
input_schema={
"type": "object",
"properties": {
"claims": {
"type": "array",
"items": {
"type": "object",
"properties": {
"claim": {
"type": "string",
"description": "The claim text to verify.",
},
"type": {
"type": "string",
"enum": ["citation", "quantitative"],
"description": "'citation' if the claim quotes/paraphrases a review, 'quantitative' if it states a number/percentage.",
},
"review_id": {
"type": "string",
"description": "For citation claims: the review ID being cited.",
},
"stat_operation": {
"type": "string",
"description": "For quantitative claims: the calculate_stats operation to re-run (e.g. 'rating_distribution', 'keyword_frequency').",
},
"stat_keyword": {
"type": "string",
"description": "For keyword_frequency claims: the keyword to count.",
},
},
"required": ["claim", "type"],
},
"description": "List of claims to verify. Include 2-5 key claims from your analysis.",
},
},
"required": ["claims"],
},
)
async def verify_claims_tool(args: dict[str, Any]) -> dict[str, Any]:
claims = args["claims"]
results: list[dict] = []
for claim_obj in claims[:10]: # Cap at 10
claim_text = claim_obj["claim"]
claim_type = claim_obj["type"]
verification: dict[str, Any] = {
"claim": claim_text,
"type": claim_type,
}
if claim_type == "citation":
review_id = claim_obj.get("review_id", "")
if not review_id:
verification["status"] = "fail"
verification["reason"] = "No review_id provided for citation claim."
else:
review = vectordb.get_review_by_id(session_id, review_id)
if not review:
verification["status"] = "fail"
verification["reason"] = f"Review '{review_id}' not found in database."
else:
verification["status"] = "pass"
verification["actual_text"] = review["text"][:400]
verification["rating"] = review.get("metadata", {}).get("rating")
elif claim_type == "quantitative":
operation = claim_obj.get("stat_operation", "")
keyword = claim_obj.get("stat_keyword", "")
all_reviews = vectordb.get_all_reviews(session_id)
if not all_reviews:
verification["status"] = "fail"
verification["reason"] = "No reviews in database."
elif operation == "keyword_frequency" and keyword:
count = sum(1 for r in all_reviews if keyword.lower() in r["text"].lower())
pct = round(count / len(all_reviews) * 100, 1)
verification["status"] = "pass"
verification["actual_count"] = count
verification["actual_percentage"] = pct
verification["total_reviews"] = len(all_reviews)
elif operation == "rating_distribution":
ratings = [r["metadata"].get("rating") for r in all_reviews if r["metadata"].get("rating") is not None]
dist = Counter(int(round(r)) for r in ratings)
verification["status"] = "pass"
verification["actual_distribution"] = {str(k): v for k, v in sorted(dist.items())}
verification["actual_average"] = round(sum(ratings) / len(ratings), 2) if ratings else None
elif operation == "summary_stats":
ratings = [r["metadata"].get("rating") for r in all_reviews if r["metadata"].get("rating") is not None]
verification["status"] = "pass"
verification["total_reviews"] = len(all_reviews)
verification["actual_average"] = round(sum(ratings) / len(ratings), 2) if ratings else None
else:
verification["status"] = "pass"
verification["note"] = "No specific re-calculation available for this operation."
results.append(verification)
passed = sum(1 for r in results if r.get("status") == "pass")
failed = sum(1 for r in results if r.get("status") == "fail")
await emit_tool(
"verify_claims",
f"Verified {len(results)} claims: {passed} passed, {failed} failed",
{"claim_count": len(results)},
{"passed": passed, "failed": failed},
)
return {"content": [{"type": "text", "text": json.dumps({
"verifications": results,
"summary": {"total": len(results), "passed": passed, "failed": failed},
"instruction": "If any claims failed verification, correct them in your output. If a citation doesn't match the actual review text, fix the quote. If a number is wrong, use the actual number from verification.",
})}]}
return [broaden_search_tool, verify_claims_tool]
File created successfully at: /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/verification_tools.py
from .report_tools import create_report_tools
from .report_tools import create_report_tools from .verification_tools import create_verification_tools
The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/__init__.py has been updated successfully.
tools += create_report_tools(session_id, emit_tool)
return create_sdk_mcp_server(name="reviewlens", version="1.0.0", tools=tools) tools += create_report_tools(session_id, emit_tool)
tools += create_verification_tools(session_id, emit_tool, collect_sources)
return create_sdk_mcp_server(name="reviewlens", version="1.0.0", tools=tools)The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/tools/__init__.py has been updated successfully.
Now update the prompt — add the verification tools to the Tools section and the self-correction protocol to Guidelines.
{
"file_path": "/Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/prompts.py",
"offset": 86,
"limit": 15
} 86→### Analysis Tools
87→- **compare_segments** — Compare two groups of reviews side by side (e.g., positive vs negative, recent vs older, by topic). Use for any "how does X differ from Y" question. Returns structured comparison with counts, avg ratings, unique terms, and samples.
88→- **extract_themes** — Discover and rank the main themes/topics across the review corpus using n-gram frequency analysis. Use when the user asks broad questions like "what are people talking about?" or when you need to understand the landscape before drilling in.
89→- **find_anomalies** — Scan for data quality issues and suspicious patterns: rating-text mismatches, duplicate reviews, unusual volume clustering, outlier lengths. Use proactively in initial briefings, or when asked about data quality or fake reviews.
90→
91→### Presentation Tools
92→- **generate_chart** — Create a Chart.js chart that renders inline in the chat. Place a `[chart:N]` marker in your text where the chart should appear. Use when a visual communicates better than text: distributions, trends, comparisons.
93→- **suggest_follow_ups** — Generate contextual follow-up question buttons. Call this at the END of every response.
94→
95→### Knowledge Tools
96→- **list_knowledge_files** — Discover available reference files with summaries.
97→- **read_knowledge_file** — Read a specific knowledge file for analytical frameworks and templates.
98→
99→### Report Tools
100→- **save_to_report** — Save a key finding to the running report. Use this to bookmark important insights as you discover them during conversation. Takes a section name and markdown content.### Presentation Tools
### Verification Tools - **broaden_search** — Takes a topic and generates 4-5 query variants (synonyms, related terms), batch-executes them, deduplicates, and returns merged results with coverage assessment. Use this instead of a single search_reviews call when building any finding. - **verify_claims** — Self-correction tool. Takes a list of claims from your draft analysis and verifies each: citation claims are checked against actual review text, quantitative claims are re-calculated. Returns pass/fail with corrections. ### Presentation Tools
The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/prompts.py has been updated successfully.
Now update Guidelines — replace #1 (search thoroughly) with the mandatory self-correction protocol.
1. **Search thoroughly.** Don't rely on a single search query. Use multiple queries with different phrasings and angles to build a complete picture. For example, if asked about "toppings", also search "ingredients", "menu items", "pizza", "food quality" etc. Cast a wide net, then synthesise. The cost of an extra search is low; the cost of missing relevant reviews is high. 2. **Ground every claim in data.** Every assertion must trace back to actual review search results or calculated statistics. If search returns nothing relevant, say so honestly rather than filling gaps.
1. **Self-correction protocol (mandatory).** Before delivering any substantive response, you MUST: - Use `broaden_search` for every topic you're investigating — never base a finding on a single search query. Minimum 3 angles per topic. - Verify quantitative claims against `calculate_stats` — if you state a percentage or count, confirm it with the actual data. - Use `verify_claims` on your key findings before the final output — pass your 2-5 most important claims through verification. - If fewer than 5 reviews match a topic, explicitly flag this as thin coverage: "Based on N reviews mentioning this topic..." Don't present thin data as definitive. This is not aspirational — it's required. Verification steps appear in the analysis process timeline, which builds analyst trust. 2. **Ground every claim in data.** Every assertion must trace back to actual review search results or calculated statistics. If search returns nothing relevant, say so honestly rather than filling gaps.
The file /Users/shaynelarocque/Documents/GitHub/futuresight/reviewlens/app/prompts.py has been updated successfully.
python3 -c "
import ast
for f in ['app/tools/verification_tools.py', 'app/tools/__init__.py', 'app/prompts.py']:
ast.parse(open(f).read())
print(f'{f}: OK')
"lsof -ti :8000 2>/dev/null | xargs kill 2>/dev/null; sleep 1 && .venv/bin/uvicorn app.main:app --reload --reload-exclude '.venv' --reload-exclude 'data'
Command running in background with ID: bl5qi03cu. Output is being written to: /private/tmp/claude-501/-Users-shaynelarocque-Documents-GitHub-futuresight/5c8423a6-db28-4eb0-98eb-ccb8759929ff/tasks/bl5qi03cu.output
Server's up. Here's what was added:
broaden_search — Calls Haiku to generate 4-5 query variants from a topic, batch-executes all against ChromaDB, deduplicates by review ID, returns merged results with a coverage assessment (strong/moderate/thin). Replaces single search_reviews calls as the basis for findings.
verify_claims — Takes 2-10 claims from the agent's draft. For citation claims: looks up the review by ID and returns the actual text for comparison. For quantitative claims: re-runs the calculation against vectordb and returns the real number. Returns pass/fail per claim with corrections.
Prompt — Guideline #1 is now a mandatory self-correction protocol: broaden_search for every topic (minimum 3 angles), verify quantitative claims against calculate_stats, verify_claims on key findings before output, and explicitly flag thin coverage (< 5 reviews). Framed as required, not aspirational.
Both tools emit to the timeline, so verification steps show up in the "View analysis process" accordion — visible trust signal for the analyst.