Files
skillkit/packages/core/src/reasoning/engine.ts
T
Rohit Ghumare 8121c2bbac feat(core): add PageIndex-inspired patterns for skill discovery (#37)
* feat(core): add PageIndex-inspired patterns for skill discovery

Implements patterns from anthropics/knowledge-work-plugins:

Tree Module (packages/core/src/tree/):
- Hierarchical skill taxonomy with 12 categories
- Tree generator from skill tags and metadata
- Tree serializer for JSON/Markdown export
- Related skills graph with 4 relation types

Reasoning Engine (packages/core/src/reasoning/):
- LLM-based tree traversal for skill discovery
- Explainable recommendations with reasoning chains
- Search planning with category relevance scoring
- Result caching with 5-minute TTL

Connectors (packages/core/src/connectors/):
- Tool-agnostic ~~ placeholder system
- 13 connector categories (crm, chat, email, etc.)
- Auto-suggest mappings from MCP config
- Placeholder detection and replacement utilities

Execution Flow (packages/core/src/execution/):
- Step-by-step execution tracking with metrics
- Automatic retry with exponential backoff
- Standalone vs Enhanced mode detection
- Capability-based feature gating

CLI Integration:
- New `skillkit tree` command with --generate, --stats flags
- Enhanced `skillkit recommend` with --explain, --reasoning flags

TUI Integration:
- Tree view mode in Marketplace (toggle with 'v')
- Arrow key navigation for tree hierarchy

* fix: address CodeRabbit and Devin review feedback

- Use os.homedir() instead of process.env.HOME || '~' fallback
  (tree.ts, tree.service.ts, mode.ts)
- Add guard for division by zero in tree stats percentage
- Validate parseInt result for --depth flag
- Fix average stats calculation to use cacheMisses count
- Extract category from data in validateCategoryScore
- Remove unused skillMap field from TreeGenerator
- Make reasoning provider configurable instead of hardcoded
- Add try/catch for tree loading errors in Marketplace
- Handle missing tree nodes during traversal

* fix(execution): clear timeout timer to prevent resource leak

Store setTimeout ID and clear it in finally block when step
completes successfully before timeout. This prevents orphaned
timers from accumulating during long-running applications.
2026-02-02 16:18:13 +00:00

619 lines
17 KiB
TypeScript

import type { SkillSummary, ProjectProfile } from '../recommend/types.js';
import type { SkillTree, TreeNode } from '../tree/types.js';
import { TreeGenerator } from '../tree/generator.js';
import {
type ReasoningConfig,
type TreeSearchQuery,
type TreeSearchResult,
type TreeReasoningResult,
type ExplainedRecommendation,
type ExplainedMatch,
type SearchPlan,
type ReasoningCacheEntry,
type ReasoningEngineStats,
DEFAULT_REASONING_CONFIG,
} from './types.js';
import {
buildSearchPlanPrompt,
buildExplanationPrompt,
extractJsonFromResponse,
validateSearchPlan,
} from './prompts.js';
import { CATEGORY_TAXONOMY } from '../tree/types.js';
const CACHE_TTL_MS = 5 * 60 * 1000;
const MAX_CACHE_SIZE = 100;
export class ReasoningEngine {
private config: ReasoningConfig;
private skillMap: Map<string, SkillSummary> = new Map();
private tree: SkillTree | null = null;
private cache: Map<string, ReasoningCacheEntry> = new Map();
private stats: ReasoningEngineStats = {
totalQueries: 0,
cacheHits: 0,
cacheMisses: 0,
averageProcessingTimeMs: 0,
averageResultsPerQuery: 0,
};
constructor(config?: Partial<ReasoningConfig>) {
this.config = { ...DEFAULT_REASONING_CONFIG, ...config };
}
loadSkills(skills: SkillSummary[]): void {
this.skillMap.clear();
for (const skill of skills) {
this.skillMap.set(skill.name, skill);
}
}
loadTree(tree: SkillTree): void {
this.tree = tree;
}
generateTree(skills: SkillSummary[]): void {
const generator = new TreeGenerator();
this.tree = generator.generateTree(skills);
this.loadSkills(skills);
}
async search(query: TreeSearchQuery): Promise<TreeReasoningResult> {
const startTime = Date.now();
this.stats.totalQueries++;
const cacheKey = this.getCacheKey(query);
const cached = this.getFromCache(cacheKey);
if (cached) {
this.stats.cacheHits++;
return {
query: query.query,
results: cached.results,
exploredPaths: [],
reasoning: 'Retrieved from cache',
totalNodesVisited: 0,
processingTimeMs: Date.now() - startTime,
};
}
this.stats.cacheMisses++;
const maxResults = query.maxResults ?? 10;
const minConfidence = query.minConfidence ?? 30;
const plan = await this.createSearchPlan(query);
const results: TreeSearchResult[] = [];
const exploredPaths: string[][] = [];
let totalNodesVisited = 0;
if (this.tree) {
const traversalResult = await this.traverseTree(query, plan);
results.push(...traversalResult.results);
exploredPaths.push(...traversalResult.exploredPaths);
totalNodesVisited = traversalResult.nodesVisited;
} else {
const fallbackResults = this.fallbackSearch(query);
results.push(...fallbackResults);
}
const filteredResults = results
.filter((r) => r.confidence >= minConfidence)
.sort((a, b) => b.confidence - a.confidence)
.slice(0, maxResults);
const processingTimeMs = Date.now() - startTime;
this.updateStats(processingTimeMs, filteredResults.length);
this.addToCache(cacheKey, filteredResults);
return {
query: query.query,
results: filteredResults,
exploredPaths,
reasoning: this.buildReasoningSummary(plan, filteredResults),
totalNodesVisited,
processingTimeMs,
};
}
async explain(
skill: SkillSummary,
score: number,
profile: ProjectProfile
): Promise<ExplainedRecommendation> {
const treePath = this.getSkillPath(skill.name);
const explanation = await this.generateExplanation(skill, score, profile);
return {
skill,
score,
reasoning: explanation,
treePath,
};
}
async explainBatch(
skills: Array<{ skill: SkillSummary; score: number }>,
profile: ProjectProfile
): Promise<ExplainedRecommendation[]> {
const results: ExplainedRecommendation[] = [];
for (const { skill, score } of skills) {
const explained = await this.explain(skill, score, profile);
results.push(explained);
}
return results;
}
private async createSearchPlan(query: TreeSearchQuery): Promise<SearchPlan> {
const categories = CATEGORY_TAXONOMY.map((c) => c.category);
if (this.config.provider === 'mock') {
return this.mockSearchPlan(query.query, query.context);
}
const prompt = buildSearchPlanPrompt(
query.query,
categories,
query.context
);
const response = await this.callLLM(prompt);
try {
const data = extractJsonFromResponse(response);
return validateSearchPlan(data);
} catch {
return this.mockSearchPlan(query.query, query.context);
}
}
private mockSearchPlan(query: string, context?: ProjectProfile): SearchPlan {
const queryLower = query.toLowerCase();
const keywords = queryLower
.split(/\s+/)
.filter((w) => w.length > 2);
const categoryScores: { category: string; score: number }[] = [];
for (const mapping of CATEGORY_TAXONOMY) {
let score = 0;
for (const keyword of keywords) {
if (mapping.category.toLowerCase().includes(keyword)) {
score += 30;
}
for (const tag of mapping.tags) {
if (tag.includes(keyword) || keyword.includes(tag)) {
score += 20;
}
}
for (const kw of mapping.keywords) {
if (kw.includes(keyword) || keyword.includes(kw)) {
score += 15;
}
}
}
if (context) {
for (const framework of context.stack.frameworks) {
if (mapping.tags.includes(framework.name.toLowerCase())) {
score += 10;
}
}
for (const language of context.stack.languages) {
if (mapping.tags.includes(language.name.toLowerCase())) {
score += 5;
}
}
}
if (score > 0) {
categoryScores.push({ category: mapping.category, score });
}
}
categoryScores.sort((a, b) => b.score - a.score);
const primaryCategories = categoryScores
.slice(0, 3)
.map((c) => c.category);
const secondaryCategories = categoryScores
.slice(3, 6)
.map((c) => c.category);
const filters: SearchPlan['filters'] = {
tags: keywords.filter((k) =>
CATEGORY_TAXONOMY.some((m) => m.tags.includes(k))
),
frameworks: context?.stack.frameworks.map((f) => f.name) || [],
languages: context?.stack.languages.map((l) => l.name) || [],
};
return {
primaryCategories: primaryCategories.length > 0 ? primaryCategories : ['Development'],
secondaryCategories,
keywords,
filters,
strategy: keywords.length <= 2 ? 'breadth-first' : 'targeted',
};
}
private async traverseTree(
query: TreeSearchQuery,
plan: SearchPlan
): Promise<{
results: TreeSearchResult[];
exploredPaths: string[][];
nodesVisited: number;
}> {
if (!this.tree) {
return { results: [], exploredPaths: [], nodesVisited: 0 };
}
const results: TreeSearchResult[] = [];
const exploredPaths: string[][] = [];
let nodesVisited = 0;
const relevantNodes = this.findRelevantNodes(plan);
for (const { node, path } of relevantNodes) {
nodesVisited++;
exploredPaths.push(path);
for (const skillName of node.skills) {
const skill = this.skillMap.get(skillName);
if (!skill) continue;
const matchResult = this.evaluateSkillMatch(query.query, skill, query.context);
if (matchResult.confidence >= (query.minConfidence ?? 30)) {
results.push({
skill,
path,
reasoning: matchResult.reasoning,
confidence: matchResult.confidence,
relevantSections: matchResult.relevantSections,
matchedKeywords: matchResult.matchedKeywords,
});
}
}
}
return { results, exploredPaths, nodesVisited };
}
private findRelevantNodes(
plan: SearchPlan
): Array<{ node: TreeNode; path: string[] }> {
if (!this.tree) return [];
const relevant: Array<{ node: TreeNode; path: string[]; priority: number }> = [];
const traverse = (node: TreeNode, path: string[], priorityBoost: number) => {
const nodeName = node.name.toLowerCase();
let priority = priorityBoost;
if (plan.primaryCategories.some((c) => c.toLowerCase() === nodeName)) {
priority += 100;
}
if (plan.secondaryCategories.some((c) => c.toLowerCase() === nodeName)) {
priority += 50;
}
for (const keyword of plan.keywords) {
if (nodeName.includes(keyword) || keyword.includes(nodeName)) {
priority += 25;
}
}
if (priority > 0 || node.depth === 0) {
relevant.push({ node, path: [...path, node.name], priority });
}
for (const child of node.children) {
traverse(child, [...path, node.name], priority > 0 ? priority * 0.5 : 0);
}
};
traverse(this.tree.rootNode, [], 0);
relevant.sort((a, b) => b.priority - a.priority);
return relevant.slice(0, 20).map(({ node, path }) => ({ node, path }));
}
private evaluateSkillMatch(
query: string,
skill: SkillSummary,
context?: ProjectProfile
): {
confidence: number;
reasoning: string;
relevantSections: string[];
matchedKeywords: string[];
} {
const queryTerms = query.toLowerCase().split(/\s+/);
const matchedKeywords: string[] = [];
let confidence = 0;
const nameLower = skill.name.toLowerCase();
for (const term of queryTerms) {
if (nameLower.includes(term)) {
confidence += 30;
matchedKeywords.push(term);
}
}
const descLower = (skill.description || '').toLowerCase();
for (const term of queryTerms) {
if (descLower.includes(term) && !matchedKeywords.includes(term)) {
confidence += 20;
matchedKeywords.push(term);
}
}
const tagsLower = (skill.tags || []).map((t) => t.toLowerCase());
for (const term of queryTerms) {
if (tagsLower.some((t) => t.includes(term) || term.includes(t))) {
if (!matchedKeywords.includes(term)) {
confidence += 25;
matchedKeywords.push(term);
}
}
}
if (context) {
for (const framework of context.stack.frameworks) {
const fwLower = framework.name.toLowerCase();
if (tagsLower.includes(fwLower) || nameLower.includes(fwLower)) {
confidence += 15;
}
}
for (const language of context.stack.languages) {
const langLower = language.name.toLowerCase();
if (tagsLower.includes(langLower) || nameLower.includes(langLower)) {
confidence += 10;
}
}
}
confidence = Math.min(100, confidence);
const relevantSections: string[] = [];
if (matchedKeywords.length > 0) {
relevantSections.push('description', 'tags');
}
const reasoning = matchedKeywords.length > 0
? `Matches keywords: ${matchedKeywords.join(', ')}`
: 'No direct keyword match';
return {
confidence,
reasoning,
relevantSections,
matchedKeywords,
};
}
private fallbackSearch(query: TreeSearchQuery): TreeSearchResult[] {
const results: TreeSearchResult[] = [];
for (const skill of this.skillMap.values()) {
const matchResult = this.evaluateSkillMatch(
query.query,
skill,
query.context
);
if (matchResult.confidence >= (query.minConfidence ?? 30)) {
results.push({
skill,
path: ['Uncategorized'],
reasoning: matchResult.reasoning,
confidence: matchResult.confidence,
relevantSections: matchResult.relevantSections,
matchedKeywords: matchResult.matchedKeywords,
});
}
}
return results;
}
private async generateExplanation(
skill: SkillSummary,
score: number,
profile: ProjectProfile
): Promise<ExplainedMatch> {
if (this.config.provider === 'mock') {
return this.mockExplanation(skill, score, profile);
}
const prompt = buildExplanationPrompt(skill, score, profile);
try {
const response = await this.callLLM(prompt);
const data = extractJsonFromResponse(response) as Partial<ExplainedMatch>;
return {
matchedBecause: data.matchedBecause || [],
relevantFor: data.relevantFor || [],
differentFrom: data.differentFrom || [],
confidence: data.confidence || this.scoreToConfidence(score),
};
} catch {
return this.mockExplanation(skill, score, profile);
}
}
private mockExplanation(
skill: SkillSummary,
score: number,
profile: ProjectProfile
): ExplainedMatch {
const matchedBecause: string[] = [];
const relevantFor: string[] = [];
const differentFrom: string[] = [];
const skillTags = skill.tags || [];
for (const framework of profile.stack.frameworks) {
const fwLower = framework.name.toLowerCase();
if (
skillTags.some((t) => t.toLowerCase().includes(fwLower)) ||
skill.name.toLowerCase().includes(fwLower)
) {
matchedBecause.push(`Uses ${framework.name}`);
}
}
for (const language of profile.stack.languages) {
const langLower = language.name.toLowerCase();
if (skillTags.some((t) => t.toLowerCase().includes(langLower))) {
matchedBecause.push(`Supports ${language.name}`);
}
}
if (matchedBecause.length === 0) {
matchedBecause.push(`Related tags: ${skillTags.slice(0, 3).join(', ')}`);
}
relevantFor.push(`Your ${profile.type || 'project'} project`);
if (profile.name) {
relevantFor.push(`Specifically for ${profile.name}`);
}
differentFrom.push('General-purpose alternatives');
return {
matchedBecause,
relevantFor,
differentFrom,
confidence: this.scoreToConfidence(score),
};
}
private scoreToConfidence(score: number): 'high' | 'medium' | 'low' {
if (score >= 70) return 'high';
if (score >= 50) return 'medium';
return 'low';
}
private getSkillPath(skillName: string): string[] {
if (!this.tree) return ['Uncategorized'];
const generator = new TreeGenerator();
const path = generator.getPath(this.tree, skillName);
return path || ['Uncategorized'];
}
private buildReasoningSummary(
plan: SearchPlan,
results: TreeSearchResult[]
): string {
const parts: string[] = [];
parts.push(`Search strategy: ${plan.strategy}`);
parts.push(`Primary categories: ${plan.primaryCategories.join(', ')}`);
if (plan.keywords.length > 0) {
parts.push(`Keywords extracted: ${plan.keywords.join(', ')}`);
}
parts.push(`Found ${results.length} matching skills`);
if (results.length > 0) {
const avgConfidence = results.reduce((sum, r) => sum + r.confidence, 0) / results.length;
parts.push(`Average confidence: ${Math.round(avgConfidence)}%`);
}
return parts.join('. ');
}
private async callLLM(prompt: string): Promise<string> {
return `Mock response for: ${prompt.slice(0, 50)}...`;
}
private getCacheKey(query: TreeSearchQuery): string {
return JSON.stringify({
query: query.query,
contextName: query.context?.name,
maxResults: query.maxResults,
minConfidence: query.minConfidence,
});
}
private getFromCache(key: string): ReasoningCacheEntry | null {
const entry = this.cache.get(key);
if (!entry) return null;
const now = Date.now();
if (now - entry.timestamp > entry.ttl) {
this.cache.delete(key);
return null;
}
return entry;
}
private addToCache(key: string, results: TreeSearchResult[]): void {
if (this.cache.size >= MAX_CACHE_SIZE) {
const oldestKey = this.cache.keys().next().value;
if (oldestKey) {
this.cache.delete(oldestKey);
}
}
this.cache.set(key, {
query: key,
results,
timestamp: Date.now(),
ttl: CACHE_TTL_MS,
});
}
private updateStats(processingTimeMs: number, resultCount: number): void {
const cacheMisses = this.stats.cacheMisses;
if (cacheMisses === 1) {
this.stats.averageProcessingTimeMs = processingTimeMs;
this.stats.averageResultsPerQuery = resultCount;
} else {
this.stats.averageProcessingTimeMs =
(this.stats.averageProcessingTimeMs * (cacheMisses - 1) + processingTimeMs) / cacheMisses;
this.stats.averageResultsPerQuery =
(this.stats.averageResultsPerQuery * (cacheMisses - 1) + resultCount) / cacheMisses;
}
}
getStats(): ReasoningEngineStats {
return { ...this.stats };
}
clearCache(): void {
this.cache.clear();
}
getTree(): SkillTree | null {
return this.tree;
}
}
export function createReasoningEngine(
config?: Partial<ReasoningConfig>
): ReasoningEngine {
return new ReasoningEngine(config);
}