@matimo/core 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/core/skill-registry.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Skill Registry — in-memory store and search for skills
+ *
+ * Mirrors ToolRegistry but for skills. Provides discovery, search, and filtering.
+ * Supports both substring matching (default) and semantic search via pluggable embeddings.
+ */
+import { SkillDefinition, SkillSummary, SearchSkillsOptions, EmbeddingProvider, SkillContentOptions } from './types';
+/**
+ * Semantic search result with relevance score.
+ */
+export interface SemanticSearchResult {
+    skill: SkillSummary;
+    /** Cosine similarity score (0–1, higher = more relevant) */
+    score: number;
+}
+export declare class SkillRegistry {
+    private logger;
+    private skills;
+    /** Pluggable embedding provider for semantic search */
+    private embeddingProvider;
+    /** Cached embeddings: skill name → vector */
+    private embeddings;
+    /** Whether embeddings need rebuilding */
+    private embeddingsDirty;
+    /** Cached parsed content for selective loading */
+    private parsedContent;
+    /**
+     * Set a custom embedding provider (OpenAI, Cohere, etc.).
+     * If not set, a built-in TF-IDF provider is used as fallback.
+     */
+    setEmbeddingProvider(provider: EmbeddingProvider): void;
+    /**
+     * Register a single skill
+     */
+    register(skill: SkillDefinition): void;
+    /**
+     * Register multiple skills
+     */
+    registerAll(skills: SkillDefinition[]): void;
+    /**
+     * Get a single skill by name
+     */
+    get(name: string): SkillDefinition | undefined;
+    /**
+     * Get a single skill by name (throws if not found)
+     */
+    getRequired(name: string): SkillDefinition;
+    /**
+     * Get selective skill content — only the sections an agent needs.
+     * This prevents dumping entire SKILL.md files into the LLM context.
+     *
+     * @example
+     * // Get only the error handling section, max 500 tokens
+     * registry.getSkillContent('postgres-query-operations', {
+     *   sections: ['Error Handling'],
+     *   maxTokens: 500,
+     * })
+     */
+    getSkillContent(name: string, options?: SkillContentOptions): string | null;
+    /**
+     * List all sections of a skill with their token costs.
+     * Agents use this to decide which sections to load.
+     */
+    getSkillSections(name: string): Array<{
+        path: string;
+        level: number;
+        tokenEstimate: number;
+    }> | null;
+    /**
+     * List all skills (Level 1 discovery — minimal context)
+     */
+    list(): SkillSummary[];
+    /**
+     * Search skills by keyword, category, difficulty, etc.
+     *
+     * When `options.semantic` is true, uses embedding-based similarity ranking
+     * instead of substring matching. Falls back to built-in TF-IDF if no
+     * external embedding provider is configured.
+     */
+    search(options?: SearchSkillsOptions): SkillSummary[];
+    /**
+     * Semantic search with relevance scores.
+     * Returns ranked results with cosine similarity scores.
+     *
+     * @example
+     * const results = await registry.semanticSearch('How do I handle Postgres connection pooling?');
+     * // → [{ skill: { name: 'postgres-query-operations', ... }, score: 0.82 }]
+     */
+    semanticSearch(query: string, options?: {
+        limit?: number;
+        minScore?: number;
+    }): Promise<SemanticSearchResult[]>;
+    /**
+     * Get all skills (full definitions)
+     */
+    getAll(): SkillDefinition[];
+    /**
+     * Check if a skill exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get the count of registered skills
+     */
+    count(): number;
+    /**
+     * Clear all skills
+     */
+    clear(): void;
+    /**
+     * Remove a skill
+     */
+    remove(name: string): boolean;
+    /**
+     * Ensure embeddings are computed and up-to-date.
+     */
+    private ensureEmbeddings;
+    /**
+     * Synchronous ranking using TF-IDF (for the non-async search() method).
+     */
+    private rankBySimilarity;
+    /**
+     * Get or create the default TF-IDF provider.
+     */
+    private defaultProvider;
+    private getDefaultProvider;
+    /**
+     * Convert a skill into a searchable text string for embedding.
+     */
+    private skillToText;
+}
+//# sourceMappingURL=skill-registry.d.ts.map

package/dist/core/skill-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-registry.d.ts","sourceRoot":"","sources":["../../src/core/skill-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAOjB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,MAAM,CAAsC;IAEpD,uDAAuD;IACvD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,6CAA6C;IAC7C,OAAO,CAAC,UAAU,CAA+B;IACjD,yCAAyC;IACzC,OAAO,CAAC,eAAe,CAAQ;IAC/B,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAyC;IAE9D;;;OAGG;IACH,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAMvD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAetC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAM5C;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI9C;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;IAQ1C;;;;;;;;;;OAUG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI;IAM3E;;;OAGG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,GACX,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAMvE;;OAEG;IACH,IAAI,IAAI,YAAY,EAAE;IAWtB;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,EAAE;IAmEzD;;;;;;;OAOG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAClD,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAgClC;;OAEG;IACH,MAAM,IAAI,eAAe,EAAE;IAI3B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAS7B;;OAEG;YACW,gBAAgB;IAwB9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyBxB;;OAEG;IACH,OAAO,CAAC,eAAe,CAAuC;IAC9D,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;IACH,OAAO,CAAC,WAAW;CAOpB"}

package/dist/core/skill-registry.js

@@ -0,0 +1,316 @@
+/**
+ * Skill Registry — in-memory store and search for skills
+ *
+ * Mirrors ToolRegistry but for skills. Provides discovery, search, and filtering.
+ * Supports both substring matching (default) and semantic search via pluggable embeddings.
+ */
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+import { getGlobalMatimoLogger } from '../logging';
+import { TfIdfEmbeddingProvider, cosineSimilarity } from './tfidf-embedding';
+import { parseSkillSections, extractSkillContent, listSkillSections } from './skill-content-parser';
+export class SkillRegistry {
+    constructor() {
+        this.logger = getGlobalMatimoLogger();
+        this.skills = new Map();
+        /** Pluggable embedding provider for semantic search */
+        this.embeddingProvider = null;
+        /** Cached embeddings: skill name → vector */
+        this.embeddings = new Map();
+        /** Whether embeddings need rebuilding */
+        this.embeddingsDirty = true;
+        /** Cached parsed content for selective loading */
+        this.parsedContent = new Map();
+        /**
+         * Get or create the default TF-IDF provider.
+         */
+        this.defaultProvider = null;
+    }
+    /**
+     * Set a custom embedding provider (OpenAI, Cohere, etc.).
+     * If not set, a built-in TF-IDF provider is used as fallback.
+     */
+    setEmbeddingProvider(provider) {
+        this.embeddingProvider = provider;
+        this.embeddingsDirty = true;
+        this.logger.debug('SkillRegistry: custom embedding provider set');
+    }
+    /**
+     * Register a single skill
+     */
+    register(skill) {
+        if (!skill.name) {
+            throw new MatimoError('Skill must have a name', ErrorCode.INVALID_SCHEMA);
+        }
+        this.skills.set(skill.name, skill);
+        this.embeddingsDirty = true;
+        // Cache parsed sections for selective loading
+        if (skill.body) {
+            this.parsedContent.set(skill.name, parseSkillSections(skill.body));
+        }
+        this.logger.debug('SkillRegistry: skill registered', { name: skill.name });
+    }
+    /**
+     * Register multiple skills
+     */
+    registerAll(skills) {
+        for (const skill of skills) {
+            this.register(skill);
+        }
+    }
+    /**
+     * Get a single skill by name
+     */
+    get(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Get a single skill by name (throws if not found)
+     */
+    getRequired(name) {
+        const skill = this.skills.get(name);
+        if (!skill) {
+            throw new MatimoError(`Skill not found: ${name}`, ErrorCode.TOOL_NOT_FOUND);
+        }
+        return skill;
+    }
+    /**
+     * Get selective skill content — only the sections an agent needs.
+     * This prevents dumping entire SKILL.md files into the LLM context.
+     *
+     * @example
+     * // Get only the error handling section, max 500 tokens
+     * registry.getSkillContent('postgres-query-operations', {
+     *   sections: ['Error Handling'],
+     *   maxTokens: 500,
+     * })
+     */
+    getSkillContent(name, options) {
+        const parsed = this.parsedContent.get(name);
+        if (!parsed)
+            return null;
+        return extractSkillContent(parsed, options);
+    }
+    /**
+     * List all sections of a skill with their token costs.
+     * Agents use this to decide which sections to load.
+     */
+    getSkillSections(name) {
+        const parsed = this.parsedContent.get(name);
+        if (!parsed)
+            return null;
+        return listSkillSections(parsed);
+    }
+    /**
+     * List all skills (Level 1 discovery — minimal context)
+     */
+    list() {
+        return Array.from(this.skills.values()).map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            version: skill.version,
+            license: skill.license,
+            metadata: skill.metadata,
+            source: skill.source,
+        }));
+    }
+    /**
+     * Search skills by keyword, category, difficulty, etc.
+     *
+     * When `options.semantic` is true, uses embedding-based similarity ranking
+     * instead of substring matching. Falls back to built-in TF-IDF if no
+     * external embedding provider is configured.
+     */
+    search(options = {}) {
+        const { query = '', category, difficulty, tags, author, limit = 50, offset = 0 } = options;
+        let results = Array.from(this.skills.values());
+        // Apply filters first (these are always exact/substring)
+        if (category) {
+            results = results.filter((skill) => skill.metadata?.category?.toLowerCase() === category.toLowerCase());
+        }
+        if (difficulty) {
+            results = results.filter((skill) => skill.metadata?.difficulty?.toLowerCase() === difficulty.toLowerCase());
+        }
+        if (tags && tags.length > 0) {
+            const metadataTags = tags.map((t) => t.toLowerCase());
+            results = results.filter((skill) => {
+                const skillTags = (skill.metadata?.tags || '')
+                    .split(',')
+                    .map((t) => t.trim().toLowerCase());
+                return metadataTags.some((tag) => skillTags.includes(tag));
+            });
+        }
+        if (author) {
+            results = results.filter((skill) => skill.metadata?.author?.toLowerCase() === author.toLowerCase());
+        }
+        // Apply query filter (substring or semantic)
+        if (query) {
+            if (options.semantic) {
+                // Semantic search: rank by embedding similarity
+                const scored = this.rankBySimilarity(query, results);
+                // Precompute a map for O(1) lookup by skill name
+                const skillByName = new Map(results.map((skill) => [skill.name, skill]));
+                results = scored
+                    .filter((r) => r.score > 0.1) // Minimum relevance threshold
+                    .sort((a, b) => b.score - a.score)
+                    .map((r) => skillByName.get(r.skill.name))
+                    .filter((skill) => skill !== undefined);
+            }
+            else {
+                // Substring search (original behavior)
+                const lowerQuery = query.toLowerCase();
+                results = results.filter((skill) => {
+                    const nameMatch = skill.name.toLowerCase().includes(lowerQuery);
+                    const descMatch = skill.description.toLowerCase().includes(lowerQuery);
+                    return nameMatch || descMatch;
+                });
+            }
+        }
+        // Pagination
+        const paged = results.slice(offset, offset + limit);
+        return paged.map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            version: skill.version,
+            license: skill.license,
+            metadata: skill.metadata,
+            source: skill.source,
+        }));
+    }
+    /**
+     * Semantic search with relevance scores.
+     * Returns ranked results with cosine similarity scores.
+     *
+     * @example
+     * const results = await registry.semanticSearch('How do I handle Postgres connection pooling?');
+     * // → [{ skill: { name: 'postgres-query-operations', ... }, score: 0.82 }]
+     */
+    async semanticSearch(query, options = {}) {
+        const { limit = 10, minScore = 0.1 } = options;
+        await this.ensureEmbeddings();
+        const provider = this.embeddingProvider || this.getDefaultProvider();
+        const queryEmbedding = await provider.embed(query);
+        const results = [];
+        for (const [name, embedding] of this.embeddings) {
+            const skill = this.skills.get(name);
+            if (!skill)
+                continue;
+            const score = cosineSimilarity(queryEmbedding, embedding);
+            if (score >= minScore) {
+                results.push({
+                    skill: {
+                        name: skill.name,
+                        description: skill.description,
+                        version: skill.version,
+                        license: skill.license,
+                        metadata: skill.metadata,
+                        source: skill.source,
+                    },
+                    score,
+                });
+            }
+        }
+        return results.sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    /**
+     * Get all skills (full definitions)
+     */
+    getAll() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Check if a skill exists
+     */
+    has(name) {
+        return this.skills.has(name);
+    }
+    /**
+     * Get the count of registered skills
+     */
+    count() {
+        return this.skills.size;
+    }
+    /**
+     * Clear all skills
+     */
+    clear() {
+        this.skills.clear();
+        this.embeddings.clear();
+        this.parsedContent.clear();
+        this.embeddingsDirty = true;
+    }
+    /**
+     * Remove a skill
+     */
+    remove(name) {
+        this.embeddings.delete(name);
+        this.parsedContent.delete(name);
+        this.embeddingsDirty = true;
+        return this.skills.delete(name);
+    }
+    // ─── Private: Embedding Management ──────────────────────────────────────
+    /**
+     * Ensure embeddings are computed and up-to-date.
+     */
+    async ensureEmbeddings() {
+        if (!this.embeddingsDirty)
+            return;
+        const provider = this.embeddingProvider || this.getDefaultProvider();
+        const skills = Array.from(this.skills.values());
+        // Build text corpus: name + description + metadata tags
+        const texts = skills.map((s) => this.skillToText(s));
+        // If using TF-IDF, refit the vocabulary
+        if (provider instanceof TfIdfEmbeddingProvider) {
+            provider.fit(texts);
+        }
+        const vectors = await provider.embedBatch(texts);
+        this.embeddings.clear();
+        for (let i = 0; i < skills.length; i++) {
+            this.embeddings.set(skills[i].name, vectors[i]);
+        }
+        this.embeddingsDirty = false;
+    }
+    /**
+     * Synchronous ranking using TF-IDF (for the non-async search() method).
+     */
+    rankBySimilarity(query, candidates) {
+        const provider = this.getDefaultProvider();
+        // Build corpus from candidates
+        const texts = candidates.map((s) => this.skillToText(s));
+        provider.fit([...texts, query]); // Include query in vocab
+        const queryVec = provider.embedSync(query);
+        return candidates.map((skill) => {
+            const skillVec = provider.embedSync(this.skillToText(skill));
+            return {
+                skill: {
+                    name: skill.name,
+                    description: skill.description,
+                    version: skill.version,
+                    license: skill.license,
+                    metadata: skill.metadata,
+                    source: skill.source,
+                },
+                score: cosineSimilarity(queryVec, skillVec),
+            };
+        });
+    }
+    getDefaultProvider() {
+        if (!this.defaultProvider) {
+            this.defaultProvider = new TfIdfEmbeddingProvider();
+        }
+        return this.defaultProvider;
+    }
+    /**
+     * Convert a skill into a searchable text string for embedding.
+     */
+    skillToText(skill) {
+        const parts = [skill.name.replace(/-/g, ' '), skill.description];
+        if (skill.metadata?.tags)
+            parts.push(skill.metadata.tags);
+        if (skill.metadata?.category)
+            parts.push(skill.metadata.category);
+        if (skill.allowedTools)
+            parts.push(skill.allowedTools.join(' '));
+        return parts.join(' ');
+    }
+}
+//# sourceMappingURL=skill-registry.js.map

package/dist/core/skill-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-registry.js","sourceRoot":"","sources":["../../src/core/skill-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/tfidf-embedding.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TF-IDF Embedding Provider — zero-dependency semantic search
+ * (Term Frequency–Inverse Document Frequency)
+ * Provides a lightweight text-to-vector implementation using TF-IDF (Term
+ * Frequency–Inverse Document Frequency) for cosine-similarity ranking. This
+ * is good enough for 10–200 skills. For production enterprise deployments,
+ * plug in an OpenAI/Cohere `EmbeddingProvider` instead.
+ *
+ * No external dependencies — works out of the box.
+ */
+import { EmbeddingProvider } from './types';
+/**
+ * Simple TF-IDF based embedding provider.
+ * Builds a vocabulary from the registered corpus and represents each text as
+ * a TF-IDF weighted vector.
+ */
+export declare class TfIdfEmbeddingProvider implements EmbeddingProvider {
+    private vocabulary;
+    private idf;
+    private corpusSize;
+    private _dimensions;
+    get dimensions(): number;
+    /**
+     * Build the vocabulary and IDF weights from a corpus of documents.
+     * Must be called before `embed()` or `embedBatch()`.
+     */
+    fit(documents: string[]): void;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Synchronous embed for internal use (no async overhead).
+     */
+    embedSync(text: string): number[];
+    /**
+     * Tokenize text into lowercase terms.
+     * Splits on non-alphanumeric characters and filters stopwords.
+     */
+    private tokenize;
+}
+/**
+ * Cosine similarity between two vectors.
+ * Returns a value between -1 and 1 (1 = identical, 0 = orthogonal).
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=tfidf-embedding.d.ts.map

package/dist/core/tfidf-embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf-embedding.d.ts","sourceRoot":"","sources":["../../src/core/tfidf-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,GAAG,CAAqC;IAChD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,WAAW,CAAK;IAExB,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;OAGG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IA2BxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAItD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAsCjC;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAMjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAejE"}