Teachings Generator

import { TeachingsGenerator } from '@deepagents/text2sql/synthesis';

const generator = new TeachingsGenerator(adapter, {
  context: 'E-commerce database tracking orders and inventory'
});

const teachings = await generator.generate();
// Returns 3-10 high-value teachables (terms, hints, guardrails, etc.)

interface TeachingsGeneratorOptions {
  /** Additional domain context to guide generation */
  context?: string;
  /** Model to use for generation */
  model?: AgentModel;
}

// Without context - relies purely on schema
const teachings = await new TeachingsGenerator(adapter).generate();

// With context - generates more relevant teachings
const teachings = await new TeachingsGenerator(adapter, {
  context: `Our database tracks e-commerce orders.
  - Active customers are those who ordered in the last 90 days
  - We exclude test accounts with email ending in @test.com
  - Revenue should exclude cancelled and refunded orders`
}).generate();

import { groq } from '@ai-sdk/groq';

const teachings = await new TeachingsGenerator(adapter, {
  context: 'Healthcare patient records',
  model: groq('llama-3.3-70b-versatile')
}).generate();

// Retries up to 3 times (default)
const teachings = await generator.generate();

// Custom retry count
const teachings = await generator.generate(5);

import {
  TeachingsGenerator,
  SchemaSynthesizer,
  PersonaGenerator,
  toPairs
} from '@deepagents/text2sql/synthesis';

// Generate teachings
const teachingsGen = new TeachingsGenerator(adapter, {
  context: 'SaaS subscription and usage tracking database'
});
const teachings = await teachingsGen.generate();

// Generate personas
const personaGen = new PersonaGenerator(adapter, { count: 5 });
const personas = await personaGen.generate();

// Generate pairs with teachings and personas
const pairs = await toPairs(new SchemaSynthesizer(adapter, {
  count: 10,
  complexity: 'medium',
  personas: personas,
  teachings: teachings  // Guides SQL generation
}));

[
  {
    type: 'guardrail',
    rule: 'Avoid unbounded scans on orders table - always include date range filter',
    reason: 'Performance - orders table contains millions of rows',
    action: 'Ask user for timeframe if not specified'
  },
  {
    type: 'hint',
    text: 'Exclude test accounts with email ending in @test.com from all metrics'
  },
  {
    type: 'term',
    name: 'active customer',
    definition: 'customer who placed an order in the last 90 days'
  },
  {
    type: 'clarification',
    when: 'user asks for "revenue"',
    ask: 'Do you want gross revenue or net revenue (excluding refunds/cancellations)?',
    reason: 'Revenue can mean different things for different analyses'
  },
  {
    type: 'quirk',
    issue: 'order_total includes shipping and tax',
    workaround: 'Use order_subtotal for product revenue only'
  },
  {
    type: 'example',
    question: 'show top selling products',
    answer: `SELECT p.product_name, COUNT(oi.order_id) as order_count
FROM products p
JOIN order_items oi ON p.product_id = oi.product_id
JOIN orders o ON oi.order_id = o.order_id
WHERE o.status NOT IN ('cancelled', 'refunded')
  AND o.created_at >= CURRENT_DATE - INTERVAL '90 days'
GROUP BY p.product_id, p.product_name
ORDER BY order_count DESC
LIMIT 10`,
    note: 'Excludes cancelled/refunded orders and focuses on recent history'
  }
]

// Automatic: generates and applies teachings
await text2sql.teach(
  'Our database tracks e-commerce orders. Active customers ordered in last 90 days.'
);

// Manual: generate teachings separately
const generator = new TeachingsGenerator(adapter, {
  context: 'E-commerce database'
});
const teachings = await generator.generate();

// Apply manually
text2sql.instruct(...teachings);

import {
  TeachingsGenerator,
  PersonaGenerator,
  SchemaSynthesizer,
  DepthEvolver,
  BreadthEvolver,
  toPairs
} from '@deepagents/text2sql/synthesis';

// 1. Generate teachings
const teachingsGen = new TeachingsGenerator(adapter, {
  context: `Financial services database.
  - NPL = non-performing loan (90+ days past due)
  - Always exclude test accounts (account_type = 'test')
  - Basis points: 1% = 100 bps`
});
const teachings = await teachingsGen.generate();

// 2. Generate personas
const personaGen = new PersonaGenerator(adapter, { count: 8 });
const personas = await personaGen.generate();

// 3. Generate base pairs
const basePairs = await toPairs(new SchemaSynthesizer(adapter, {
  count: 5,
  complexity: ['low', 'medium', 'hard'],
  personas: personas,
  teachings: teachings
}));
console.log(`Base pairs: ${basePairs.length}`);

// 4. Evolve in depth (make questions harder)
const depthEvolved = await toPairs(
  new DepthEvolver(basePairs, adapter, {
    count: 2  // 2 harder versions per question
  })
);
console.log(`Depth evolved: ${depthEvolved.length}`);

// 5. Evolve in breadth (paraphrase)
const breadthEvolved = await toPairs(
  new BreadthEvolver([...basePairs, ...depthEvolved], {
    count: 3  // 3 paraphrases per question
  })
);
console.log(`Breadth evolved: ${breadthEvolved.length}`);

const allPairs = [...basePairs, ...depthEvolved, ...breadthEvolved];
console.log(`Total dataset: ${allPairs.length} pairs`);