An LLM-powered tree search engine for multi-turn conversation optimization.

DTS explores conversation strategies in parallel, simulates diverse user reactions, scores trajectories with multi-judge consensus, and prunes underperformers—finding optimal dialogue paths that single-shot LLM responses miss.

Real-time tree exploration with strategy scoring, conversation playback, and detailed evaluation breakdowns

• Why DTS?
• How It Works
  • The Algorithm
  • Parallel Beam Search
  • User Intent Forking
  • Multi-Judge Scoring
  • Scoring Modes
• System Architecture
• Prerequisites & API Keys
• Installation
• Quick Start
• Configuration
• Deep Research Integration
• API Reference
• Frontend Visualizer
• Project Structure
• Token Usage & Cost Management
• Troubleshooting
• License

Standard LLMs generate responses one turn at a time, optimizing locally without considering long-term conversation outcomes. This leads to:

• Myopic responses that sound good but lead to dead ends
• Single-path thinking that misses better strategic approaches
• Fragile strategies that fail when users respond unexpectedly

DTS solves this by treating conversation as a tree search problem:

1. Explore multiple strategies in parallel (not just one response)
2. Simulate diverse user reactions (skeptical, enthusiastic, confused, etc.)
3. Score complete trajectories against your goal
4. Prune bad paths early to focus computation on promising directions

The result: dialogue strategies that are robust, goal-oriented, and tested against varied user behaviors.

DTS implements a parallel beam search with the following loop:

For each round:
    1. Generate N diverse conversation strategies
    2. For each strategy, simulate K user intent variants
    3. Roll out multi-turn conversations for each branch
    4. Score all trajectories with 3 independent judges
    5. Prune branches below threshold (median vote)
    6. Backpropagate scores up the tree
    7. Repeat with surviving branches

Unlike traditional single-path generation, DTS maintains multiple conversation branches simultaneously:

graph TD
    subgraph Round 1
        Root[User Message] --> S1[Strategy: Empathetic]
        Root --> S2[Strategy: Direct]
        Root --> S3[Strategy: Socratic]
    end

    subgraph Round 2
        S1 --> S1I1[Intent: Cooperative]
        S1 --> S1I2[Intent: Skeptical]
        S2 --> S2I1[Intent: Cooperative]
        S2 --> S2I2[Intent: Resistant]
    end

    subgraph Scoring
        S1I1 --> J1((Judge 1))
        S1I1 --> J2((Judge 2))
        S1I1 --> J3((Judge 3))
        J1 & J2 & J3 --> M{Median Vote}
    end

    M -->|Score ≥ 6.5| Keep[Keep Branch]
    M -->|Score < 6.5| Prune[Prune Branch]

Branches are color-coded by score: green (passing), yellow (borderline), red (pruned)

Key parameters:

• init_branches: Number of initial strategies (default: 6)
• turns_per_branch: Conversation depth per branch (default: 5)
• max_concurrency: Parallel LLM calls (default: 16)

Most dialogue systems assume a single "happy path" user response. DTS can stress-test strategies against diverse user personas when enabled.

User Variability Mode:

• user_variability=False (default): Uses a fixed "healthily critical + engaged" persona for consistent, realistic testing
• user_variability=True: Generates diverse user intents for robustness testing across user types

When variability is enabled, possible user personas include:

Each strategy can fork into K intent variants (configurable via user_intents_per_branch), creating branches that prove robustness across user types.

UserIntent structure:

UserIntent(
    id="skeptical_questioner",
    label="Skeptical Questioner",
    description="Demands evidence before accepting claims",
    emotional_tone="skeptical",      # How user feels
    cognitive_stance="questioning",  # How user thinks
)

Each trajectory is evaluated by 3 independent LLM judges. Scores are aggregated via median voting (robust to outlier judges):

Judge 1: 7.2  ─┐
Judge 2: 6.8  ─┼─► Median: 7.2  ─► Pass (≥ 6.5)
Judge 3: 8.1  ─┘

Why 3 judges?

• Single judge = high variance, easily gamed
• Median of 3 = robust to one outlier
• Majority vote determines pass/fail (2 of 3 must pass)

Scoring criteria (each 0-1, summed to 0-10):

• Goal achievement
• User need addressed
• Forward progress
• Clarity & coherence
• Appropriate tone
• Information accuracy
• Handling objections
• Building rapport
• Conversation flow
• Strategic effectiveness

Left: A successful trajectory with detailed strengths. Right: A pruned branch showing weaknesses and why it failed.

DTS supports two evaluation modes:

Comparative mode (default):

Input: [Strategy A, Strategy B, Strategy C] (siblings)
Output: A=7.5, B=6.0, C=4.5 (forced ranking with 1.5-point gaps)

Absolute mode:

Input: Strategy A (evaluated alone)
Output: 3 judges → [7.2, 6.8, 8.1] → Median: 7.2

Use scoring_mode="comparative" when you need the best single answer. Use scoring_mode="absolute" when filtering many branches quickly.

sequenceDiagram
    participant User
    participant FE as Frontend (HTML/JS)
    participant API as FastAPI WebSocket
    participant ENG as DTS Engine
    participant LLM as OpenRouter/OpenAI
    participant RES as Firecrawl + Tavily

    User->>FE: Configure & Start Search
    FE->>API: WebSocket Connect
    API->>ENG: Initialize DTSEngine

    opt Deep Research Enabled
        ENG->>RES: Research Query
        RES-->>ENG: Domain Context
    end

    loop For Each Round
        ENG->>LLM: Generate Strategies
        LLM-->>ENG: N Strategies

        loop For Each Branch
            ENG->>LLM: Generate User Intents
            ENG->>LLM: Simulate Conversation
            ENG->>LLM: Judge Trajectory (3x)
        end

        ENG->>API: Emit Events (node_added, scored, pruned)
        API-->>FE: Stream Updates
        FE->>User: Update Visualization
    end

    ENG->>API: Complete with Best Path
    FE->>User: Show Results

1. OpenRouter (recommended): openrouter.ai/keys

   • Works with 100+ models (GPT-4, Claude, Gemini, open-source)
   • Pay-per-token, no subscriptions
   • Set OPENAI_BASE_URL=https://openrouter.ai/api/v1

2. Firecrawl: firecrawl.dev

   • Required for deep_research=True
   • Handles JavaScript-rendered pages, anti-bot bypass

3. Tavily: tavily.com

   • Required for deep_research=True
   • AI-optimized web search API

Note: Deep Research features require both Firecrawl and Tavily keys. Without them, set deep_research=False in your configuration.

Note: The default model minimax/minimax-m2.1 is chosen for its excellent price/performance ratio. You can use any OpenRouter-compatible model for any task by overriding the model parameters in your configuration.

Requires Python 3.11+

# Clone the repository
git clone https://github.com/MVPandey/DTS.git
cd DTS

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

Create a .env file in the project root (see .env.example):

# Required - API Keys
OPENROUTER_API_KEY=sk-or-v1-your-openrouter-key
TAVILY_API_KEY=tvly-your-tavily-key
FIRECRAWL_API_KEY=fc-your-firecrawl-key

# LLM models (minimax-m2.1 recommended for price/performance)
FAST_LLM=openrouter:minimax/minimax-m2.1
SMART_LLM=openrouter:minimax/minimax-m2.1
STRATEGIC_LLM=openrouter:minimax/minimax-m2.1
SMART_TOKEN_LIMIT=32000

# Deep research parameters
DEEP_RESEARCH_BREADTH=3
DEEP_RESEARCH_DEPTH=2
DEEP_RESEARCH_CONCURRENCY=4

# Report comprehensiveness (higher = more detailed)
TOTAL_WORDS=12000
MAX_SUBTOPICS=8
MAX_ITERATIONS=5
MAX_SEARCH_RESULTS=10
REPORT_FORMAT=markdown

Model flexibility: You can use any model available on OpenRouter for any task. The default minimax/minimax-m2.1 offers an excellent balance of cost and capability, but feel free to swap in anthropic/claude-3-opus, openai/gpt-4o, or any other model for specific phases.

The easiest way to start the server:

Unix/macOS/Linux:

# Start with Docker
./scripts/start_server.sh

# Start in development mode (hot reload)
./scripts/start_server.sh --dev

# Start without Docker (local Python)
./scripts/start_server.sh --local

# Stop the server
./scripts/start_server.sh --down

Windows:

REM Start with Docker
scripts\start_server.bat

REM Start in development mode (hot reload)
scripts\start_server.bat --dev

REM Start without Docker (local Python)
scripts\start_server.bat --local

REM Stop the server
scripts\start_server.bat --down

# Start the server (production)
docker-compose up -d dts-server

# Start in development mode with hot reload
docker-compose --profile dev up dts-server-dev

# View logs
docker-compose logs -f

# Stop and remove containers
docker-compose down

# Rebuild after code changes
docker-compose up -d --build dts-server

# Activate virtual environment
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Set PYTHONPATH
export PYTHONPATH=$(pwd)  # Windows: set PYTHONPATH=%cd%

# Start server
uvicorn backend.api.server:app --host localhost --port 8000 --reload --log-level info

The project includes VSCode launch configurations for debugging:

1. Open the project in VSCode
2. Go to Run and Debug (Ctrl+Shift+D / Cmd+Shift+D)
3. Select a configuration from the dropdown:

4. Press F5 or click the green play button

VSCode Launch Configuration (.vscode/launch.json):

{
  "name": "Debug DTS Server",
  "type": "debugpy",
  "request": "launch",
  "module": "uvicorn",
  "args": [
    "backend.api.server:app",
    "--host", "localhost",
    "--port", "8000",
    "--reload",
    "--log-level", "info"
  ],
  "env": { "PYTHONPATH": "${workspaceFolder}" },
  "envFile": "${workspaceFolder}/.env"
}

For programmatic use without the web interface:

import asyncio
from backend.core.dts import DTSConfig, DTSEngine
from backend.llm.client import LLM
from backend.utils.config import config

async def main():
    # Initialize LLM client (uses minimax-m2.1 by default for best price/performance)
    llm = LLM(
        api_key=config.openrouter_api_key,
        base_url=config.openai_base_url,
        model="minimax/minimax-m2.1",  # Or any OpenRouter model
    )

    # Configure the search
    dts_config = DTSConfig(
        goal="Negotiate a 15% discount on enterprise software",
        first_message="Hi, I'd like to discuss our renewal pricing.",
        init_branches=6,           # 6 initial strategies
        turns_per_branch=5,        # 5-turn conversations
        user_intents_per_branch=3, # Fork into 3 user persona variants
        user_variability=False,    # Use fixed "healthily critical" persona (default)
        scoring_mode="comparative", # Force-rank siblings
        prune_threshold=6.5,       # Minimum score to survive
        deep_research=True,        # Enable research context
    )

    # Run the search
    engine = DTSEngine(llm=llm, config=dts_config)
    result = await engine.run(rounds=2)

    # Output results
    print(f"Best Score: {result.best_score:.1f}/10")
    print(f"Branches Explored: {len(result.all_nodes)}")
    print(f"Branches Pruned: {result.pruned_count}")

    # Save full results
    result.save_json("output.json")

if __name__ == "__main__":
    asyncio.run(main())

Or run the included example:

python main.py

Once the server is running:

DTS integrates GPT-Researcher to gather domain context before generating strategies.

graph LR
    A[Goal + First Message] --> B[Query Distillation]
    B --> C[Web Search via Tavily]
    C --> D[Page Scraping via Firecrawl]
    D --> E[Research Report]
    E --> F[Strategy Generation]
    E --> G[Judge Evaluation]

1. Query Distillation: LLM converts goal into focused research query
2. Web Search: Tavily finds relevant sources
3. Scraping: Firecrawl extracts content (handles JS, anti-bot)
4. Report: GPT-Researcher synthesizes findings
5. Injection: Report fed to strategy generator and judges

DTSConfig(
    goal="Explain quantum computing to a 10-year-old",
    first_message="What's quantum computing?",
    deep_research=True,  # Enable research
)

Research results are cached by SHA256(goal + first_message) in .cache/research/. Subsequent runs with the same inputs skip the research phase.

Cost Note: Deep research adds external API costs beyond LLM tokens. Monitor usage during development.

URL: ws://localhost:8000/ws

{
  "type": "start_search",
  "config": {
    "goal": "Your conversation goal",
    "first_message": "Opening user message",
    "init_branches": 6,
    "turns_per_branch": 5,
    "user_intents_per_branch": 3,
    "scoring_mode": "comparative",
    "prune_threshold": 6.5,
    "rounds": 2,
    "deep_research": false
  }
}

The server emits real-time events as the search progresses:

FastAPI auto-generates OpenAPI docs at http://localhost:8000/docs.

The included frontend (frontend/index.html) provides real-time visualization:

Configuration panel with basic parameters, deep research toggle, and user variability settings

• Configuration Panel: Set goal, branches, turns, rounds, and model settings
• Deep Research Toggle: Enable/disable GPT-Researcher integration
• Reasoning Mode: Auto-detect or manually set reasoning effort
• User Variability Toggle: Switch between fixed "healthily critical" persona (default) or diverse user personas for robustness testing
• Live Progress: Watch strategies generate and branches expand
• Branch Browser: Explore all trajectories with full transcripts
• Score Details: See individual judge scores and critiques
• Token Tracking: Monitor costs by phase and model
• Export: Download results as JSON

1. Start the API server:

   uvicorn backend.api.server:app --port 8000

2. Open frontend/index.html in a browser

3. Configure your search and click "Start Search"

DTS/
├── backend/
│   ├── api/
│   │   ├── server.py          # FastAPI WebSocket server
│   │   └── schemas.py         # Pydantic request/response models
│   ├── core/
│   │   ├── dts/
│   │   │   ├── engine.py      # Main DTSEngine orchestrator
│   │   │   ├── config.py      # DTSConfig dataclass
│   │   │   ├── types.py       # Core data models
│   │   │   ├── tree.py        # DialogueTree structure
│   │   │   ├── aggregator.py  # Median vote aggregation
│   │   │   ├── retry.py       # Shared retry logic
│   │   │   └── components/
│   │   │       ├── generator.py   # Strategy & intent generation
│   │   │       ├── simulator.py   # Conversation rollouts
│   │   │       ├── evaluator.py   # Multi-judge scoring
│   │   │       └── researcher.py  # GPT-Researcher integration
│   │   └── prompts.py         # All prompt templates
│   ├── llm/
│   │   ├── client.py          # OpenAI-compatible LLM client
│   │   ├── types.py           # Message, Completion, Usage
│   │   ├── errors.py          # Custom exception types
│   │   └── tools.py           # Tool calling support
│   ├── services/
│   │   └── search_service.py  # API service layer
│   └── utils/
│       └── config.py          # Pydantic settings from .env
├── frontend/
│   ├── index.html             # Single-page visualizer
│   └── app.js                 # WebSocket client & UI logic
├── scripts/
│   ├── start_server.sh        # Unix/macOS start script
│   └── start_server.bat       # Windows start script
├── gpt-researcher/            # GPT-Researcher submodule
├── .vscode/
│   └── launch.json            # VSCode debug configurations
├── Dockerfile                 # Container image definition
├── docker-compose.yml         # Multi-container orchestration
├── main.py                    # Example script
├── pyproject.toml             # Project metadata & dependencies
├── CLAUDE.md                  # Developer instructions
└── README.md                  # This file

# Strategy for conversation approach
Strategy(tagline="Empathetic Listener", description="Validate feelings first...")

# User persona for intent forking
UserIntent(
    id="skeptic",
    label="Skeptical Questioner",
    emotional_tone="skeptical",
    cognitive_stance="questioning",
)

# Tree node with conversation state
DialogueNode(
    id="uuid",
    strategy=Strategy(...),
    user_intent=UserIntent(...),
    messages=[Message(role="user", content="...")],
    stats=NodeStats(aggregated_score=7.2),
)

# Final result
DTSRunResult(
    best_node_id="uuid",
    best_score=8.1,
    best_messages=[...],
    all_nodes=[...],
    token_usage={...},
)

DTS is token-intensive due to parallel exploration. A typical run involves:

Cost Formula ≈ Branches × Intents × Turns × (Generation + 3×Judging)

Example: 6 branches × 3 intents × 5 turns × 4 calls = 360 LLM calls

1. Raise prune_threshold: Aggressively cull bad branches (6.5 → 7.0)
2. Set keep_top_k: Hard cap on survivors (e.g., keep_top_k=3)
3. Lower turns_per_branch: Shorter conversations (5 → 3)
4. Disable forking: Set user_intents_per_branch=1
5. Use fast models: Cheaper models for simulation, expensive for judging
6. Fewer rounds: Start with 1 round, add more if needed

The engine tracks tokens per phase and model:

result = await engine.run(rounds=2)
print(result.token_usage)
# {
#   "total_input_tokens": 45000,
#   "total_output_tokens": 12000,
#   "total_cost_usd": 0.42,
#   "by_phase": {...},
#   "by_model": {...},
# }

Enable verbose logging:

DEBUG=true
LOGGING_LEVEL=DEBUG

If you don't have Firecrawl/Tavily keys:

DTSConfig(
    goal="...",
    first_message="...",
    deep_research=False,  # Disable research
)

Apache License 2.0 — see LICENSE.

Contributions welcome! Please read CONTRIBUTING.md before submitting PRs.

• GPT-Researcher for deep research capabilities
• OpenRouter for multi-model API access
• Firecrawl for web scraping
• Tavily for AI-optimized search