Mapper3

AI-powered market research agent that generates structured market maps, feature comparisons, funding timelines, SWOT analyses, and news digests for technology categories.

Live at mapper.calibrelabs.ai · Built by Calibre Labs.

What it does

Type a category ("CRM", "mRNA therapeutics", "companies likely to IPO") and the agent:

1. Clarifies scope with you
2. Searches the web for current data
3. Generates a structured analysis using one of 5 tools
4. Answers follow-up questions and refines on request

Tools

Tool	Output	Example prompt
Market Map	Ranked company table with metrics	"CRM software"
Feature Matrix	✅/❌/🔶 comparison grid	"Compare features of note-taking apps"
Funding Timeline	Investment rounds with valuations	"Funding history of top AI startups"
SWOT Analysis	Data-backed strengths/weaknesses/opportunities/threats	"SWOT on Stripe"
News Digest	Recent headlines with sentiment	"Latest news on CRM companies"

Plus generate_markdown_response for long-form analytical answers and google_search for live web data. Refinements preserve existing values and only re-search for new items.

Stack

• Framework: Next.js 16 (App Router) + TypeScript + Tailwind CSS v4
• AI: Gemini 3.1 Flash-Lite via @ai-sdk/google (Vercel AI SDK)
• Search: google.tools.googleSearch() for live web data
• Auth: Cookie-based username (no passwords, no OAuth)
• DB: SQLite via better-sqlite3 (WAL mode), /data volume on Railway
• Analytics: Amplitude Browser + Node SDKs + @amplitude/ai (Agent Analytics)
• Tracing: Braintrust (wrapAISDK pattern, per-turn spans with metadata.username)
• Hosting: Railway (full stack with SQLite volume)
• Design: Calibre Labs brand (Fraunces + Plus Jakarta Sans, navy/gold/cream, light/dark toggle)

Setup

# Install dependencies
npm install

# Set environment variables
cp .env.example .env.local
# Fill in GOOGLE_GENERATIVE_AI_API_KEY (https://aistudio.google.com/apikey)
# and NEXT_PUBLIC_AMPLITUDE_API_KEY if you want analytics in dev

# Run dev server
npm run dev          # via portless (auto-assigns local HTTPS)
npm run dev:plain    # direct `next dev` if portless misbehaves

Environment Variables

See .env.example for the full surface. Required for local dev:

Variable	Required	Description
GOOGLE_GENERATIVE_AI_API_KEY	Yes	Google AI Studio API key
NEXT_PUBLIC_AMPLITUDE_API_KEY	No	Browser-side Amplitude (dev OK to skip)
AMPLITUDE_API_KEY	No	Server-side Amplitude (Node SDK + @amplitude/ai)
BRAINTRUST_API_KEY	No	Braintrust LLM tracing
DATABASE_PATH	No	SQLite path (default: ./data/mapper3.db; Railway uses /data/mapper3.db)
REWRITE_ADMIN_TOKEN	No	Bearer token for /api/admin/rewrite-history (prod only)

Testing

# Run E2E tests (requires dev server running)
npx tsx tests/e2e.ts

# If server is on a non-default port
BASE_URL=http://localhost:4896 npx tsx tests/e2e.ts

11 tests covering all 5 tools + refinement + Q&A mode. ~30-60s total.

Project Structure

app/
  (app)/          Authenticated pages (chat, history, profile)
  (auth)/         Login page (username cookie)
  share/[id]/     Public share pages for tool outputs
  api/
    chat/         Streaming chat endpoint (tool calling)
    admin/        Token-gated admin endpoints (e.g. rewrite-history)
components/
  chat/           Message bubbles, tool cards, streaming indicators
lib/
  ai/             Gemini provider, system prompts, tool definitions
  db/             SQLite connection, schema, queries
  session/        FSM state machine (NEW → PLANNING → MAPPING → REFINING → COMPLETE)
  scoring/        Composite session score (outcome / quality / efficiency / reliability)
  tracing/        Braintrust integration + circuit breaker
  amplitude-ai.ts Amplitude AI SDK singleton + flush helpers
  analytics.ts    Amplitude Browser SDK wrapper
docs/             Tracking plan + retros (agent analytics, taxonomy, devex)
scripts/
  rewrite-session-score-history.ts   Local DB → re-emit Score events at original timestamps
tests/
  e2e.ts          End-to-end tests (5 tools + refinement + Q&A)

Architecture

User message
  -> Turn 1: Scope clarification (no tools, ~2s)
  -> Turn 2+: Model self-selects from 6 tools:
       google_search -> gather data -> output tool
  -> Q&A: Answer questions about existing outputs in text
  -> Refine: Copy existing values, only search for new items

All turns use gemini-3.1-flash-lite-preview with google.tools.googleSearch() for live data. Each turn emits Amplitude [Agent] events and a Braintrust span tagged with metadata.username. Session-end emits a composite [Agent] Score event covering outcome, quality, efficiency, and reliability (= tool-emit compliance).

Production

Deployed to Railway via nixpacks. SQLite lives on the /data volume (set DATABASE_PATH=/data/mapper3.db in Railway env). See railway.toml and docs/ for deploy notes and retros.

Admin endpoint: POST /api/admin/rewrite-history (Bearer-token gated) re-emits historical [Agent] Score events at their original timestamps for in-place chart correction.