@thanh01.pmt/domain-kit 0.1.0

package/dist/concepts/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/concepts/conceptResolver.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Concept resolution — maps keywords to Master Tree concepts.\n *\n * Ported from knowledge-tree/resolve_concepts.py\n * Uses ULO/CIO/SIO-aware matching:\n *   - SIO keywords → match against concept.keywords (tech-specific)\n *   - CIO keywords → match against concept.description (mechanism)\n *   - ULO keywords → match against concept.ulo (what/why, tech-independent)\n *\n * Fallback: keyword overlap matching when embeddings unavailable.\n *\n * NOTE: This module requires sentence-transformers Python package for embeddings.\n * In pure TypeScript mode, it falls back to keyword overlap matching.\n */\n\nimport { createLlmClient, llmChatJson, type LlmClientConfig } from '../utils/llmClient';\nimport type { Keyword } from '../extractors/keywordExtractor';\n\nexport interface ResolvedConcept {\n  keyword: string;\n  source: string;\n  depth: 'ulo' | 'cio' | 'sio';\n  concept_codes: string[];\n  matches: ConceptMatch[];\n  override?: boolean;\n  rechecked?: boolean;\n}\n\nexport interface ConceptMatch {\n  code: string;\n  name: string;\n  description: string;\n  keywords: string;\n  ulo?: string;\n  cio?: string;\n  score: number;\n  matched_level: 'ulo' | 'cio' | 'sio';\n  method: 'embedding' | 'keyword_overlap';\n}\n\nexport interface ProposedConcept {\n  keyword: string;\n  source: string;\n  depth: 'ulo' | 'cio' | 'sio';\n  reason: string;\n  best_match?: ConceptMatch;\n}\n\nexport interface ResolveConceptsResult {\n  resolved: ResolvedConcept[];\n  proposed: ProposedConcept[];\n  summary: {\n    total_keywords: number;\n    resolved_count: number;\n    proposed_count: number;\n    search_mode: string;\n  };\n}\n\nexport interface ResolveConceptsOptions {\n  keywords: Keyword[];\n  goal: string;\n  embeddings?: Record<string, { embedding?: number[]; name?: string; description?: string; keywords?: string; ulo?: string; cio?: string }>;\n  /** Pre-computed depth from conceptEscalator — overrides inferDepthFromSource */\n  depthOverrides?: Map<string, 'ulo' | 'cio' | 'sio'>;\n  topK?: number;\n  threshold?: number;\n  llmConfig?: LlmClientConfig;\n}\n\n// Source-based thresholds\nconst SOURCE_THRESHOLDS: Record<string, number> = {\n  docstring: 0.45,\n  readme_description: 0.45,\n  readme: 0.50,\n  type_declaration: 0.55,\n  function_signature: 0.55,\n  import: 0.60,\n  property_wrapper: 0.55,\n  error_handling: 0.60,\n  config: 0.60,\n  framework_usage: 0.45,\n};\n\nconst DEFAULT_THRESHOLD = 0.55;\n\nfunction cosineSimilarity(a: number[], b: number[]): number {\n  if (!a.length || !b.length || a.length !== b.length) return 0;\n  let dot = 0, normA = 0, normB = 0;\n  for (let i = 0; i < a.length; i++) {\n    dot += a[i] * b[i];\n    normA += a[i] * a[i];\n    normB += b[i] * b[i];\n  }\n  if (normA === 0 || normB === 0) return 0;\n  return dot / (Math.sqrt(normA) * Math.sqrt(normB));\n}\n\n/**\n * ULO/CIO/SIO-aware keyword overlap scoring.\n * Matches against different concept fields based on depth level.\n */\nfunction uloCioAwareScore(\n  query: string,\n  depth: 'ulo' | 'cio' | 'sio',\n  conceptData: { keywords?: string; description?: string; ulo?: string; cio?: string },\n): number {\n  const queryTerms = new Set(query.toLowerCase().split(/\\s+/));\n\n  // Choose which fields to match based on depth\n  let targetText = '';\n  if (depth === 'sio') {\n    // SIO: match against keywords (tech-specific terms)\n    targetText = conceptData.keywords || '';\n  } else if (depth === 'cio') {\n    // CIO: match against description + cio (mechanism)\n    targetText = [conceptData.description || '', conceptData.cio || ''].join(' ');\n  } else {\n    // ULO: match against ulo + description (what/why, tech-independent)\n    targetText = [conceptData.ulo || '', conceptData.description || ''].join(' ');\n  }\n\n  const targetTerms = new Set(targetText.toLowerCase().split(/\\s+/));\n  if (!queryTerms.size || !targetTerms.size) return 0;\n\n  let overlap = 0;\n  for (const t of queryTerms) {\n    if (targetTerms.has(t)) overlap++;\n  }\n  return Math.min(overlap / queryTerms.size, 1.0);\n}\n\n\nfunction inferFieldsFromGoal(goal: string): string[] {\n  const goalLower = goal.toLowerCase();\n  const fieldKeywords: Record<string, string[]> = {\n    ASE: ['algorithm', 'software', 'programming', 'code', 'develop', 'build', 'app'],\n    DAI: ['data', 'database', 'storage', 'query', 'sql', 'analytics'],\n    CSN: ['network', 'protocol', 'server', 'client', 'api', 'http'],\n    HCI: ['user', 'interface', 'ui', 'ux', 'interaction', 'design'],\n    MOB: ['mobile', 'ios', 'android', 'swift', 'kotlin', 'flutter'],\n    WEB: ['web', 'html', 'css', 'javascript', 'react', 'vue'],\n  };\n\n  const matched: string[] = [];\n  for (const [code, keywords] of Object.entries(fieldKeywords)) {\n    if (keywords.some(kw => goalLower.includes(kw))) matched.push(code);\n  }\n  return matched.length > 0 ? matched : ['ASE'];\n}\n\n/**\n * Infer depth from keyword source and context.\n */\nfunction inferDepthFromSource(source: string): 'ulo' | 'cio' | 'sio' {\n  const uloSources = ['docstring', 'readme', 'readme_description', 'framework_usage'];\n  const cioSources = ['type_declaration', 'function_signature', 'config'];\n\n  if (uloSources.includes(source)) return 'ulo';\n  if (cioSources.includes(source)) return 'cio';\n  return 'sio';\n}\n\n/**\n * Resolve keywords to concepts using ULO/CIO/SIO-aware matching.\n */\nexport async function resolveConcepts(\n  options: ResolveConceptsOptions,\n): Promise<ResolveConceptsResult> {\n  const { keywords, goal, embeddings, depthOverrides, topK = 3, threshold = DEFAULT_THRESHOLD, llmConfig } = options;\n\n  const relevantFields = inferFieldsFromGoal(goal);\n  const resolved: ResolvedConcept[] = [];\n  const proposed: ProposedConcept[] = [];\n  const hasEmbeddings = Object.keys(embeddings || {}).length > 0 &&\n    Object.values(embeddings || {}).some(d => d.embedding && d.embedding.length > 0);\n  let search_mode = hasEmbeddings ? 'embedding' : 'keyword_overlap';\n\n  const concepts = embeddings || {};\n\n  for (const kwData of keywords) {\n    const keyword = kwData.keyword;\n    const source = kwData.source;\n    // Use escalator's depth override if available, else infer from source\n    const depth = depthOverrides?.get(keyword) || inferDepthFromSource(source);\n\n    // Search concepts via ULO/CIO/SIO-aware matching\n    const scored: ConceptMatch[] = [];\n    for (const [code, data] of Object.entries(concepts)) {\n      const conceptKeywords = data.keywords || '';\n      const conceptDesc = data.description || '';\n      const conceptUlo = (data as Record<string, unknown>).ulo as string | undefined;\n      const conceptCio = (data as Record<string, unknown>).cio as string | undefined;\n\n      // Primary: ULO/CIO-aware score based on depth level\n      const awareScore = uloCioAwareScore(keyword, depth, {\n        keywords: conceptKeywords,\n        description: conceptDesc,\n        ulo: conceptUlo,\n        cio: conceptCio,\n      });\n\n      // Fallback: broad keyword overlap across all fields\n      const queryTerms = new Set(keyword.toLowerCase().split(/\\s+/));\n      const allTerms = new Set([\n        ...conceptKeywords.toLowerCase().split(/\\s+/),\n        ...conceptDesc.toLowerCase().split(/\\s+/),\n        ...(conceptUlo || '').toLowerCase().split(/\\s+/),\n        ...(conceptCio || '').toLowerCase().split(/\\s+/),\n      ].filter(Boolean));\n      let overlapCount = 0;\n      for (const t of queryTerms) { if (allTerms.has(t)) overlapCount++; }\n      const fallbackScore = queryTerms.size > 0 ? Math.min(overlapCount / queryTerms.size, 1.0) : 0;\n\n      // Use the higher score, but track which method won\n      const usedAware = awareScore >= fallbackScore;\n      const finalScore = usedAware ? awareScore : fallbackScore;\n\n      if (finalScore > 0) {\n        scored.push({\n          code,\n          name: data.name || code,\n          description: conceptDesc,\n          keywords: conceptKeywords,\n          ulo: conceptUlo,\n          cio: conceptCio,\n          score: finalScore,\n          matched_level: usedAware ? depth : 'sio',\n          method: hasEmbeddings && data.embedding && data.embedding.length > 0 ? 'embedding' : 'keyword_overlap',\n        });\n      }\n    }\n\n    scored.sort((a, b) => b.score - a.score);\n    const topMatches = scored.slice(0, topK);\n\n    if (topMatches.length === 0) {\n      proposed.push({\n        keyword,\n        source,\n        depth,\n        reason: 'No matches in Master Tree',\n      });\n      continue;\n    }\n\n    const effThreshold = SOURCE_THRESHOLDS[source] || threshold;\n    const topMatch = topMatches[0];\n\n    if (topMatch.score >= effThreshold) {\n      resolved.push({\n        keyword,\n        source,\n        depth,\n        concept_codes: topMatches.filter(m => m.score >= effThreshold).map(m => m.code),\n        matches: topMatches,\n      });\n    } else {\n      proposed.push({\n        keyword,\n        source,\n        depth,\n        best_match: topMatch,\n        reason: `Low confidence (${topMatch.score.toFixed(2)} < ${effThreshold})`,\n      });\n    }\n  }\n\n  return {\n    resolved,\n    proposed,\n    summary: {\n      total_keywords: keywords.length,\n      resolved_count: resolved.length,\n      proposed_count: proposed.length,\n      search_mode,\n    },\n  };\n}\n"]}

package/dist/concepts/index.d.cts

@@ -0,0 +1,79 @@
+import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.cjs';
+import { K as Keyword } from '../keywordExtractor-zPAz2isq.cjs';
+import '../parsers/index.cjs';
+
+/**
+ * Concept resolution — maps keywords to Master Tree concepts.
+ *
+ * Ported from knowledge-tree/resolve_concepts.py
+ * Uses ULO/CIO/SIO-aware matching:
+ *   - SIO keywords → match against concept.keywords (tech-specific)
+ *   - CIO keywords → match against concept.description (mechanism)
+ *   - ULO keywords → match against concept.ulo (what/why, tech-independent)
+ *
+ * Fallback: keyword overlap matching when embeddings unavailable.
+ *
+ * NOTE: This module requires sentence-transformers Python package for embeddings.
+ * In pure TypeScript mode, it falls back to keyword overlap matching.
+ */
+
+interface ResolvedConcept {
+    keyword: string;
+    source: string;
+    depth: 'ulo' | 'cio' | 'sio';
+    concept_codes: string[];
+    matches: ConceptMatch[];
+    override?: boolean;
+    rechecked?: boolean;
+}
+interface ConceptMatch {
+    code: string;
+    name: string;
+    description: string;
+    keywords: string;
+    ulo?: string;
+    cio?: string;
+    score: number;
+    matched_level: 'ulo' | 'cio' | 'sio';
+    method: 'embedding' | 'keyword_overlap';
+}
+interface ProposedConcept {
+    keyword: string;
+    source: string;
+    depth: 'ulo' | 'cio' | 'sio';
+    reason: string;
+    best_match?: ConceptMatch;
+}
+interface ResolveConceptsResult {
+    resolved: ResolvedConcept[];
+    proposed: ProposedConcept[];
+    summary: {
+        total_keywords: number;
+        resolved_count: number;
+        proposed_count: number;
+        search_mode: string;
+    };
+}
+interface ResolveConceptsOptions {
+    keywords: Keyword[];
+    goal: string;
+    embeddings?: Record<string, {
+        embedding?: number[];
+        name?: string;
+        description?: string;
+        keywords?: string;
+        ulo?: string;
+        cio?: string;
+    }>;
+    /** Pre-computed depth from conceptEscalator — overrides inferDepthFromSource */
+    depthOverrides?: Map<string, 'ulo' | 'cio' | 'sio'>;
+    topK?: number;
+    threshold?: number;
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Resolve keywords to concepts using ULO/CIO/SIO-aware matching.
+ */
+declare function resolveConcepts(options: ResolveConceptsOptions): Promise<ResolveConceptsResult>;
+
+export { type ConceptMatch, type ProposedConcept, type ResolveConceptsOptions, type ResolveConceptsResult, type ResolvedConcept, resolveConcepts };

package/dist/concepts/index.d.ts

@@ -0,0 +1,79 @@
+import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.js';
+import { K as Keyword } from '../keywordExtractor-CKaXqSku.js';
+import '../parsers/index.js';
+
+/**
+ * Concept resolution — maps keywords to Master Tree concepts.
+ *
+ * Ported from knowledge-tree/resolve_concepts.py
+ * Uses ULO/CIO/SIO-aware matching:
+ *   - SIO keywords → match against concept.keywords (tech-specific)
+ *   - CIO keywords → match against concept.description (mechanism)
+ *   - ULO keywords → match against concept.ulo (what/why, tech-independent)
+ *
+ * Fallback: keyword overlap matching when embeddings unavailable.
+ *
+ * NOTE: This module requires sentence-transformers Python package for embeddings.
+ * In pure TypeScript mode, it falls back to keyword overlap matching.
+ */
+
+interface ResolvedConcept {
+    keyword: string;
+    source: string;
+    depth: 'ulo' | 'cio' | 'sio';
+    concept_codes: string[];
+    matches: ConceptMatch[];
+    override?: boolean;
+    rechecked?: boolean;
+}
+interface ConceptMatch {
+    code: string;
+    name: string;
+    description: string;
+    keywords: string;
+    ulo?: string;
+    cio?: string;
+    score: number;
+    matched_level: 'ulo' | 'cio' | 'sio';
+    method: 'embedding' | 'keyword_overlap';
+}
+interface ProposedConcept {
+    keyword: string;
+    source: string;
+    depth: 'ulo' | 'cio' | 'sio';
+    reason: string;
+    best_match?: ConceptMatch;
+}
+interface ResolveConceptsResult {
+    resolved: ResolvedConcept[];
+    proposed: ProposedConcept[];
+    summary: {
+        total_keywords: number;
+        resolved_count: number;
+        proposed_count: number;
+        search_mode: string;
+    };
+}
+interface ResolveConceptsOptions {
+    keywords: Keyword[];
+    goal: string;
+    embeddings?: Record<string, {
+        embedding?: number[];
+        name?: string;
+        description?: string;
+        keywords?: string;
+        ulo?: string;
+        cio?: string;
+    }>;
+    /** Pre-computed depth from conceptEscalator — overrides inferDepthFromSource */
+    depthOverrides?: Map<string, 'ulo' | 'cio' | 'sio'>;
+    topK?: number;
+    threshold?: number;
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Resolve keywords to concepts using ULO/CIO/SIO-aware matching.
+ */
+declare function resolveConcepts(options: ResolveConceptsOptions): Promise<ResolveConceptsResult>;
+
+export { type ConceptMatch, type ProposedConcept, type ResolveConceptsOptions, type ResolveConceptsResult, type ResolvedConcept, resolveConcepts };

package/dist/concepts/index.mjs

@@ -0,0 +1,4 @@
+import '../chunk-KMYENICQ.mjs';
+export { resolveConcepts } from '../chunk-KNDBODUQ.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/concepts/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}