dag-semantic-matcher

interface TaskDescription {
  raw: string;              // Original natural language
  intent: Intent;           // Extracted intent
  capabilities: string[];   // Required capabilities
  constraints: Constraint[];
  context: TaskContext;
}

interface Intent {
  primary: string;          // Main action/goal
  secondary: string[];      // Supporting actions
  domain: string;           // Problem domain
}

interface MatchResult {
  skillId: string;
  score: number;            // 0-1 overall match score
  breakdown: {
    intentMatch: number;
    capabilityMatch: number;
    constraintMatch: number;
  };
  explanation: string;
  gaps: string[];           // Missing capabilities
}

async function matchTaskToSkills(
  task: TaskDescription,
  registry: SkillRegistry
): Promise<MatchResult[]> {
  // Extract intent from raw description
  const intent = await extractIntent(task.raw);
  task.intent = intent;

  // Generate candidates based on capabilities
  const candidates = generateCandidates(task, registry);

  // Score each candidate
  const scored = await Promise.all(
    candidates.map(skill => scoreMatch(task, skill))
  );

  // Sort by score descending
  return scored.sort((a, b) => b.score - a.score);
}

interface IntentExtraction {
  action: string;           // What to do
  object: string;           // What to do it to
  modifiers: string[];      // How to do it
  domain: string;           // Problem area
}

async function extractIntent(
  description: string
): Promise<Intent> {
  // Common action patterns
  const actionPatterns = {
    create: ['build', 'create', 'make', 'generate', 'write'],
    analyze: ['analyze', 'examine', 'review', 'inspect', 'check'],
    modify: ['update', 'change', 'edit', 'fix', 'refactor'],
    validate: ['validate', 'verify', 'test', 'ensure', 'confirm'],
    transform: ['convert', 'transform', 'translate', 'migrate'],
  };

  // Domain patterns
  const domainPatterns = {
    code: ['code', 'function', 'class', 'module', 'api'],
    data: ['data', 'database', 'schema', 'query', 'model'],
    docs: ['documentation', 'readme', 'guide', 'tutorial'],
    test: ['test', 'spec', 'coverage', 'assertion'],
    security: ['security', 'vulnerability', 'auth', 'permission'],
  };

  const normalizedDesc = description.toLowerCase();

  // Find primary action
  let primaryAction = 'unknown';
  for (const [action, patterns] of Object.entries(actionPatterns)) {
    if (patterns.some(p => normalizedDesc.includes(p))) {
      primaryAction = action;
      break;
    }
  }

  // Find domain
  let domain = 'general';
  for (const [d, patterns] of Object.entries(domainPatterns)) {
    if (patterns.some(p => normalizedDesc.includes(p))) {
      domain = d;
      break;
    }
  }

  return {
    primary: primaryAction,
    secondary: [],
    domain,
  };
}

// Capability synonyms and related terms
const capabilitySynonyms: Map<string, string[]> = new Map([
  ['code-review', ['review code', 'check code', 'code analysis', 'code quality']],
  ['testing', ['test', 'spec', 'unit test', 'integration test', 'qa']],
  ['documentation', ['docs', 'readme', 'guide', 'tutorial', 'api docs']],
  ['refactoring', ['refactor', 'clean up', 'improve', 'restructure']],
  ['security', ['security audit', 'vulnerability scan', 'pen test']],
]);

function semanticSimilarity(
  term1: string,
  term2: string
): number {
  // Exact match
  if (term1 === term2) return 1.0;

  // Check synonyms
  for (const [canonical, synonyms] of capabilitySynonyms) {
    const allTerms = [canonical, ...synonyms];
    if (allTerms.includes(term1) && allTerms.includes(term2)) {
      return 0.9;
    }
  }

  // Substring match
  if (term1.includes(term2) || term2.includes(term1)) {
    return 0.7;
  }

  // Word overlap
  const words1 = new Set(term1.split(/\s+/));
  const words2 = new Set(term2.split(/\s+/));
  const intersection = new Set([...words1].filter(x => words2.has(x)));
  const union = new Set([...words1, ...words2]);
  const jaccard = intersection.size / union.size;

  return jaccard * 0.6;
}

function scoreMatch(
  task: TaskDescription,
  skill: SkillMetadata
): MatchResult {
  // Intent match
  const intentScore = scoreIntentMatch(task.intent, skill);

  // Capability match
  const capScore = scoreCapabilityMatch(
    task.capabilities,
    skill.capabilities
  );

  // Constraint match
  const constraintScore = scoreConstraintMatch(
    task.constraints,
    skill
  );

  // Combined score (weighted)
  const score = (
    intentScore * 0.3 +
    capScore * 0.5 +
    constraintScore * 0.2
  );

  // Find capability gaps
  const gaps = findCapabilityGaps(task.capabilities, skill.capabilities);

  return {
    skillId: skill.id,
    score,
    breakdown: {
      intentMatch: intentScore,
      capabilityMatch: capScore,
      constraintMatch: constraintScore,
    },
    explanation: generateExplanation(task, skill, score),
    gaps,
  };
}

function scoreCapabilityMatch(
  required: string[],
  available: Capability[]
): number {
  if (required.length === 0) return 0.5;

  let totalScore = 0;
  for (const req of required) {
    let bestMatch = 0;
    for (const cap of available) {
      const similarity = semanticSimilarity(req, cap.name);
      const adjustedScore = similarity * cap.confidence;
      bestMatch = Math.max(bestMatch, adjustedScore);
    }
    totalScore += bestMatch;
  }

  return totalScore / required.length;
}

function generateExplanation(
  task: TaskDescription,
  skill: SkillMetadata,
  score: number
): string {
  const parts: string[] = [];

  if (score >= 0.8) {
    parts.push(`Strong match for "${task.intent.primary}" tasks.`);
  } else if (score >= 0.6) {
    parts.push(`Good match with some capability alignment.`);
  } else if (score >= 0.4) {
    parts.push(`Partial match - may need supplementary skills.`);
  } else {
    parts.push(`Weak match - consider alternatives.`);
  }

  // Explain what matched
  const matchedCaps = skill.capabilities
    .filter(cap =>
      task.capabilities.some(req =>
        semanticSimilarity(req, cap.name) > 0.6
      )
    )
    .map(cap => cap.name);

  if (matchedCaps.length > 0) {
    parts.push(`Matches: ${matchedCaps.join(', ')}`);
  }

  return parts.join(' ');
}

function expandQuery(
  task: TaskDescription
): TaskDescription {
  const expanded = { ...task };
  const additionalCaps: string[] = [];

  // Add synonyms for required capabilities
  for (const cap of task.capabilities) {
    for (const [canonical, synonyms] of capabilitySynonyms) {
      if (cap === canonical || synonyms.includes(cap)) {
        additionalCaps.push(canonical, ...synonyms);
      }
    }
  }

  expanded.capabilities = [
    ...new Set([...task.capabilities, ...additionalCaps]),
  ];

  return expanded;
}

matchResults:
  query: "Review this TypeScript code for bugs and security issues"

  extractedIntent:
    primary: analyze
    secondary: [validate]
    domain: code

  requiredCapabilities:
    - code-review
    - bug-detection
    - security-analysis

  matches:
    - skillId: code-reviewer
      score: 0.92
      breakdown:
        intentMatch: 0.95
        capabilityMatch: 0.90
        constraintMatch: 0.90
      explanation: "Strong match for 'analyze' tasks. Matches: code-review, bug-detection"
      gaps: []

    - skillId: security-auditor
      score: 0.78
      breakdown:
        intentMatch: 0.80
        capabilityMatch: 0.85
        constraintMatch: 0.70
      explanation: "Good match with security focus. Matches: security-analysis"
      gaps: [bug-detection]

    - skillId: typescript-expert
      score: 0.65
      breakdown:
        intentMatch: 0.70
        capabilityMatch: 0.60
        constraintMatch: 0.65
      explanation: "Partial match - specialized in TypeScript but general purpose"
      gaps: [security-analysis]