Claude Code transcript - page 7/11

from .report_tools import create_report_tools

    tools += create_report_tools(session_id, emit_tool)

"""Data access tools — search, sentiment, stats, review lookup."""

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"

    @tool(
        name="search_reviews",
        description="Semantic search over the ingested review database. Returns the most relevant reviews ranked by similarity. Set broaden=true for substantive questions — this generates query variants via Haiku, runs them all, and deduplicates for broader coverage.",
        input_schema={
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query — describe what you're looking for in natural language.",
                },
                "n_results": {
                    "type": "integer",
                    "description": "Number of results to return (default 10, max 25).",
                    "default": 10,
                },
                "broaden": {
                    "type": "boolean",
                    "description": "When true, generates 3-4 query variants and merges deduplicated results for broader coverage. Use for any substantive analysis question.",
                    "default": False,
                },
                "min_rating": {
                    "type": "number",
                    "description": "Optional: only return reviews with rating >= this value.",
                },
                "max_rating": {
                    "type": "number",
                    "description": "Optional: only return reviews with rating <= this value.",
                },
                "date_after": {
                    "type": "string",
                    "description": "Optional: only return reviews after this date (ISO format, e.g. '2024-06-01').",
                },
                "date_before": {
                    "type": "string",
                    "description": "Optional: only return reviews before this date (ISO format, e.g. '2024-09-30').",
                },
            },
            "required": ["query"],
        },
    )
    async def search_reviews_tool(args: dict[str, Any]) -> dict[str, Any]:
        query = args["query"]
        n = min(args.get("n_results", 10), 25)
        broaden = args.get("broaden", False)

        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"]}})
        if "date_after" in args:
            conditions.append({"date": {"$gte": args["date_after"]}})
        if "date_before" in args:
            conditions.append({"date": {"$lte": args["date_before"]}})

        where = None
        if len(conditions) > 1:
            where = {"$and": conditions}
        elif len(conditions) == 1:
            where = conditions[0]

        if broaden:
            # Generate query variants via Haiku
            client = anthropic.AsyncAnthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
            try:
                expansion = await client.messages.create(
                    model=HAIKU_MODEL,
                    max_tokens=150,
                    messages=[{
                        "role": "user",
                        "content": (
                            f"Generate 4 alternative search queries for finding customer reviews about: \"{query}\"\n"
                            "Include synonyms, related phrases, different angles.\n"
                            "Return ONLY a JSON array of strings."
                        ),
                    }],
                )
                variants = json.loads(expansion.content[0].text.strip())
                if not isinstance(variants, list):
                    variants = []
            except Exception:
                variants = []

            queries = [query] + [v for v in variants[:4] if isinstance(v, str)]

            # Run all queries and deduplicate
            seen_ids: set[str] = set()
            results: list[dict] = []
            query_hits: dict[str, int] = {}
            for q in queries:
                hits = vectordb.search_reviews(session_id, q, n_results=n, where=where)
                query_hits[q] = len(hits)
                for r in hits:
                    if r["id"] not in seen_ids:
                        seen_ids.add(r["id"])
                        results.append(r)

            collect_sources(results)

            coverage = "strong" if len(results) >= 10 else "moderate" if len(results) >= 5 else "thin"

            await emit_tool(
                "search_reviews",
                f"Broadened search: \"{query}\" — {len(queries)} variants, {len(results)} unique results ({coverage})",
                {"query": query, "broaden": True, "variants": queries},
                {"unique_results": len(results), "coverage": coverage},
            )

            return {"content": [{"type": "text", "text": json.dumps({
                "query": query,
                "broadened": True,
                "queries_used": queries,
                "unique_result_count": len(results),
                "coverage": coverage,
                "results": results,
                "note": f"{'Coverage is thin — fewer than 5 unique reviews. Flag this limitation honestly.' if coverage == 'thin' else ''}",
            })}]}
        else:
            results = vectordb.search_reviews(session_id, query, n_results=n, where=where)
            collect_sources(results)

            await emit_tool(
                "search_reviews",
                f"Searched reviews: \"{query}\" — {len(results)} results",
                {"query": query, "n_results": n},
                {"result_count": len(results)},
            )

            return {"content": [{"type": "text", "text": json.dumps({
                "query": query,
                "result_count": len(results),
                "results": results,
                "note": "If no results are relevant, tell the user you couldn't find matching reviews. Do NOT make up information.",
            })}]}

### Presentation Tools

- **search_reviews** — Semantic search with optional rating/date filters. Set `broaden: true` for substantive questions — generates query variants via Haiku, runs them all, deduplicates for broader coverage. Use `broaden: true` for any analysis question; plain search for simple lookups.

1. **Self-correction protocol (mandatory).** For any substantive analysis:
   - Use `search_reviews` with `broaden: true` — never base a finding on a single query.
   - Before stating any percentage or count, confirm it with `calculate_stats`. Never present an unverified number.
   - After drafting your analysis, use `get_review_by_id` to spot-check that cited reviews actually say what you claimed. If they don't, correct the quote.
   - If fewer than 5 reviews match a topic, flag it: "Based on N reviews..." Don't present thin data as definitive.
   These verification steps show in the analysis timeline and build analyst trust.

HAIKU_MODEL = "claude-haiku-4-5"

                    "enum": ["bar", "horizontalBar", "stacked_bar", "line", "pie", "doughnut", "radar", "scatter"],

function renderChart(canvasId, config) {
  var canvas = document.getElementById(canvasId);
  if (!canvas) return;

  var textColor = getChartTextColor();
  var gridColor = getChartGridColor();

  // Normalize custom types to Chart.js types
  var chartType = config.type;
  var isHorizontal = chartType === "horizontalBar";
  var isStacked = chartType === "stacked_bar";
  if (isHorizontal || isStacked) chartType = "bar";

  var noScales = chartType === "pie" || chartType === "doughnut" || chartType === "radar";
  var isRadarOrPie = chartType === "pie" || chartType === "doughnut" || chartType === "radar";

  var datasets = config.data.datasets.map(function (ds, i) {
    var multiColor = isRadarOrPie;
    var colors = multiColor ? CHART_COLORS.slice(0, ds.data.length) : [CHART_COLORS[i % CHART_COLORS.length]];
    var borders = multiColor ? CHART_BORDERS.slice(0, ds.data.length) : [CHART_BORDERS[i % CHART_BORDERS.length]];

    var dsConfig = {
      label: ds.label,
      data: ds.data,
      backgroundColor: colors.length === 1 ? colors[0] : colors,
      borderColor: borders.length === 1 ? borders[0] : borders,
      borderWidth: chartType === "line" ? 2 : chartType === "radar" ? 2 : 1,
      tension: 0.3,
      fill: chartType === "line" || chartType === "radar",
    };

    if (chartType === "radar") {
      dsConfig.backgroundColor = (colors.length === 1 ? colors[0] : colors[0]).replace("0.75)", "0.2)");
      dsConfig.pointBackgroundColor = borders.length === 1 ? borders[0] : borders;
    }

    return dsConfig;
  });

  var scales = undefined;
  if (!noScales) {
    var xAxis = {
      ticks: { color: textColor, font: { family: "'IBM Plex Mono', monospace", size: 10 } },
      grid: { color: gridColor },
    };
    var yAxis = {
      ticks: { color: textColor, font: { family: "'IBM Plex Mono', monospace", size: 10 } },
      grid: { color: gridColor },
      beginAtZero: true,
    };
    if (isHorizontal) xAxis.beginAtZero = true;
    if (isStacked) {
      xAxis.stacked = true;
      yAxis.stacked = true;
    }
    scales = { x: xAxis, y: yAxis };
  }

  var chartOptions = {
    responsive: true,
    maintainAspectRatio: true,
    plugins: {
      title: {
        display: true,
        text: config.title,
        font: { size: 13, weight: "500", family: "'DM Sans', sans-serif" },
        color: textColor,
        padding: { bottom: 12 },
      },
      legend: {
        labels: { color: textColor, font: { family: "'DM Sans', sans-serif", size: 11 } },
      },
    },
    scales: scales,
  };

  if (isHorizontal) chartOptions.indexAxis = "y";

  if (chartType === "radar") {
    chartOptions.scales = {
      r: {
        ticks: { color: textColor, font: { size: 9 }, backdropColor: "transparent" },
        grid: { color: gridColor },
        pointLabels: { color: textColor, font: { family: "'DM Sans', sans-serif", size: 10 } },
      },
    };
  }

  new Chart(canvas, {
    type: chartType,
    data: { labels: config.data.labels, datasets: datasets },
    options: chartOptions,
  });
}

5. **Charts serve the insight, inline.** Don't chart a single number. Don't chart everything. Place `[chart:N]` in your text where each chart should appear. Chart type guide: `bar` for simple comparisons, `horizontalBar` for ranked lists (top complaints, aspects by frequency), `stacked_bar` for sentiment breakdowns by aspect (positive/negative/neutral stacked), `line` for trends over time, `pie`/`doughnut` for proportions, `radar` for multi-aspect product profiles, `scatter` for correlations. Choose the type that best serves the insight.