@kiyeonjeon21/datacontext 0.2.0 → 0.3.0

package/src/knowledge/store.ts

@@ -12,8 +12,10 @@ import type {
   TableDescription,
   QueryExample,
   BusinessRule,
+  BusinessTerm,
   KnowledgeEntry,
   ColumnDescription,
+  TermCategory,
 } from './types.js';
 import { generateId, createKnowledgeMeta } from './types.js';
 
@@ -321,6 +323,177 @@ export class KnowledgeStore {
     return rule;
   }
 
+  // ============ Business Terms (Glossary) ============
+
+  /**
+   * Get all business terms
+   */
+  getBusinessTerms(): BusinessTerm[] {
+    return this.data?.businessTerms ?? [];
+  }
+
+  /**
+   * Get active business terms
+   */
+  getActiveTerms(): BusinessTerm[] {
+    return this.data?.businessTerms.filter(t => t.isActive) ?? [];
+  }
+
+  /**
+   * Get business terms for specific tables
+   */
+  getTermsForTables(tables: string[]): BusinessTerm[] {
+    return this.data?.businessTerms.filter(
+      term => term.isActive && 
+        (term.appliesTo?.tables?.some(t => tables.includes(t)) ?? true)
+    ) ?? [];
+  }
+
+  /**
+   * Find terms matching a query (by term name or synonyms)
+   */
+  findMatchingTerms(query: string): BusinessTerm[] {
+    const lowerQuery = query.toLowerCase();
+    return this.data?.businessTerms.filter(term => {
+      if (!term.isActive) return false;
+      // Check term name
+      if (term.term.toLowerCase().includes(lowerQuery)) return true;
+      if (lowerQuery.includes(term.term.toLowerCase())) return true;
+      // Check synonyms
+      for (const syn of term.synonyms) {
+        if (syn.toLowerCase().includes(lowerQuery)) return true;
+        if (lowerQuery.includes(syn.toLowerCase())) return true;
+      }
+      return false;
+    }) ?? [];
+  }
+
+  /**
+   * Add a business term
+   */
+  async addBusinessTerm(
+    term: string,
+    definition: string,
+    options: {
+      synonyms?: string[];
+      sqlExpression?: string;
+      appliesTo?: { tables?: string[]; columns?: string[] };
+      category?: TermCategory;
+      examples?: string[];
+      schemaHash?: string;
+    } = {}
+  ): Promise<BusinessTerm> {
+    if (!this.data) {
+      throw new Error('Knowledge store not loaded');
+    }
+
+    // Check for duplicates
+    const existing = this.data.businessTerms.find(
+      t => t.term.toLowerCase() === term.toLowerCase()
+    );
+    if (existing) {
+      // Update existing term
+      return this.updateBusinessTerm(existing.id, {
+        definition,
+        ...options,
+      });
+    }
+
+    const schemaHash = options.schemaHash ?? this.data.schemaHash;
+    const newTerm: BusinessTerm = {
+      ...createKnowledgeMeta('user', schemaHash),
+      type: 'business_term',
+      term,
+      synonyms: options.synonyms ?? [],
+      definition,
+      sqlExpression: options.sqlExpression,
+      appliesTo: options.appliesTo,
+      category: options.category,
+      examples: options.examples,
+      isActive: true,
+    };
+
+    this.data.businessTerms.push(newTerm);
+    await this.save();
+    return newTerm;
+  }
+
+  /**
+   * Add multiple business terms at once
+   */
+  async addBusinessTerms(terms: BusinessTerm[]): Promise<BusinessTerm[]> {
+    if (!this.data) {
+      throw new Error('Knowledge store not loaded');
+    }
+
+    const added: BusinessTerm[] = [];
+    for (const term of terms) {
+      // Check for duplicates
+      const existingIndex = this.data.businessTerms.findIndex(
+        t => t.term.toLowerCase() === term.term.toLowerCase()
+      );
+      
+      if (existingIndex >= 0) {
+        // Update existing
+        this.data.businessTerms[existingIndex] = {
+          ...this.data.businessTerms[existingIndex],
+          ...term,
+          updatedAt: new Date().toISOString(),
+        };
+        added.push(this.data.businessTerms[existingIndex]);
+      } else {
+        // Add new
+        this.data.businessTerms.push(term);
+        added.push(term);
+      }
+    }
+
+    await this.save();
+    return added;
+  }
+
+  /**
+   * Update a business term
+   */
+  async updateBusinessTerm(
+    id: string,
+    updates: Partial<Omit<BusinessTerm, 'id' | 'type' | 'createdAt'>>
+  ): Promise<BusinessTerm> {
+    if (!this.data) {
+      throw new Error('Knowledge store not loaded');
+    }
+
+    const index = this.data.businessTerms.findIndex(t => t.id === id);
+    if (index < 0) {
+      throw new Error(`Business term not found: ${id}`);
+    }
+
+    const updated: BusinessTerm = {
+      ...this.data.businessTerms[index],
+      ...updates,
+      updatedAt: new Date().toISOString(),
+    };
+
+    this.data.businessTerms[index] = updated;
+    await this.save();
+    return updated;
+  }
+
+  /**
+   * Delete a business term
+   */
+  async deleteBusinessTerm(id: string): Promise<void> {
+    if (!this.data) {
+      throw new Error('Knowledge store not loaded');
+    }
+
+    const index = this.data.businessTerms.findIndex(t => t.id === id);
+    if (index >= 0) {
+      this.data.businessTerms.splice(index, 1);
+      await this.save();
+    }
+  }
+
   // ============ Utilities ============
 
   /**
@@ -351,15 +524,60 @@ export class KnowledgeStore {
       }
     }
 
+    for (const bt of this.data.businessTerms ?? []) {
+      if (bt.schemaHash !== currentSchemaHash) {
+        outdated.push(bt);
+      }
+    }
+
     return outdated;
   }
 
   /**
    * Build context for AI from knowledge store
+   * 
+   * Generates a comprehensive context string including:
+   * - Table descriptions and column details
+   * - Business glossary/terms with SQL mappings
+   * - Business rules and conditions
+   * - Query examples
+   * 
+   * @param tables - Tables to include context for
+   * @param userQuery - Optional user query to match relevant terms
+   * @returns Formatted context string for AI
    */
-  buildContext(tables: string[]): string {
+  buildContext(tables: string[], userQuery?: string): string {
     const parts: string[] = [];
 
+    // Add business glossary FIRST (helps AI understand terminology)
+    const terms = userQuery 
+      ? this.findMatchingTerms(userQuery)
+      : this.getTermsForTables(tables);
+    
+    if (terms.length > 0) {
+      parts.push('## Business Glossary');
+      parts.push('Use these term definitions when interpreting user requests:');
+      parts.push('');
+      for (const term of terms) {
+        let termInfo = `**${term.term}**`;
+        if (term.synonyms.length > 0) {
+          termInfo += ` (also: ${term.synonyms.join(', ')})`;
+        }
+        parts.push(termInfo);
+        parts.push(`  Definition: ${term.definition}`);
+        if (term.sqlExpression) {
+          parts.push(`  SQL: \`${term.sqlExpression}\``);
+        }
+        if (term.appliesTo?.tables?.length) {
+          parts.push(`  Applies to: ${term.appliesTo.tables.join(', ')}`);
+        }
+        if (term.examples?.length) {
+          parts.push(`  Example usage: "${term.examples[0]}"`);
+        }
+        parts.push('');
+      }
+    }
+
     // Add table descriptions
     for (const tableName of tables) {
       const desc = this.getTableDescription(tableName);
@@ -389,10 +607,11 @@ export class KnowledgeStore {
     const rules = this.getActiveRulesForTables(tables);
     if (rules.length > 0) {
       parts.push('## Business Rules');
+      parts.push('Always apply these rules when querying:');
       for (const rule of rules) {
-        parts.push(`- ${rule.name}: ${rule.description}`);
+        parts.push(`- **${rule.name}**: ${rule.description}`);
         if (rule.condition) {
-          parts.push(`  Condition: ${rule.condition}`);
+          parts.push(`  SQL condition: \`${rule.condition}\``);
         }
       }
       parts.push('');
@@ -402,11 +621,14 @@ export class KnowledgeStore {
     const examples = this.getQueryExamplesForTables(tables);
     if (examples.length > 0) {
       parts.push('## Query Examples');
+      parts.push('Reference these verified examples:');
       for (const ex of examples.slice(0, 5)) { // Limit to 5 examples
-        parts.push(`Intent: ${ex.intent}`);
-        parts.push(`SQL: ${ex.sql}`);
+        parts.push(`Intent: "${ex.intent}"`);
+        parts.push('```sql');
+        parts.push(ex.sql);
+        parts.push('```');
         if (ex.explanation) {
-          parts.push(`Explanation: ${ex.explanation}`);
+          parts.push(`Note: ${ex.explanation}`);
         }
         parts.push('');
       }
@@ -424,6 +646,7 @@ export class KnowledgeStore {
       tableDescriptions: [],
       queryExamples: [],
       businessRules: [],
+      businessTerms: [],
     };
   }
 
@@ -439,9 +662,10 @@ export class KnowledgeStore {
     }>;
     queryExamples: QueryExample[];
     businessRules: BusinessRule[];
+    businessTerms: BusinessTerm[];
   } {
     if (!this.data) {
-      return { tables: [], queryExamples: [], businessRules: [] };
+      return { tables: [], queryExamples: [], businessRules: [], businessTerms: [] };
     }
 
     return {
@@ -453,6 +677,7 @@ export class KnowledgeStore {
       })),
       queryExamples: this.data.queryExamples,
       businessRules: this.data.businessRules,
+      businessTerms: this.data.businessTerms ?? [],
     };
   }
 }

package/src/knowledge/types.ts

@@ -92,8 +92,50 @@ export interface BusinessRule extends KnowledgeMeta {
   priority: number;
 }
 
+/** Term category for classification */
+export type TermCategory = 'status' | 'time' | 'money' | 'entity' | 'metric' | 'filter' | 'custom';
+
+/**
+ * Business term / glossary entry
+ * 
+ * Represents a domain-specific term and its SQL meaning.
+ * Used to translate natural language into accurate SQL conditions.
+ * 
+ * @example
+ * {
+ *   term: "활성 사용자",
+ *   synonyms: ["active user", "활성화된 사용자"],
+ *   definition: "status 컬럼이 1인 사용자",
+ *   sqlExpression: "status = 1",
+ *   appliesTo: { tables: ["users"] },
+ *   category: "status"
+ * }
+ */
+export interface BusinessTerm extends KnowledgeMeta {
+  type: 'business_term';
+  /** Business term (natural language) */
+  term: string;
+  /** Alternative names/synonyms for this term */
+  synonyms: string[];
+  /** Human-readable definition */
+  definition: string;
+  /** SQL expression to apply when this term is used */
+  sqlExpression?: string;
+  /** Tables/columns this term applies to */
+  appliesTo?: {
+    tables?: string[];
+    columns?: string[];
+  };
+  /** Category for grouping */
+  category?: TermCategory;
+  /** Usage examples */
+  examples?: string[];
+  /** Whether this term is active */
+  isActive: boolean;
+}
+
 /** Union type for all knowledge entries */
-export type KnowledgeEntry = TableDescription | QueryExample | BusinessRule;
+export type KnowledgeEntry = TableDescription | QueryExample | BusinessRule | BusinessTerm;
 
 /** Complete knowledge data structure */
 export interface KnowledgeData {
@@ -111,6 +153,8 @@ export interface KnowledgeData {
   queryExamples: QueryExample[];
   /** Business rules */
   businessRules: BusinessRule[];
+  /** Business terms / glossary */
+  businessTerms: BusinessTerm[];
 }
 
 /** Generate a unique ID */