signalwire-agents 0.1.0

package/dist/skills/builtin/native_vector_search.js

@@ -0,0 +1,248 @@
+/**
+ * Native Vector Search Skill - In-memory document search using TF-IDF-like scoring.
+ *
+ * Tier 3 built-in skill: no external dependencies or API keys required.
+ * Implements a simple text-matching algorithm based on word overlap scoring
+ * (TF-IDF inspired) to search through a set of in-memory documents.
+ * Suitable for small to medium document collections.
+ */
+import { SkillBase } from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+/**
+ * Tokenize text into lowercase words, removing punctuation and common stop words.
+ * @param text - Raw text to tokenize.
+ * @returns Array of meaningful word tokens.
+ */
+function tokenize(text) {
+    const stopWords = new Set([
+        'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+        'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+        'should', 'may', 'might', 'shall', 'can', 'to', 'of', 'in', 'for',
+        'on', 'with', 'at', 'by', 'from', 'as', 'into', 'through', 'during',
+        'before', 'after', 'above', 'below', 'between', 'and', 'but', 'or',
+        'nor', 'not', 'so', 'yet', 'both', 'either', 'neither', 'each',
+        'every', 'all', 'any', 'few', 'more', 'most', 'other', 'some',
+        'such', 'no', 'only', 'own', 'same', 'than', 'too', 'very',
+        'just', 'because', 'if', 'when', 'where', 'how', 'what', 'which',
+        'who', 'whom', 'this', 'that', 'these', 'those', 'i', 'me', 'my',
+        'we', 'our', 'you', 'your', 'he', 'him', 'his', 'she', 'her',
+        'it', 'its', 'they', 'them', 'their', 'about', 'up', 'out',
+    ]);
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((word) => word.length > 1 && !stopWords.has(word));
+}
+/**
+ * Compute normalized term frequency for a list of tokens.
+ * @param tokens - Array of tokenized words.
+ * @returns Map from token to its normalized frequency.
+ */
+function termFrequency(tokens) {
+    const tf = new Map();
+    for (const token of tokens) {
+        tf.set(token, (tf.get(token) ?? 0) + 1);
+    }
+    // Normalize by document length
+    const len = tokens.length || 1;
+    for (const [term, count] of tf) {
+        tf.set(term, count / len);
+    }
+    return tf;
+}
+/**
+ * Compute inverse document frequency weights for a tokenized corpus.
+ * @param corpus - Array of token arrays, one per document.
+ * @returns Map from token to its IDF weight.
+ */
+function inverseDocumentFrequency(corpus) {
+    const idf = new Map();
+    const numDocs = corpus.length || 1;
+    // Count how many documents contain each term
+    const docFreq = new Map();
+    for (const tokens of corpus) {
+        const uniqueTokens = new Set(tokens);
+        for (const token of uniqueTokens) {
+            docFreq.set(token, (docFreq.get(token) ?? 0) + 1);
+        }
+    }
+    for (const [term, freq] of docFreq) {
+        idf.set(term, Math.log((numDocs + 1) / (freq + 1)) + 1);
+    }
+    return idf;
+}
+/**
+ * Score a query against a document using TF-IDF cosine-like similarity.
+ * @param queryTokens - Tokenized query words.
+ * @param docTf - Pre-computed term frequency map for the document.
+ * @param idf - Pre-computed inverse document frequency map.
+ * @returns Similarity score (higher is more relevant).
+ */
+function scoreTfIdf(queryTokens, docTf, idf) {
+    if (queryTokens.length === 0)
+        return 0;
+    let score = 0;
+    const queryTf = termFrequency(queryTokens);
+    for (const [term, qWeight] of queryTf) {
+        const docWeight = docTf.get(term) ?? 0;
+        const idfWeight = idf.get(term) ?? 1;
+        score += qWeight * docWeight * idfWeight * idfWeight;
+    }
+    return score;
+}
+/**
+ * In-memory document search using TF-IDF-like word overlap scoring.
+ *
+ * Tier 3 built-in skill with no external dependencies or API keys required.
+ * Documents are provided via the `documents` config array and indexed at
+ * construction time. Suitable for small to medium document collections.
+ */
+export class NativeVectorSearchSkill extends SkillBase {
+    _documents = [];
+    _tokenizedDocs = [];
+    _docTfs = [];
+    _idf = new Map();
+    _indexed = false;
+    /**
+     * @param config - Optional configuration; supports `documents` array of {id, text, metadata?}.
+     */
+    constructor(config) {
+        super('native_vector_search', config);
+        this._loadDocuments();
+    }
+    /** @returns Manifest with config schema for the documents array. */
+    getManifest() {
+        return {
+            name: 'native_vector_search',
+            description: 'In-memory document search using TF-IDF-like word overlap scoring. No external dependencies or API keys required.',
+            version: '1.0.0',
+            author: 'SignalWire',
+            tags: ['search', 'vector', 'tfidf', 'documents', 'local', 'knowledge'],
+            configSchema: {
+                documents: {
+                    type: 'array',
+                    description: 'Array of documents to index: [{ id: string, text: string, metadata?: object }].',
+                },
+            },
+        };
+    }
+    /**
+     * Load and index documents from configuration.
+     */
+    _loadDocuments() {
+        const docs = this.getConfig('documents', []);
+        if (!Array.isArray(docs) || docs.length === 0) {
+            this._documents = [];
+            this._indexed = false;
+            return;
+        }
+        this._documents = docs.filter((d) => d && typeof d.id === 'string' && typeof d.text === 'string' && d.text.trim().length > 0);
+        // Tokenize all documents
+        this._tokenizedDocs = this._documents.map((doc) => tokenize(doc.text));
+        // Compute TF for each document
+        this._docTfs = this._tokenizedDocs.map((tokens) => termFrequency(tokens));
+        // Compute IDF across the corpus
+        this._idf = inverseDocumentFrequency(this._tokenizedDocs);
+        this._indexed = true;
+    }
+    /** @returns A single `search_documents` tool that searches indexed documents by text similarity. */
+    getTools() {
+        return [
+            {
+                name: 'search_documents',
+                description: 'Search through the indexed documents for the most relevant results matching your query. Uses text similarity scoring to rank results.',
+                parameters: {
+                    query: {
+                        type: 'string',
+                        description: 'The search query or question.',
+                    },
+                    top_k: {
+                        type: 'number',
+                        description: 'Number of top results to return (1-20). Defaults to 3.',
+                    },
+                },
+                required: ['query'],
+                handler: (args) => {
+                    const query = args.query;
+                    const topK = args.top_k;
+                    if (!query || typeof query !== 'string' || query.trim().length === 0) {
+                        return new SwaigFunctionResult('Please provide a search query.');
+                    }
+                    if (!this._indexed || this._documents.length === 0) {
+                        return new SwaigFunctionResult('No documents are loaded for searching. Configure the skill with a "documents" array.');
+                    }
+                    const k = Math.max(1, Math.min(20, topK ?? 3));
+                    const queryTokens = tokenize(query);
+                    if (queryTokens.length === 0) {
+                        return new SwaigFunctionResult('The search query did not contain any meaningful search terms. Please try a more specific query.');
+                    }
+                    // Score all documents
+                    const scored = this._documents.map((doc, i) => ({
+                        document: doc,
+                        score: scoreTfIdf(queryTokens, this._docTfs[i], this._idf),
+                    }));
+                    // Sort by score descending
+                    scored.sort((a, b) => b.score - a.score);
+                    // Filter out zero-score results and take top k
+                    const results = scored.filter((s) => s.score > 0).slice(0, k);
+                    if (results.length === 0) {
+                        return new SwaigFunctionResult(`No relevant documents found for "${query}". Try different search terms.`);
+                    }
+                    const parts = [
+                        `Found ${results.length} relevant document(s) for "${query}":`,
+                        '',
+                    ];
+                    for (let i = 0; i < results.length; i++) {
+                        const { document, score } = results[i];
+                        const relevance = score.toFixed(4);
+                        parts.push(`--- Result ${i + 1} (ID: ${document.id}, relevance: ${relevance}) ---`);
+                        // Truncate long texts for readability
+                        const maxLen = 500;
+                        const text = document.text.trim();
+                        if (text.length > maxLen) {
+                            parts.push(text.slice(0, maxLen) + '...');
+                        }
+                        else {
+                            parts.push(text);
+                        }
+                        if (document.metadata && Object.keys(document.metadata).length > 0) {
+                            const metaStr = Object.entries(document.metadata)
+                                .map(([k, v]) => `${k}: ${String(v)}`)
+                                .join(', ');
+                            parts.push(`[Metadata: ${metaStr}]`);
+                        }
+                        parts.push('');
+                    }
+                    return new SwaigFunctionResult(parts.join('\n').trim());
+                },
+            },
+        ];
+    }
+    /** @returns Prompt section describing the local document search capabilities. */
+    getPromptSections() {
+        const docCount = this._documents.length;
+        return [
+            {
+                title: 'Document Search',
+                body: `You have access to a local collection of ${docCount} document(s) that can be searched for relevant information.`,
+                bullets: [
+                    'Use the search_documents tool when the user asks about topics that may be covered in the indexed documents.',
+                    'You can specify how many results to return with the top_k parameter.',
+                    'Results are ranked by text relevance using word overlap scoring.',
+                    'Synthesize information from multiple results when appropriate.',
+                    'If no results are found, the query terms may not match the document content. Try different wording.',
+                ],
+            },
+        ];
+    }
+}
+/**
+ * Factory function for creating NativeVectorSearchSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new NativeVectorSearchSkill instance.
+ */
+export function createSkill(config) {
+    return new NativeVectorSearchSkill(config);
+}
+//# sourceMappingURL=native_vector_search.js.map

package/dist/skills/builtin/native_vector_search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native_vector_search.js","sourceRoot":"","sources":["../../../src/skills/builtin/native_vector_search.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAO5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAoBnE;;;;GAIG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;QACxB,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO;QACnE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;QACnE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK;QACjE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ;QACnE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI;QAClE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM;QAC9D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;QAC7D,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;QAC1D,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO;QAChE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI;QAChE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;QAC5D,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK;KAC3D,CAAC,CAAC;IAEH,OAAO,IAAI;SACR,WAAW,EAAE;SACb,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,MAAgB;IACrC,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,+BAA+B;IAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,GAAG,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,SAAS,wBAAwB,CAC/B,MAAkB;IAElB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAEnC,6CAA6C;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,SAAS,UAAU,CACjB,WAAqB,EACrB,KAA0B,EAC1B,GAAwB;IAExB,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEvC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,OAAO,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAE3C,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,KAAK,IAAI,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACvD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,uBAAwB,SAAQ,SAAS;IAC5C,UAAU,GAAoB,EAAE,CAAC;IACjC,cAAc,GAAe,EAAE,CAAC;IAChC,OAAO,GAA0B,EAAE,CAAC;IACpC,IAAI,GAAwB,IAAI,GAAG,EAAE,CAAC;IACtC,QAAQ,GAAG,KAAK,CAAC;IAEzB;;OAEG;IACH,YAAY,MAAoB;QAC9B,KAAK,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAED,oEAAoE;IACpE,WAAW;QACT,OAAO;YACL,IAAI,EAAE,sBAAsB;YAC5B,WAAW,EACT,kHAAkH;YACpH,OAAO,EAAE,OAAO;YAChB,MAAM,EAAE,YAAY;YACpB,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC;YACtE,YAAY,EAAE;gBACZ,SAAS,EAAE;oBACT,IAAI,EAAE,OAAO;oBACb,WAAW,EACT,iFAAiF;iBACpF;aACF;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,cAAc;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAkB,WAAW,EAAE,EAAE,CAAC,CAAC;QAE9D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAC3B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAC/F,CAAC;QAEF,yBAAyB;QACzB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAEvE,+BAA+B;QAC/B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAE1E,gCAAgC;QAChC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAE1D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,oGAAoG;IACpG,QAAQ;QACN,OAAO;YACL;gBACE,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EACT,uIAAuI;gBACzI,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,+BAA+B;qBAC7C;oBACD,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,wDAAwD;qBACtE;iBACF;gBACD,QAAQ,EAAE,CAAC,OAAO,CAAC;gBACnB,OAAO,EAAE,CAAC,IAA6B,EAAE,EAAE;oBACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAA2B,CAAC;oBAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,KAA2B,CAAC;oBAE9C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBACrE,OAAO,IAAI,mBAAmB,CAAC,gCAAgC,CAAC,CAAC;oBACnE,CAAC;oBAED,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBACnD,OAAO,IAAI,mBAAmB,CAC5B,sFAAsF,CACvF,CAAC;oBACJ,CAAC;oBAED,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;oBAC/C,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;oBAEpC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBAC7B,OAAO,IAAI,mBAAmB,CAC5B,iGAAiG,CAClG,CAAC;oBACJ,CAAC;oBAED,sBAAsB;oBACtB,MAAM,MAAM,GAAqB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;wBAChE,QAAQ,EAAE,GAAG;wBACb,KAAK,EAAE,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC;qBAC3D,CAAC,CAAC,CAAC;oBAEJ,2BAA2B;oBAC3B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;oBAEzC,+CAA+C;oBAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBAE9D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBACzB,OAAO,IAAI,mBAAmB,CAC5B,oCAAoC,KAAK,gCAAgC,CAC1E,CAAC;oBACJ,CAAC;oBAED,MAAM,KAAK,GAAa;wBACtB,SAAS,OAAO,CAAC,MAAM,8BAA8B,KAAK,IAAI;wBAC9D,EAAE;qBACH,CAAC;oBAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;wBACxC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;wBACvC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;wBAEnC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,QAAQ,CAAC,EAAE,gBAAgB,SAAS,OAAO,CAAC,CAAC;wBAEpF,sCAAsC;wBACtC,MAAM,MAAM,GAAG,GAAG,CAAC;wBACnB,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;wBAClC,IAAI,IAAI,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;4BACzB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC;wBAC5C,CAAC;6BAAM,CAAC;4BACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;wBACnB,CAAC;wBAED,IAAI,QAAQ,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;4BACnE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;iCAC9C,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;iCACrC,IAAI,CAAC,IAAI,CAAC,CAAC;4BACd,KAAK,CAAC,IAAI,CAAC,cAAc,OAAO,GAAG,CAAC,CAAC;wBACvC,CAAC;wBAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACjB,CAAC;oBAED,OAAO,IAAI,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC1D,CAAC;aACF;SACF,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,iBAAiB;QACf,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAExC,OAAO;YACL;gBACE,KAAK,EAAE,iBAAiB;gBACxB,IAAI,EAAE,4CAA4C,QAAQ,6DAA6D;gBACvH,OAAO,EAAE;oBACP,6GAA6G;oBAC7G,sEAAsE;oBACtE,kEAAkE;oBAClE,gEAAgE;oBAChE,qGAAqG;iBACtG;aACF;SACF,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAoB;IAC9C,OAAO,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/skills/builtin/play_background_file.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Play Background File Skill - Controls background audio playback during calls.
+ *
+ * Tier 2 built-in skill: no external dependencies required.
+ * Provides tools to play and stop background audio files (e.g., hold music,
+ * ambient sounds) during a call using SWML playback actions.
+ */
+import { SkillBase } from '../SkillBase.js';
+import type { SkillManifest, SkillToolDefinition, SkillPromptSection, SkillConfig } from '../SkillBase.js';
+/**
+ * Controls background audio playback during calls via SWML actions.
+ *
+ * Tier 2 built-in skill with no external dependencies. Provides tools to play
+ * and stop background audio files (e.g., hold music, ambient sounds). Supports
+ * `default_file_url` and `allowed_domains` config options.
+ */
+export declare class PlayBackgroundFileSkill extends SkillBase {
+    /**
+     * @param config - Optional configuration; supports `default_file_url` and `allowed_domains`.
+     */
+    constructor(config?: SkillConfig);
+    /** @returns Manifest with config schema for default_file_url and allowed_domains. */
+    getManifest(): SkillManifest;
+    /** @returns Two tools: `play_background` to start audio and `stop_background` to stop it. */
+    getTools(): SkillToolDefinition[];
+    /** @returns Prompt section describing background audio playback capabilities. */
+    getPromptSections(): SkillPromptSection[];
+}
+/**
+ * Factory function for creating PlayBackgroundFileSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new PlayBackgroundFileSkill instance.
+ */
+export declare function createSkill(config?: SkillConfig): PlayBackgroundFileSkill;

package/dist/skills/builtin/play_background_file.js

@@ -0,0 +1,135 @@
+/**
+ * Play Background File Skill - Controls background audio playback during calls.
+ *
+ * Tier 2 built-in skill: no external dependencies required.
+ * Provides tools to play and stop background audio files (e.g., hold music,
+ * ambient sounds) during a call using SWML playback actions.
+ */
+import { SkillBase } from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+/**
+ * Controls background audio playback during calls via SWML actions.
+ *
+ * Tier 2 built-in skill with no external dependencies. Provides tools to play
+ * and stop background audio files (e.g., hold music, ambient sounds). Supports
+ * `default_file_url` and `allowed_domains` config options.
+ */
+export class PlayBackgroundFileSkill extends SkillBase {
+    /**
+     * @param config - Optional configuration; supports `default_file_url` and `allowed_domains`.
+     */
+    constructor(config) {
+        super('play_background_file', config);
+    }
+    /** @returns Manifest with config schema for default_file_url and allowed_domains. */
+    getManifest() {
+        return {
+            name: 'play_background_file',
+            description: 'Controls background audio playback during calls. Play hold music, ambient sounds, or any audio file in the background.',
+            version: '1.0.0',
+            author: 'SignalWire',
+            tags: ['audio', 'playback', 'background', 'music', 'call-control'],
+            configSchema: {
+                default_file_url: {
+                    type: 'string',
+                    description: 'Default audio file URL to use when no URL is specified.',
+                },
+                allowed_domains: {
+                    type: 'array',
+                    description: 'List of allowed domains for audio file URLs. If set, only URLs from these domains are accepted.',
+                },
+            },
+        };
+    }
+    /** @returns Two tools: `play_background` to start audio and `stop_background` to stop it. */
+    getTools() {
+        const defaultFileUrl = this.getConfig('default_file_url', undefined);
+        const allowedDomains = this.getConfig('allowed_domains', undefined);
+        return [
+            {
+                name: 'play_background',
+                description: 'Play an audio file in the background during the call. The audio will loop continuously unless stopped. Useful for hold music, ambient sounds, or background audio.',
+                parameters: {
+                    file_url: {
+                        type: 'string',
+                        description: 'The URL of the audio file to play (MP3, WAV, or other supported format). Must be a publicly accessible URL.',
+                    },
+                    wait: {
+                        type: 'boolean',
+                        description: 'If true, wait for the audio file to finish playing before continuing. Defaults to false (play in background).',
+                    },
+                },
+                required: defaultFileUrl ? [] : ['file_url'],
+                handler: (args) => {
+                    let fileUrl = args.file_url ?? defaultFileUrl;
+                    const wait = args.wait ?? false;
+                    if (!fileUrl || typeof fileUrl !== 'string' || fileUrl.trim().length === 0) {
+                        return new SwaigFunctionResult('Please provide a file URL for the audio to play in the background.');
+                    }
+                    fileUrl = fileUrl.trim();
+                    // Validate URL format
+                    try {
+                        const parsed = new URL(fileUrl);
+                        if (!['http:', 'https:'].includes(parsed.protocol)) {
+                            return new SwaigFunctionResult('Invalid file URL. Only HTTP and HTTPS URLs are supported.');
+                        }
+                        // Check allowed domains if configured
+                        if (allowedDomains && allowedDomains.length > 0) {
+                            const hostname = parsed.hostname.toLowerCase();
+                            const isAllowed = allowedDomains.some((domain) => hostname === domain.toLowerCase() ||
+                                hostname.endsWith(`.${domain.toLowerCase()}`));
+                            if (!isAllowed) {
+                                return new SwaigFunctionResult(`Audio files from "${parsed.hostname}" are not allowed. Allowed domains: ${allowedDomains.join(', ')}.`);
+                            }
+                        }
+                    }
+                    catch {
+                        return new SwaigFunctionResult(`Invalid file URL: "${fileUrl}". Please provide a valid HTTP or HTTPS URL.`);
+                    }
+                    const result = new SwaigFunctionResult(`Now playing background audio: ${fileUrl}${wait ? ' (waiting for completion)' : ''}.`);
+                    result.playBackgroundFile(fileUrl, wait);
+                    return result;
+                },
+            },
+            {
+                name: 'stop_background',
+                description: 'Stop any audio file currently playing in the background. Use this when the caller is ready to resume the conversation or when background audio is no longer needed.',
+                parameters: {},
+                handler: () => {
+                    const result = new SwaigFunctionResult('Background audio playback has been stopped.');
+                    result.stopBackgroundFile();
+                    return result;
+                },
+            },
+        ];
+    }
+    /** @returns Prompt section describing background audio playback capabilities. */
+    getPromptSections() {
+        const defaultFileUrl = this.getConfig('default_file_url', undefined);
+        const bullets = [
+            'Use the play_background tool to start playing audio in the background during a call.',
+            'Use the stop_background tool to stop any currently playing background audio.',
+            'Background audio is useful for hold music, ambient sounds, or playing announcements.',
+            'The audio will continue playing until explicitly stopped with stop_background.',
+        ];
+        if (defaultFileUrl) {
+            bullets.push(`A default audio file is configured. You can call play_background without specifying a file URL to use the default.`);
+        }
+        return [
+            {
+                title: 'Background Audio Playback',
+                body: 'You can control background audio playback during the call.',
+                bullets,
+            },
+        ];
+    }
+}
+/**
+ * Factory function for creating PlayBackgroundFileSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new PlayBackgroundFileSkill instance.
+ */
+export function createSkill(config) {
+    return new PlayBackgroundFileSkill(config);
+}
+//# sourceMappingURL=play_background_file.js.map

package/dist/skills/builtin/play_background_file.js.map

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

package/dist/skills/builtin/spider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Spider Skill - Scrapes webpage content using the Spider API.
+ *
+ * Tier 3 built-in skill: requires SPIDER_API_KEY environment variable.
+ * Uses the Spider API to fetch and extract content from web pages,
+ * optionally filtering by CSS selector.
+ */
+import { SkillBase } from '../SkillBase.js';
+import type { SkillManifest, SkillToolDefinition, SkillPromptSection, SkillConfig } from '../SkillBase.js';
+/**
+ * Scrapes webpage content using the Spider API.
+ *
+ * Tier 3 built-in skill. Requires the `SPIDER_API_KEY` environment variable.
+ * Extracts text, markdown, or HTML from any public URL, with optional CSS
+ * selector filtering. Supports `max_content_length` config option.
+ */
+export declare class SpiderSkill extends SkillBase {
+    /**
+     * @param config - Optional configuration; supports `max_content_length`.
+     */
+    constructor(config?: SkillConfig);
+    /** @returns Manifest declaring SPIDER_API_KEY as required and config schema for max_content_length. */
+    getManifest(): SkillManifest;
+    /** @returns A single `scrape_url` tool that extracts content from a web page. */
+    getTools(): SkillToolDefinition[];
+    /** @returns Prompt section describing web scraping capabilities and content limits. */
+    getPromptSections(): SkillPromptSection[];
+}
+/**
+ * Factory function for creating SpiderSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new SpiderSkill instance.
+ */
+export declare function createSkill(config?: SkillConfig): SpiderSkill;

package/dist/skills/builtin/spider.js

@@ -0,0 +1,164 @@
+/**
+ * Spider Skill - Scrapes webpage content using the Spider API.
+ *
+ * Tier 3 built-in skill: requires SPIDER_API_KEY environment variable.
+ * Uses the Spider API to fetch and extract content from web pages,
+ * optionally filtering by CSS selector.
+ */
+import { SkillBase } from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+/**
+ * Scrapes webpage content using the Spider API.
+ *
+ * Tier 3 built-in skill. Requires the `SPIDER_API_KEY` environment variable.
+ * Extracts text, markdown, or HTML from any public URL, with optional CSS
+ * selector filtering. Supports `max_content_length` config option.
+ */
+export class SpiderSkill extends SkillBase {
+    /**
+     * @param config - Optional configuration; supports `max_content_length`.
+     */
+    constructor(config) {
+        super('spider', config);
+    }
+    /** @returns Manifest declaring SPIDER_API_KEY as required and config schema for max_content_length. */
+    getManifest() {
+        return {
+            name: 'spider',
+            description: 'Scrapes webpage content using the Spider API. Extracts text, markdown, or HTML from any public URL.',
+            version: '1.0.0',
+            author: 'SignalWire',
+            tags: ['scraping', 'web', 'spider', 'content', 'extraction', 'external'],
+            requiredEnvVars: ['SPIDER_API_KEY'],
+            configSchema: {
+                max_content_length: {
+                    type: 'number',
+                    description: 'Maximum length of returned content in characters. Defaults to 5000.',
+                    default: 5000,
+                },
+            },
+        };
+    }
+    /** @returns A single `scrape_url` tool that extracts content from a web page. */
+    getTools() {
+        const maxContentLength = this.getConfig('max_content_length', 5000);
+        return [
+            {
+                name: 'scrape_url',
+                description: 'Scrape and extract content from a web page URL. Returns the page text or markdown content.',
+                parameters: {
+                    url: {
+                        type: 'string',
+                        description: 'The full URL of the web page to scrape (must start with http:// or https://).',
+                    },
+                    selector: {
+                        type: 'string',
+                        description: 'Optional CSS selector to extract specific content from the page (e.g., "article", ".main-content", "#body").',
+                    },
+                },
+                required: ['url'],
+                handler: async (args) => {
+                    const url = args.url;
+                    const selector = args.selector;
+                    if (!url || typeof url !== 'string' || url.trim().length === 0) {
+                        return new SwaigFunctionResult('Please provide a URL to scrape.');
+                    }
+                    const trimmedUrl = url.trim();
+                    if (!trimmedUrl.startsWith('http://') && !trimmedUrl.startsWith('https://')) {
+                        return new SwaigFunctionResult('Invalid URL. Please provide a full URL starting with http:// or https://.');
+                    }
+                    const apiKey = process.env['SPIDER_API_KEY'];
+                    if (!apiKey) {
+                        return new SwaigFunctionResult('Spider scraping is not configured. The SPIDER_API_KEY environment variable is required.');
+                    }
+                    try {
+                        const requestBody = {
+                            url: trimmedUrl,
+                            return_format: 'markdown',
+                        };
+                        if (selector && typeof selector === 'string' && selector.trim().length > 0) {
+                            requestBody['css_selector'] = selector.trim();
+                        }
+                        const response = await fetch('https://api.spider.cloud/crawl', {
+                            method: 'POST',
+                            headers: {
+                                'Content-Type': 'application/json',
+                                'Authorization': `Bearer ${apiKey}`,
+                            },
+                            body: JSON.stringify(requestBody),
+                        });
+                        if (!response.ok) {
+                            const errorText = await response.text();
+                            return new SwaigFunctionResult(`Spider API returned an error (HTTP ${response.status}): ${errorText.slice(0, 300)}`);
+                        }
+                        const data = (await response.json());
+                        // Handle error responses
+                        if (!Array.isArray(data) && 'error' in data) {
+                            return new SwaigFunctionResult(`Spider scraping failed: ${data.error}`);
+                        }
+                        // Extract content from result
+                        let content = '';
+                        const result = Array.isArray(data) ? data[0] : data;
+                        if (!result) {
+                            return new SwaigFunctionResult(`No content could be extracted from "${trimmedUrl}".`);
+                        }
+                        if (result.error) {
+                            return new SwaigFunctionResult(`Error scraping "${trimmedUrl}": ${result.error}`);
+                        }
+                        // Prefer markdown > text > content
+                        content = result.markdown ?? result.text ?? result.content ?? '';
+                        if (content.trim().length === 0) {
+                            return new SwaigFunctionResult(`The page at "${trimmedUrl}" returned no extractable content.`);
+                        }
+                        // Truncate if necessary
+                        let truncated = false;
+                        if (content.length > maxContentLength) {
+                            content = content.slice(0, maxContentLength);
+                            truncated = true;
+                        }
+                        const parts = [
+                            `Content from ${trimmedUrl}:`,
+                            '',
+                            content.trim(),
+                        ];
+                        if (truncated) {
+                            parts.push('');
+                            parts.push(`[Content truncated to ${maxContentLength} characters]`);
+                        }
+                        return new SwaigFunctionResult(parts.join('\n'));
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        return new SwaigFunctionResult(`Failed to scrape "${trimmedUrl}": ${message}`);
+                    }
+                },
+            },
+        ];
+    }
+    /** @returns Prompt section describing web scraping capabilities and content limits. */
+    getPromptSections() {
+        return [
+            {
+                title: 'Web Page Scraping',
+                body: 'You can scrape and extract content from web pages.',
+                bullets: [
+                    'Use the scrape_url tool to fetch content from any public web page.',
+                    'Provide a full URL starting with http:// or https://.',
+                    'Optionally specify a CSS selector to extract specific parts of the page.',
+                    'Content is returned as markdown text for easy reading.',
+                    `Content is limited to ${this.getConfig('max_content_length', 5000)} characters.`,
+                    'Summarize the scraped content for the user rather than reading it verbatim.',
+                ],
+            },
+        ];
+    }
+}
+/**
+ * Factory function for creating SpiderSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new SpiderSkill instance.
+ */
+export function createSkill(config) {
+    return new SpiderSkill(config);
+}
+//# sourceMappingURL=spider.js.map

package/dist/skills/builtin/spider.js.map

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