Skip to main content
Version: 0.36.0

Your First Discovery

Time: about 15 minutes to set up. The run itself takes longer: with the default 100 exploration steps, expect roughly 30 minutes to a couple of hours, depending on the number of steps, your warehouse and your model. (A first 100-step run on the public e-commerce demo data took about 52 minutes.) Prerequisites: DecisionBox running (Quick Start), a data warehouse with data, an LLM API key

This guide walks through creating a project, configuring it, running a discovery, and understanding the results.

Step 1: Create a Project​

Open http://localhost:3000 and click New Project.

Basics​

  • Name: A descriptive name (e.g., "Online Store Analytics")
  • Domain: The playbook closest to your business. Built in: E-Commerce, Gaming, Social Network and Digital Analytics Property.
  • Category: The sub-type within that playbook. E-Commerce: Multi-Category Store. Gaming: Match-3, Idle / Incremental, Casual / Hyper-Casual. Social Network: Content Sharing. Digital Analytics Property: Content & Media Property, E-commerce Storefront, Lead Generation Site.

The domain and category decide which analysis areas and prompts the run uses. For example, an e-commerce store gets conversion, revenue and retention analysis (shared by every store) plus product performance and session behavior analysis (specific to multi-category stores). A match-3 game gets churn, engagement and monetization analysis plus level difficulty and booster usage.

Data Warehouse​

Select your warehouse provider and enter connection details:

BigQuery:

  • Project ID: Your GCP project ID (e.g., my-gcp-project)
  • Location: Dataset location (e.g., us-central1, US, us-east5)
  • Datasets: Comma-separated dataset names (e.g., analytics, features)

Amazon Redshift (Serverless):

  • Workgroup Name: Your Redshift Serverless workgroup (e.g., default-workgroup)
  • Database: Database name (e.g., dev)
  • Region: AWS region (e.g., us-east-1)

Filter (optional): If your warehouse has data from multiple apps/tenants, set a filter:

  • Filter Field: Column name (e.g., app_id)
  • Filter Value: Your app's ID (e.g., my-app-123)

The agent will add WHERE app_id = 'my-app-123' to all queries.

AI Provider​

Select your LLM provider:

ProviderAuth
Claude (Anthropic)API key
OpenAIAPI key
OllamaNone (local)
Vertex AIGCP ADC
AWS BedrockAWS credentials

Then pick or type the model ID your provider gives you. Model lists change often, so the field accepts free text; see Configuring LLM Providers for each provider's ID format.

For provider-specific configuration (Vertex AI project ID, Bedrock region), additional fields appear when you select the provider.

Click Create Project.

Step 2: Credentials​

The project-creation wizard already collected the credentials it needs and stored them as project-scoped secrets:

  • llm-credentials — your LLM API key
  • warehouse-credentials — your warehouse SA key / DB password (skipped when the warehouse uses the cluster's cloud identity)
  • embedding-credentials — your embedding provider key (required — schema indexing and /ask both depend on it)
  • blurb-llm-credentials — only present when you configured a separate per-project Blurb LLM

To rotate any of these later, open Settings → Data Warehouse or AI Provider and re-save the field.

Go to Settings → Profile tab.

The profile tells the AI about your business: what you sell, to whom, and the targets you track. This context noticeably improves insight quality.

For an e-commerce store, the sections are:

  • Business Information: what the store is and who it serves
  • Product Catalog: the categories and products you sell
  • Shipping and Payment: how orders are delivered and paid for
  • Target KPIs: targets such as conversion rate, average order value and 30-day retention

The form is generated from the playbook's JSON Schema, so each domain has its own fields (a match-3 game, for example, asks about boosters and in-app purchase packages).

Step 4: Run Discovery​

First, build the schema index. A new project is not indexed automatically: open the project and click Build schema index in the schema index panel. (If your warehouse is large, review and narrow the table list first, so only the tables you need are indexed.) DecisionBox then reads each table and writes a short plain-language description of it. The Run discovery button shows "Waiting for schema index..." and stays disabled until the index is Ready. See Schema Indexing.

Then click Run discovery in the top bar. The dropdown lets you configure:

  • Exploration steps: More steps = more comprehensive (default: 100). You set the number; a run's length grows with it.
  • Minimum steps: Stops the AI from finishing too early (default: 60% of the exploration steps).
  • Run All Areas: Runs every analysis area in the playbook (for e-commerce: conversion, revenue, retention, and so on)
  • Select areas: Run only specific analysis areas.

Click Run All Areas to start.

What Happens During a Run​

The live progress panel shows each step:

  1. Schema Discovery — The agent lists your warehouse tables and reads their schemas
  2. Exploration — The AI writes SQL queries, executes them, analyzes results, and writes more queries based on what it finds. Each step shows:
    • What the AI is thinking
    • The SQL query it wrote
    • Row count and execution time
    • Whether the query was auto-fixed (SQL errors are retried with corrections)
  3. Analysis — For each analysis area (conversion, revenue, etc.), the AI reviews the exploration results and generates insights
  4. Validation — Two AI agents check insights against the data: a verifier checks each claim against the rows it came from, and a refuter looks for evidence that the insight is wrong. Each checked insight gets a verdict (confirmed, supported, partial, unverifiable or rejected). Not every insight is always checked, so look for the verdict.
  5. Recommendations — From the insights that qualify (by default, confirmed or supported, plus any that weren't checked), the AI writes specific action steps, which are then checked the same way

Step 5: Review Results​

Click the completed discovery card to see the full results.

Insights​

Insights are displayed in a table with:

  • Insight: The specific finding (e.g., "Late deliveries cut the average review score from 4.2 to 2.5")
  • Severity: Critical, High, Medium, or Low
  • Area: Which analysis area found this (conversion, revenue, etc.)
  • Validation: The verdict from the checks
  • Affected: How many customers, orders or other records are affected
  • Confidence: How confident the AI is

Click an insight name to see:

  • Full description with exact numbers
  • Key indicators (specific metrics)
  • Risk score and confidence
  • Validation results (the verdict, and the verifier's and refuter's work)
  • The actual SQL queries that discovered this insight

Recommendations​

Each recommendation includes:

  • Title: Specific action (e.g., "Coach sellers on reliable delivery before improving product listings")
  • Priority: 1 is the highest
  • Expected Impact: The metric to move and the estimated improvement
  • Target Segment: Who it applies to, how many, and the confidence
  • Action Steps: Numbered implementation steps
  • Related insights: Which insights this recommendation is built on
  • Validation: The verdict from the same two checks

Feedback​

Use the thumbs up/down buttons on insights and recommendations, and add a comment saying why when something is off. Your feedback is saved with the run, and later runs receive it as context.

Step 6: Run Again​

After reviewing results and giving feedback, run another discovery. Each run starts from what earlier runs found: it is told about previous insights and recommendations so it doesn't simply repeat them unless the situation has changed, and it looks for new patterns instead.

Next Steps​