Query Generation Modes

Choose between speed/cost and quality/insights based on your needs.

Overview

AIQ provides four query generation modes that let you balance cost, speed, and quality:

Mode	Cost (20 queries)	Quality	Speed	Use Case
Simple	$0	60/100	Instant	Quick testing, budget-conscious
Default ✅	$0.10	85/100	5-10s	Production use (current)
Rich 🚧	$0.12	95/100	10-15s	Quality validated (Phase 2)
Premium 🔮	$0.25	100/100	20-30s	Multi-perspective (Phase 3)

Current Status

Default mode is currently available. Rich and Premium modes coming in Phase 2-3.

Mode 1: Simple (Template-Based)

What It Is

Template-based generation using 100+ pre-built query patterns. No LLM calls = zero cost.

Features

• ✅ 100+ pre-built query templates
• ✅ Simple variable substitution
• ✅ Journey stage categorization
• ✅ Zero LLM cost
• ✅ Instant generation

Example

await generateQueries({
  industry: 'Healthcare IT',
  count: 20,
  mode: 'simple',
});

// Template: "How to solve {problem} in {context}"
// Generated: "How to solve customer churn in SaaS companies"

When to Use

• Quick testing without budget
• Need predictable, consistent results
• Don't need creative/contextual queries

Limitations

• Generic queries (not brand-specific)
• Limited creativity
• No URL content analysis

---

Mode 2: Default (AI-Powered) ✅

What It Is

Current production mode - Uses Claude Sonnet 4.5 for natural language generation with URL content analysis.

Features

• ✅ Claude Sonnet 4.5 (high-quality LLM)
• ✅ URL content analysis (web crawling)
• ✅ Natural, conversational queries
• ✅ Industry-specific terminology
• ✅ Persona & journey stage targeting
• ✅ Problem-focused mode

Example

await generateQueries({
  industry: 'Healthcare IT',
  url: 'https://example.com',
  count: 20,
  mode: 'default', // Current behavior (can omit - it's default)
});

// Generated queries:
// ✅ "What are the biggest challenges in healthcare digital transformation?"
// ✅ "How do hospitals implement electronic health records securely?"
// ✅ "Which HIPAA-compliant cloud platforms should healthcare providers use?"

When to Use

• Production query generation (recommended for most users)
• Need high-quality, natural queries
• Have URL content to analyze
• Standard budget ($0.10 per 20 queries)

Cost

~$0.005 per query (Claude generation + optional URL crawl)

Current behavior: All existing code uses this mode automatically (no changes needed).

---

Mode 3: Rich (Quality Validated) 🚧

Coming Soon

Status: Phase 2 implementation (Weeks 3-4)

What It Is

All Default mode features plus automatic quality validation using the Query Quality Framework.

Features

• ✅ All Default mode features
• ✅ Complexity scoring (word count, specificity, natural language)
• ✅ Conversationality scoring (question structure, tone)
• ✅ Intent classification (6 patterns)
• ✅ Citation prediction via grounded search
• ✅ Filters queries scoring < 65/100
• ✅ Intent diversity enforcement (60%+ across batch)

Quality Validation Process

1. Generate queries (Claude)
2. Score each query:
   ├─ Complexity: 30% weight
   ├─ Conversationality: 30% weight
   ├─ Intent: 20% weight
   └─ Answerability: 20% weight
3. Filter: Keep only queries ≥ 65/100
4. Re-generate if batch fails diversity check
5. Return validated queries

Example

await generateQueries({
  industry: 'Healthcare IT',
  count: 20,
  mode: 'rich', // Quality validated
});

// REJECTED (keyword search):
// ❌ "best healthcare software 2025"
//    Score: 42/100 (too generic, keyword pattern)

// ACCEPTED (conversational, complex):
// ✅ "What should a 200-bed hospital consider when choosing an EHR system?"
//    Score: 87/100 (complex, conversational, problem-focused)

When to Use

• Need guaranteed high-quality queries
• Consultant-facing dashboards
• Willing to pay 20% more for validation
• Zero tolerance for keyword searches

Cost

~$0.006 per query (generation + validation)

---

Mode 4: Premium (Multi-Perspective) 🔮

Coming Soon

Status: Phase 3 implementation (Weeks 5-6)

What It Is

All Rich mode features plus multi-perspective testing across 5 different AI personas with segmented insights.

5 Testing Perspectives

1. Standard - Balanced, general search behavior
2. Commercial - Buying intent, product research
3. Technical - Developer focus (Stack Overflow, docs, GitHub)
4. Educational - Learning intent (tutorials, courses, how-tos)
5. Competitive - Market research (competitor sites, analyst reports)

Features

• ✅ All Rich mode features
• ✅ Multi-perspective testing (5 AI personas)
• ✅ Segmented visibility predictions
• ✅ Per-perspective citation analysis
• ✅ Actionable recommendations by segment

Example Insights

await generateQueries({
  industry: 'Healthcare IT',
  count: 20,
  mode: 'premium',
});

// Query: "How do I implement SSO for a SaaS application?"
//
// Visibility Prediction:
//   ✅ Technical: Will cite brand (docs visible)
//   ✅ Educational: Will cite brand (tutorials visible)
//   ❌ Commercial: Won't cite brand (vendor pages missing)
//   ❌ Standard: Won't cite brand (general SEO weak)
//
// Recommendation:
//   "Strong technical presence but weak commercial visibility.
//    Add pricing/ROI content to capture buying-intent searches."

When to Use

• Strategic client analysis
• Need segmented insights (which audiences see us?)
• High-value engagements ($100k+ clients)
• Want to identify specific content gaps

Cost

~$0.0125 per query (generation + validation + 5 perspectives)

---

Choosing the Right Mode

Decision Tree

Need zero cost?
  └─> Simple

Need natural, contextual queries?
  ├─> Need guaranteed quality?
  │     ├─> Need segmented insights?
  │     │     └─> Premium (enterprise)
  │     └─> Rich (growth tier)
  └─> Default (standard)

By Use Case

Use Case	Recommended Mode
Quick testing	Simple
Production use	Default
Consultant dashboards	Rich
Strategic analysis	Premium
Budget-conscious	Simple
High-quality needed	Rich
Enterprise clients	Premium

By Organization Tier

Tier	Default Mode	Allowed Modes
Free	Simple	Simple only
Starter	Default	Simple, Default
Growth	Rich	Simple, Default, Rich
Enterprise	Premium	All modes

---

Cost Comparison

Per 20 Queries

Mode	No URL	With URL	URL Adds
Simple	$0	$0	-
Default	$0.10	$0.14	+$0.04
Rich	$0.12	$0.16	+$0.04
Premium	$0.25	$0.29	+$0.04

Per 100 Queries

Mode	No URL	With URL
Simple	$0	$0
Default	$0.50	$0.70
Rich	$0.60	$0.80
Premium	$1.25	$1.45

---

API Usage

Simple Mode

import { generateQueries } from '@/app/actions/query-generation';

const result = await generateQueries({
  industry: 'Healthcare IT',
  focus: 'EHR implementation',
  count: 20,
  mode: 'simple',
});

// Cost: $0
// Speed: Instant
// Quality: 60/100

Default Mode (Current)

const result = await generateQueries({
  industry: 'Healthcare IT',
  url: 'https://example.com',
  count: 20,
  mode: 'default', // Or omit - it's the default
});

// Cost: ~$0.10
// Speed: 5-10s
// Quality: 85/100

Rich Mode (Phase 2)

const result = await generateQueries({
  industry: 'Healthcare IT',
  url: 'https://example.com',
  count: 20,
  mode: 'rich',
  qualityThreshold: 65, // Optional: override default
});

// Returns quality report
console.log(result.qualityReport);
// {
//   averageScore: 82,
//   passRate: 90, // 90% passed validation
//   intentDiversity: 75,
//   rejectedCount: 2,
// }

// Cost: ~$0.12
// Speed: 10-15s
// Quality: 95/100

Premium Mode (Phase 3)

const result = await generateQueries({
  industry: 'Healthcare IT',
  url: 'https://example.com',
  count: 20,
  mode: 'premium',
});

// Returns perspective insights
console.log(result.perspectiveInsights);
// {
//   standard: { visibilityRate: 60% },
//   commercial: { visibilityRate: 40% },
//   technical: { visibilityRate: 85% },
//   educational: { visibilityRate: 70% },
//   competitive: { visibilityRate: 55% },
// }

// Cost: ~$0.25
// Speed: 20-30s
// Quality: 100/100

---

Backward Compatibility

Existing code continues to work unchanged:

// No mode parameter = uses 'default' automatically
await generateQueries({
  industry: 'Healthcare IT',
  count: 20,
});

Opt-in to new modes:

// Explicitly choose mode
await generateQueries({
  industry: 'Healthcare IT',
  count: 20,
  mode: 'rich', // Opt-in to quality validation
});

---

Related Features

• Grounded Search - Citation prediction used in Rich/Premium modes
• Multi-Perspective Testing - Premium mode feature
• Query Execution - Run generated queries

---

Technical Details

• Mode Definitions: types/query-generation-modes.ts
• Current Implementation: app/actions/query-generation.ts
• Phase 2 Framework: lib/services/query-quality-service.ts (coming soon)
• Phase 3 Framework: lib/services/multi-perspective-testing-service.ts (planned)