@hyperfixi/patterns-reference 2.0.0

package/src/api/llm.ts

@@ -0,0 +1,357 @@
+/**
+ * LLM Examples API
+ *
+ * Provides functions to query and manage LLM examples for few-shot learning.
+ */
+
+import { getDatabase } from '../database/connection';
+import type { LLMExample, ConnectionOptions } from '../types';
+
+// =============================================================================
+// Database Row Types
+// =============================================================================
+
+interface LLMExampleRow {
+  id: number;
+  code_example_id: string;
+  language: string;
+  prompt: string;
+  completion: string;
+  quality_score: number;
+  usage_count: number;
+  created_at: string;
+}
+
+// =============================================================================
+// Query Functions
+// =============================================================================
+
+/**
+ * Get LLM examples relevant to a prompt.
+ * Uses text similarity to find relevant patterns.
+ */
+export async function getLLMExamples(
+  prompt: string,
+  language: string = 'en',
+  limit: number = 5,
+  options?: ConnectionOptions
+): Promise<LLMExample[]> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  // Extract keywords from prompt
+  const keywords = extractKeywords(prompt);
+
+  if (keywords.length === 0) {
+    // Return top-quality examples as fallback
+    const rows = db
+      .prepare(
+        `
+      SELECT * FROM llm_examples
+      WHERE language = ?
+      ORDER BY quality_score DESC, usage_count DESC
+      LIMIT ?
+    `
+      )
+      .all(language, limit) as LLMExampleRow[];
+
+    // Track usage
+    trackUsage(
+      db,
+      rows.map(r => r.id)
+    );
+
+    return rows.map(mapRowToLLMExample);
+  }
+
+  // Build LIKE clauses for keyword matching
+  const likeClauses = keywords.map(() => '(prompt LIKE ? OR completion LIKE ?)').join(' OR ');
+  const params = keywords.flatMap(k => [`%${k}%`, `%${k}%`]);
+
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM llm_examples
+    WHERE language = ? AND (${likeClauses})
+    ORDER BY quality_score DESC
+    LIMIT ?
+  `
+    )
+    .all(language, ...params, limit) as LLMExampleRow[];
+
+  // Track usage
+  trackUsage(
+    db,
+    rows.map(r => r.id)
+  );
+
+  return rows.map(mapRowToLLMExample);
+}
+
+/**
+ * Get examples by command type.
+ */
+export async function getExamplesByCommand(
+  command: string,
+  language: string = 'en',
+  limit: number = 5,
+  options?: ConnectionOptions
+): Promise<LLMExample[]> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM llm_examples
+    WHERE language = ? AND completion LIKE ?
+    ORDER BY quality_score DESC
+    LIMIT ?
+  `
+    )
+    .all(language, `%${command}%`, limit) as LLMExampleRow[];
+
+  return rows.map(mapRowToLLMExample);
+}
+
+/**
+ * Get high-quality examples (for few-shot prompts).
+ */
+export async function getHighQualityExamples(
+  language: string = 'en',
+  minQuality: number = 0.8,
+  limit: number = 10,
+  options?: ConnectionOptions
+): Promise<LLMExample[]> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM llm_examples
+    WHERE language = ? AND quality_score >= ?
+    ORDER BY quality_score DESC, usage_count DESC
+    LIMIT ?
+  `
+    )
+    .all(language, minQuality, limit) as LLMExampleRow[];
+
+  return rows.map(mapRowToLLMExample);
+}
+
+/**
+ * Get most used examples (popular).
+ */
+export async function getMostUsedExamples(
+  language: string = 'en',
+  limit: number = 10,
+  options?: ConnectionOptions
+): Promise<LLMExample[]> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM llm_examples
+    WHERE language = ?
+    ORDER BY usage_count DESC, quality_score DESC
+    LIMIT ?
+  `
+    )
+    .all(language, limit) as LLMExampleRow[];
+
+  return rows.map(mapRowToLLMExample);
+}
+
+/**
+ * Build few-shot context for LLM prompting.
+ */
+export async function buildFewShotContext(
+  prompt: string,
+  language: string = 'en',
+  numExamples: number = 3,
+  options?: ConnectionOptions
+): Promise<string> {
+  const examples = await getLLMExamples(prompt, language, numExamples, options);
+
+  if (examples.length === 0) {
+    return '';
+  }
+
+  let context = 'Here are some example hyperscript patterns:\n\n';
+
+  for (const ex of examples) {
+    context += `Task: ${ex.prompt}\n`;
+    context += `Code: ${ex.completion}\n\n`;
+  }
+
+  context += `Now generate hyperscript for: ${prompt}\n`;
+
+  return context;
+}
+
+/**
+ * Add a new LLM example.
+ */
+export async function addLLMExample(
+  example: Omit<LLMExample, 'id' | 'usageCount' | 'createdAt'>,
+  options?: ConnectionOptions
+): Promise<number> {
+  const db = getDatabase(options);
+
+  const result = db
+    .prepare(
+      `
+    INSERT INTO llm_examples
+      (code_example_id, language, prompt, completion, quality_score, usage_count, created_at)
+    VALUES (?, ?, ?, ?, ?, 0, datetime('now'))
+  `
+    )
+    .run(
+      example.patternId,
+      example.language,
+      example.prompt,
+      example.completion,
+      example.qualityScore
+    );
+
+  return result.lastInsertRowid as number;
+}
+
+/**
+ * Update example quality score.
+ */
+export async function updateQualityScore(
+  id: number,
+  qualityScore: number,
+  options?: ConnectionOptions
+): Promise<void> {
+  const db = getDatabase(options);
+
+  db.prepare(
+    `
+    UPDATE llm_examples SET quality_score = ? WHERE id = ?
+  `
+  ).run(qualityScore, id);
+}
+
+/**
+ * Get LLM example statistics.
+ */
+export async function getLLMStats(options?: ConnectionOptions): Promise<{
+  total: number;
+  byLanguage: Record<string, number>;
+  avgQuality: number;
+  totalUsage: number;
+}> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  const totalResult = db.prepare('SELECT COUNT(*) as count FROM llm_examples').get() as {
+    count: number;
+  };
+
+  const byLangResult = db
+    .prepare(
+      `
+    SELECT language, COUNT(*) as count
+    FROM llm_examples
+    GROUP BY language
+  `
+    )
+    .all() as { language: string; count: number }[];
+
+  const avgResult = db.prepare('SELECT AVG(quality_score) as avg FROM llm_examples').get() as {
+    avg: number;
+  };
+
+  const usageResult = db.prepare('SELECT SUM(usage_count) as total FROM llm_examples').get() as {
+    total: number;
+  };
+
+  const byLanguage: Record<string, number> = {};
+  for (const { language, count } of byLangResult) {
+    byLanguage[language] = count;
+  }
+
+  return {
+    total: totalResult.count,
+    byLanguage,
+    avgQuality: avgResult.avg || 0,
+    totalUsage: usageResult.total || 0,
+  };
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Extract keywords from a prompt for matching.
+ */
+function extractKeywords(prompt: string): string[] {
+  const stopWords = new Set([
+    'a',
+    'an',
+    'the',
+    'to',
+    'on',
+    'in',
+    'for',
+    'is',
+    'it',
+    'when',
+    'i',
+    'want',
+    'need',
+    'create',
+    'make',
+    'please',
+    'can',
+    'you',
+    'would',
+    'should',
+    'like',
+    'that',
+    'this',
+    'with',
+    'from',
+  ]);
+
+  return prompt
+    .toLowerCase()
+    .split(/\W+/)
+    .filter(word => word.length > 2 && !stopWords.has(word));
+}
+
+/**
+ * Track usage of examples.
+ */
+function trackUsage(db: any, ids: number[]): void {
+  if (ids.length === 0) return;
+
+  try {
+    const stmt = db.prepare(`
+      UPDATE llm_examples SET usage_count = usage_count + 1 WHERE id = ?
+    `);
+
+    for (const id of ids) {
+      stmt.run(id);
+    }
+  } catch {
+    // Silently ignore tracking errors
+  }
+}
+
+/**
+ * Map database row to LLMExample type.
+ */
+function mapRowToLLMExample(row: LLMExampleRow): LLMExample {
+  return {
+    id: row.id,
+    patternId: row.code_example_id,
+    language: row.language,
+    prompt: row.prompt,
+    completion: row.completion,
+    qualityScore: row.quality_score,
+    usageCount: row.usage_count,
+    createdAt: new Date(row.created_at),
+  };
+}

package/src/api/patterns.ts

@@ -0,0 +1,276 @@
+/**
+ * Pattern Queries API
+ *
+ * Provides functions to query patterns from the database.
+ */
+
+import { getDatabase } from '../database/connection';
+import type {
+  Pattern,
+  SearchOptions,
+  PatternStats,
+  ConnectionOptions,
+  EngineCompat,
+} from '../types';
+
+// =============================================================================
+// Database Row Types
+// =============================================================================
+
+interface CodeExampleRow {
+  id: string;
+  title: string;
+  raw_code: string;
+  description: string | null;
+  feature: string | null;
+  engine: string | null;
+  source_url: string | null;
+  created_at: string;
+}
+
+// =============================================================================
+// Query Functions
+// =============================================================================
+
+/**
+ * Get a pattern by ID.
+ */
+export async function getPatternById(
+  id: string,
+  options?: ConnectionOptions
+): Promise<Pattern | null> {
+  const db = getDatabase({ ...options, readonly: true });
+  const row = db
+    .prepare(
+      `
+    SELECT id, title, raw_code, description, feature, engine, created_at
+    FROM code_examples
+    WHERE id = ?
+  `
+    )
+    .get(id) as CodeExampleRow | undefined;
+
+  return row ? mapRowToPattern(row) : null;
+}
+
+/**
+ * Get patterns by category (feature in hyperscript-lsp schema).
+ */
+export async function getPatternsByCategory(
+  category: string,
+  options?: ConnectionOptions
+): Promise<Pattern[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT id, title, raw_code, description, feature, engine, created_at
+    FROM code_examples
+    WHERE feature = ?
+    ORDER BY title
+  `
+    )
+    .all(category) as CodeExampleRow[];
+
+  return rows.map(mapRowToPattern);
+}
+
+/**
+ * Get patterns by command (extracted from raw_code).
+ */
+export async function getPatternsByCommand(
+  command: string,
+  options?: ConnectionOptions
+): Promise<Pattern[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  // Use word boundary regex in SQLite
+  const rows = db
+    .prepare(
+      `
+    SELECT id, title, raw_code, description, feature, engine, created_at
+    FROM code_examples
+    WHERE raw_code LIKE ?
+    ORDER BY title
+  `
+    )
+    .all(`%${command}%`) as CodeExampleRow[];
+
+  // Filter more precisely in JS (SQLite LIKE is case-insensitive and broad)
+  return rows
+    .filter(row => new RegExp(`\\b${command}\\b`, 'i').test(row.raw_code))
+    .map(mapRowToPattern);
+}
+
+/**
+ * Search patterns by text query.
+ */
+export async function searchPatterns(
+  query: string,
+  searchOptions: SearchOptions = {},
+  connOptions?: ConnectionOptions
+): Promise<Pattern[]> {
+  const db = getDatabase({ ...connOptions, readonly: true });
+  const { limit = 50, offset = 0 } = searchOptions;
+
+  const rows = db
+    .prepare(
+      `
+    SELECT id, title, raw_code, description, feature, engine, created_at
+    FROM code_examples
+    WHERE title LIKE ? OR raw_code LIKE ? OR description LIKE ?
+    ORDER BY title
+    LIMIT ? OFFSET ?
+  `
+    )
+    .all(`%${query}%`, `%${query}%`, `%${query}%`, limit, offset) as CodeExampleRow[];
+
+  return rows.map(mapRowToPattern);
+}
+
+/**
+ * Get all patterns.
+ */
+export async function getAllPatterns(
+  searchOptions: SearchOptions = {},
+  connOptions?: ConnectionOptions
+): Promise<Pattern[]> {
+  const db = getDatabase({ ...connOptions, readonly: true });
+  const { limit = 1000, offset = 0 } = searchOptions;
+
+  const rows = db
+    .prepare(
+      `
+    SELECT id, title, raw_code, description, feature, engine, created_at
+    FROM code_examples
+    ORDER BY title
+    LIMIT ? OFFSET ?
+  `
+    )
+    .all(limit, offset) as CodeExampleRow[];
+
+  return rows.map(mapRowToPattern);
+}
+
+/**
+ * Get pattern statistics.
+ */
+export async function getPatternStats(connOptions?: ConnectionOptions): Promise<PatternStats> {
+  const db = getDatabase({ ...connOptions, readonly: true });
+
+  // Total patterns
+  const patternCount = db.prepare('SELECT COUNT(*) as count FROM code_examples').get() as {
+    count: number;
+  };
+
+  // Total translations
+  const translationCount = db
+    .prepare('SELECT COUNT(*) as count FROM pattern_translations')
+    .get() as {
+    count: number;
+  };
+
+  // By language
+  const byLangRows = db
+    .prepare(
+      `
+    SELECT
+      language,
+      COUNT(*) as count,
+      SUM(verified_parses) as verified_count
+    FROM pattern_translations
+    GROUP BY language
+  `
+    )
+    .all() as { language: string; count: number; verified_count: number }[];
+
+  const byLanguage: Record<string, { count: number; verifiedCount: number }> = {};
+  for (const row of byLangRows) {
+    byLanguage[row.language] = {
+      count: row.count,
+      verifiedCount: row.verified_count,
+    };
+  }
+
+  // By category
+  const byCatRows = db
+    .prepare(
+      `
+    SELECT feature, COUNT(*) as count
+    FROM code_examples
+    WHERE feature IS NOT NULL
+    GROUP BY feature
+  `
+    )
+    .all() as { feature: string; count: number }[];
+
+  const byCategory: Record<string, number> = {};
+  for (const row of byCatRows) {
+    byCategory[row.feature] = row.count;
+  }
+
+  // Average confidence
+  const avgConfResult = db
+    .prepare('SELECT AVG(confidence) as avg FROM pattern_translations WHERE confidence > 0')
+    .get() as { avg: number };
+
+  return {
+    totalPatterns: patternCount.count,
+    totalTranslations: translationCount.count,
+    byLanguage,
+    byCategory,
+    avgConfidence: avgConfResult.avg || 0,
+  };
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Map database row to Pattern type.
+ */
+function mapRowToPattern(row: CodeExampleRow): Pattern {
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description,
+    rawCode: row.raw_code,
+    category: row.feature,
+    primaryCommand: extractPrimaryCommand(row.raw_code),
+    tags: extractTags(row.raw_code),
+    difficulty: inferDifficulty(row.raw_code),
+    engine: (row.engine as EngineCompat) || null,
+    createdAt: new Date(row.created_at),
+  };
+}
+
+/**
+ * Extract primary command from hyperscript code.
+ */
+function extractPrimaryCommand(code: string): string | null {
+  const match = code.match(/^(on|toggle|put|set|add|remove|show|hide|wait|log|send|fetch|call)\b/i);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Extract tags from code.
+ */
+function extractTags(code: string): string[] {
+  const tags: string[] = [];
+  if (code.includes('.')) tags.push('class');
+  if (code.includes('#')) tags.push('id');
+  if (code.includes('on ')) tags.push('event');
+  if (code.includes('fetch')) tags.push('async');
+  if (code.includes('wait')) tags.push('timing');
+  return tags;
+}
+
+/**
+ * Infer difficulty from code complexity.
+ */
+function inferDifficulty(code: string): 'beginner' | 'intermediate' | 'advanced' {
+  const lines = code.split('\n').filter(l => l.trim()).length;
+  if (lines === 1 && !code.includes('then')) return 'beginner';
+  if (lines <= 3) return 'intermediate';
+  return 'advanced';
+}