Architecture

High-Level Flow

Client POST /research { query, mode, breadth, depth_levels }
│
├─ Phase 1: Planning
│    Model: Sonnet 4.6
│    Output: ResearchPlan { topics[]: { title, tasks[] } }
│
├─ Phase 1.5: STORM Perspective Discovery
│    Model: Haiku 4.5
│    Output: 3-5 perspectives with key questions
│    (Skipped for short/simple queries < 30 chars)
│
├─ Phase 2: Recursive Tree Search
│    For each depth level (default 3):
│      ├─ Generate N queries (Haiku 4.5, N = breadth)
│      ├─ Execute all N in parallel via tool executors
│      ├─ Extract learnings (Sonnet 4.6)
│      ├─ Deduplicate learnings (Jaccard similarity ≥ 0.7)
│      ├─ Detect knowledge gaps (Sonnet 4.6)
│      ├─ Update dynamic outline
│      └─ If depth > 0 and gaps exist → recurse (depth-1, breadth/2)
│
├─ Phase 3: Verified Synthesis (Opus 4.7)
│    ├─ Build source block (max 25 sources, 1500 chars each)
│    ├─ Streaming synthesis with retrieve-then-cite verification
│    ├─ Gap check → optional re-synthesis
│    └─ Multi-pass review → revise (up to 2 passes, threshold 0.8)
│
├─ Post-processing
│    ├─ Data visualization extraction
│    ├─ Conflict detection
│    ├─ Structured output extraction (if output_schema provided)
│    └─ Memorize key learnings to knowledge base
│
└─ SSE stream throughout all phases

Mode Dispatch

Krawl has two execution paths:

• quick → flat agent loop (LLM picks tools iteratively, tool_choice='required')
• deep / crypto / all others → recursive breadth×depth tree search

Recursive Deep Research

The core engine for deep mode:

1. Query Generation — Haiku generates N search queries per depth level, informed by accumulated learnings and STORM perspectives
2. Parallel Execution — all N queries execute concurrently across available tools
3. Learning Extraction — Sonnet extracts structured learnings from search results with confidence scores
4. Deduplication — Jaccard word overlap with stemming (threshold 0.7) prevents redundant learnings
5. Gap Detection — Sonnet identifies remaining knowledge gaps with priority scores and suggested tools
6. Outline Update — dynamic outline evolves as evidence accumulates
7. Recursion — if gaps remain and depth > 0, recurse with depth-1 and breadth/2

Configuration

STORM Perspective Discovery

Inspired by Stanford's STORM, Krawl discovers 3–5 research perspectives before starting the search tree. Each perspective has:

• name — the perspective role (e.g., "Financial Analyst", "Security Researcher")
• description — what this perspective focuses on
• key_questions — specific questions this perspective would ask

Perspectives are injected into query generation, ensuring the research tree covers multiple angles rather than a single viewpoint. Skipped for short queries (< 30 chars or single word).

Multi-Pass Synthesis

Synthesis happens in 3 sub-phases:

Initial Synthesis (Opus 4.7)

One streaming LLM call generates the full report from learnings + source content. Uses retrieve-then-cite — only sources whose content was actually fetched can be cited.

Gap Check (Sonnet 4.6)

After initial synthesis, a quality gate reviews the report for missing coverage. If gaps are found, a re-synthesis pass incorporates the missing aspects.

Review → Revise Loop (up to 2 passes)

A review model scores the report (0–1) and lists issues. If the score is below 0.8, a revision pass is triggered. The loop runs at most 2 times (configurable via MAX_REVISION_PASSES).

Initial synthesis (Opus 4.7)
    └─ Gap check (Sonnet 4.6)
        └─ If gaps found → Re-synthesize (Opus 4.7)
    └─ Review pass 1 (Sonnet 4.6) → score < 0.8?
        └─ Revise pass 1 (Opus 4.7)
    └─ Review pass 2 (Sonnet 4.6) → score < 0.8?
        └─ Revise pass 2 (Opus 4.7)
    └─ Accept report

Flat Agent Loop (Quick Mode)

For quick mode, the original agent loop is used:

1. Planning — structured research plan
2. Agent loop — LLM iteratively picks tools with tool_choice='required', max 40 steps
3. Synthesis — single-pass report generation
4. Message trimming — when conversation exceeds 44 messages, trim to keep first 2 + last 40

Agent Tools

The LLM has access to these tools during research:

Tool Filtering

The sources parameter in the research request controls which tools are available:

{
  "query": "...",
  "sources": ["exa", "x", "crypto"]
}

Only tools mapped to the specified source types are exposed to the LLM. The thinking and done tools are always available.

Concurrency

• Research semaphore: max 3 concurrent research sessions
• Parallel searches: all queries at each depth level run concurrently
• Rate limiting: 5 requests/minute per IP (configurable)

Security

• API key auth via X-API-Key header (HMAC comparison)
• Security headers: HSTS, X-Frame-Options DENY, X-Content-Type-Options nosniff
• Request body limits: 1MB (normal), 50MB (file uploads)
• SSRF prevention on webhook URLs
• Global exception handler sanitizes all errors