Text2SQL - Natural Language to SQL

Recipes are curated fragment bundles for specific industries and use cases. Each recipe provides copy-paste-ready code that teaches Text2SQL the terminology, rules, and query patterns for that domain.

Available Recipes

Recipe	Domain	Key Focus
Build an Agent (SQLite Store)	Setup	Streaming chat agent with `SqliteContextStore` for durable threads
E-Commerce	Retail, Orders, Customers	Revenue metrics, customer analytics, cart abandonment
Finance	Banking, Investments	Loan analysis, portfolio metrics, compliance
Healthcare	Clinical, Patient Data	HIPAA compliance, patient cohorts, clinical metrics

How Recipes Work

Each recipe provides:

Domain Terms - Vocabulary specific to the industry (AOV, NPL, LOS, etc.)
Guardrails - Safety rules and compliance requirements
Hints - Default behaviors and assumptions
Examples - Sample question → SQL pairs for pattern matching
Clarifications - When to ask users for more information

Quick Start

Copy a recipe's fragment bundle into your code:

import {
  clarification,
  example,
  guardrail,
  term,
  hint,
} from '@deepagents/context';

const recipe = [
  term('AOV', 'Average Order Value - total revenue divided by number of orders'),
  hint('Active customer = ordered in last 90 days unless specified'),
  // ... more fragments from the recipe
];

Set ...recipe on your ContextEngine for chat(), or append it to the low-level toSql({ fragments }) helper when you need direct SQL generation.

Combining Recipes

You can combine multiple recipes for cross-domain applications:

const combinedRecipe = [
  // E-commerce terms
  term('AOV', 'Average Order Value'),
  term('LTV', 'Lifetime Value'),

  // Finance terms for payment processing
  term('chargeback', 'disputed transaction returned to customer'),
  term('settlement', 'transfer of funds from processor to merchant'),
];

Customizing Recipes

Recipes are starting points. Customize them for your specific needs:

// Override a term with your company's definition
term('active customer', 'customer who purchased in the last 60 days'),

// Add company-specific guardrails
guardrail({
  rule: 'Never query the legacy_orders table',
  reason: 'Deprecated - use orders_v2 instead',
}),

// Add examples for your specific schema
example({
  question: 'show me VIP customers',
  answer: 'SELECT * FROM customers WHERE tier = \'VIP\' ORDER BY lifetime_value DESC',
}),

Creating Your Own Recipe

There is no public text2sql.teach() helper in the current API. Start with a recipe array, test it against your schema, and refine it manually:

const customRecipe = [
  term('active customer', 'customer who purchased in the last 60 days'),
  hint('Exclude sandbox accounts from all customer metrics'),
];

If you are generating synthetic training data, pass the final fragment array as the teachings option to SchemaSynthesizer.