dag-semantic-matcher

1. Intent Extraction

• Parse natural language task descriptions
• Identify required capabilities and constraints
• Extract implicit requirements and preferences

2. Semantic Matching

• Compare task requirements to skill capabilities
• Handle synonyms, related terms, and concepts
• Score matches based on semantic similarity

3. Candidate Generation

• Generate initial candidate skill list
• Apply filters based on constraints
• Expand search when needed

4. Match Explanation

• Explain why skills match or don't match
• Identify capability gaps
• Suggest alternatives for partial matches

```typescript

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 {

// 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);

}

```

```typescript

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 {

// 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,

};

}

```

```typescript

// Capability synonyms and related terms

const capabilitySynonyms: Map = 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;

}

```

```typescript

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;

}

```

```typescript

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(' ');

}

```

```typescript

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;

}

```

```yaml

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]

```

• Registry: Queries dag-skill-registry for skill catalog
• Ranking: Passes candidates to dag-capability-ranker
• Consumers: dag-graph-builder for node skill assignment
• Feedback: Performance data from dag-pattern-learner

1. Expand Queries: Use synonyms to improve recall
2. Weight Capabilities: Not all matches are equal
3. Explain Matches: Transparency builds trust
4. Track Performance: Learn from successful matches
5. Handle Ambiguity: Ask for clarification when unsure

---

Natural language in. Perfect skills out. Semantic understanding.