prepia 1.0.0

package/src/tools/web-search.mjs

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Web search using Node 22 global fetch.
+ * @module tools/web-search
+ */
+
+/**
+ * @typedef {Object} SearchResult
+ * @property {string} title - Result title
+ * @property {string} url - Result URL
+ * @property {string} snippet - Result snippet/description
+ * @property {string} source - Search engine used
+ */
+
+/**
+ * Search the web using DuckDuckGo HTML (no API key needed).
+ * @param {string} query - Search query
+ * @param {Object} [options]
+ * @param {number} [options.maxResults=10] - Max results to return
+ * @param {string} [options.engine='duckduckgo'] - Search engine
+ * @returns {Promise<SearchResult[]>}
+ */
+export async function search(query, options = {}) {
+  if (!query || typeof query !== 'string') {
+    throw new Error('Query must be a non-empty string');
+  }
+
+  const { maxResults = 10, engine = 'duckduckgo' } = options;
+
+  switch (engine) {
+    case 'duckduckgo':
+      return searchDuckDuckGo(query, maxResults);
+    case 'wikipedia':
+      return searchWikipedia(query, maxResults);
+    default:
+      return searchDuckDuckGo(query, maxResults);
+  }
+}
+
+/**
+ * Search using DuckDuckGo HTML version.
+ * @param {string} query
+ * @param {number} maxResults
+ * @returns {Promise<SearchResult[]>}
+ */
+async function searchDuckDuckGo(query, maxResults) {
+  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+  try {
+    const response = await fetch(url, {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (compatible; Prepia/1.0)',
+      },
+      signal: AbortSignal.timeout(15000),
+    });
+    const html = await response.text();
+    return parseDuckDuckGoResults(html, maxResults);
+  } catch (err) {
+    throw new Error(`DuckDuckGo search failed: ${err.message}`);
+  }
+}
+
+/**
+ * Parse DuckDuckGo HTML results.
+ * @param {string} html
+ * @param {number} maxResults
+ * @returns {SearchResult[]}
+ */
+function parseDuckDuckGoResults(html, maxResults) {
+  const results = [];
+  // Match result blocks
+  const resultPattern = /<a[^>]+class="result__a"[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gs;
+  const snippetPattern = /<a[^>]+class="result__snippet"[^>]*>(.*?)<\/a>/gs;
+
+  const links = [];
+  let match;
+
+  // Extract links
+  while ((match = resultPattern.exec(html)) !== null && links.length < maxResults) {
+    let url = match[1];
+    // DuckDuckGo uses redirect URLs
+    const uddgMatch = url.match(/uddg=([^&]+)/);
+    if (uddgMatch) url = decodeURIComponent(uddgMatch[1]);
+    const title = match[2].replace(/<[^>]*>/g, '').trim();
+    if (title && url) links.push({ title, url });
+  }
+
+  // Extract snippets
+  const snippets = [];
+  while ((match = snippetPattern.exec(html)) !== null) {
+    snippets.push(match[1].replace(/<[^>]*>/g, '').trim());
+  }
+
+  for (let i = 0; i < links.length && i < maxResults; i++) {
+    results.push({
+      title: links[i].title,
+      url: links[i].url,
+      snippet: snippets[i] || '',
+      source: 'duckduckgo',
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Search Wikipedia API.
+ * @param {string} query
+ * @param {number} maxResults
+ * @returns {Promise<SearchResult[]>}
+ */
+async function searchWikipedia(query, maxResults) {
+  const url = `https://en.wikipedia.org/w/api.php?action=query&list=search&srsearch=${encodeURIComponent(query)}&srlimit=${maxResults}&format=json`;
+  try {
+    const response = await fetch(url, {
+      headers: { 'User-Agent': 'Prepia/1.0' },
+      signal: AbortSignal.timeout(15000),
+    });
+    const data = await response.json();
+    return (data.query?.search || []).map(item => ({
+      title: item.title,
+      url: `https://en.wikipedia.org/wiki/${encodeURIComponent(item.title)}`,
+      snippet: item.snippet.replace(/<[^>]*>/g, '').trim(),
+      source: 'wikipedia',
+    }));
+  } catch (err) {
+    throw new Error(`Wikipedia search failed: ${err.message}`);
+  }
+}
+
+export default { search };

package/src/vault/knowledge-base.mjs

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview Persistent knowledge storage with relevance search.
+ * @module vault/knowledge-base
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export class KnowledgeBase {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.storagePath='.prepia/knowledge'] - Storage directory
+   * @param {number} [options.maxEntries=10000] - Max entries
+   * @param {number} [options.defaultTTL=86400000] - Default TTL (24h)
+   */
+  constructor(options = {}) {
+    this._storagePath = options.storagePath ?? '.prepia/knowledge';
+    this._maxEntries = options.maxEntries ?? 10000;
+    this._defaultTTL = options.defaultTTL ?? 24 * 60 * 60 * 1000;
+    /** @type {Map<string, Object>} */
+    this._entries = new Map();
+    this._initialized = false;
+  }
+
+  /**
+   * Initialize - load from disk if available.
+   */
+  async init() {
+    if (this._initialized) return;
+    try {
+      await fs.mkdir(this._storagePath, { recursive: true });
+      const indexFile = path.join(this._storagePath, 'index.json');
+      const data = await fs.readFile(indexFile, 'utf-8');
+      const entries = JSON.parse(data);
+      for (const entry of entries) {
+        this._entries.set(entry.key, entry);
+      }
+    } catch {
+      // No existing data or parse error
+    }
+    this._initialized = true;
+  }
+
+  /**
+   * Store knowledge.
+   * @param {string} key - Unique key
+   * @param {*} value - Value to store
+   * @param {Object} [options]
+   * @param {string[]} [options.tags] - Tags for categorization
+   * @param {string} [options.source] - Source of the knowledge
+   * @param {number} [options.ttl] - TTL in ms
+   * @param {number} [options.confidence=1] - Confidence score (0-1)
+   */
+  async store(key, value, options = {}) {
+    await this.init();
+    const now = Date.now();
+    this._entries.set(key, {
+      key,
+      value,
+      tags: options.tags || [],
+      source: options.source || '',
+      confidence: options.confidence ?? 1,
+      createdAt: now,
+      updatedAt: now,
+      expiresAt: now + (options.ttl ?? this._defaultTTL),
+      accessCount: 0,
+      lastAccessed: null,
+    });
+
+    // Evict if over limit
+    if (this._entries.size > this._maxEntries) {
+      const oldest = Array.from(this._entries.values())
+        .sort((a, b) => a.updatedAt - b.updatedAt)[0];
+      if (oldest) this._entries.delete(oldest.key);
+    }
+
+    await this._persist();
+  }
+
+  /**
+   * Retrieve knowledge by key.
+   * @param {string} key
+   * @returns {Promise<*>} The stored value or undefined
+   */
+  async get(key) {
+    await this.init();
+    const entry = this._entries.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this._entries.delete(key);
+      return undefined;
+    }
+    entry.accessCount++;
+    entry.lastAccessed = Date.now();
+    return entry.value;
+  }
+
+  /**
+   * Search knowledge by relevance.
+   * @param {string} query - Search query
+   * @param {Object} [options]
+   * @param {string[]} [options.tags] - Filter by tags
+   * @param {number} [options.limit=10] - Max results
+   * @returns {Promise<Object[]>}
+   */
+  async search(query, options = {}) {
+    await this.init();
+    const { tags, limit = 10 } = options;
+    const now = Date.now();
+    const queryLower = query.toLowerCase();
+    const queryWords = queryLower.split(/\s+/).filter(w => w.length > 2);
+
+    const scored = [];
+    for (const entry of this._entries.values()) {
+      if (now > entry.expiresAt) continue;
+      if (tags && !tags.some(t => entry.tags.includes(t))) continue;
+
+      let score = 0;
+      const valueStr = typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value);
+      const valueLower = valueStr.toLowerCase();
+
+      // Exact match bonus
+      if (valueLower.includes(queryLower)) score += 10;
+
+      // Word match
+      for (const word of queryWords) {
+        if (valueLower.includes(word)) score += 2;
+        if (entry.key.toLowerCase().includes(word)) score += 3;
+        if (entry.tags.some(t => t.toLowerCase().includes(word))) score += 5;
+      }
+
+      // Confidence and recency boost
+      score *= entry.confidence;
+      score += (entry.accessCount || 0) * 0.1;
+
+      if (score > 0) {
+        scored.push({ ...entry, score });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit).map(({ score, ...rest }) => rest);
+  }
+
+  /**
+   * Delete knowledge by key.
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    await this.init();
+    const deleted = this._entries.delete(key);
+    if (deleted) await this._persist();
+    return deleted;
+  }
+
+  /**
+   * Get the number of entries.
+   * @returns {Promise<number>}
+   */
+  async size() {
+    await this.init();
+    return this._entries.size;
+  }
+
+  /**
+   * Clear all knowledge.
+   */
+  async clear() {
+    this._entries.clear();
+    await this._persist();
+  }
+
+  /**
+   * Remove expired entries.
+   * @returns {Promise<number>}
+   */
+  async cleanup() {
+    await this.init();
+    const now = Date.now();
+    let removed = 0;
+    for (const [key, entry] of this._entries) {
+      if (now > entry.expiresAt) {
+        this._entries.delete(key);
+        removed++;
+      }
+    }
+    if (removed > 0) await this._persist();
+    return removed;
+  }
+
+  /**
+   * Persist to disk.
+   * @private
+   */
+  async _persist() {
+    try {
+      const indexFile = path.join(this._storagePath, 'index.json');
+      await fs.writeFile(indexFile, JSON.stringify(Array.from(this._entries.values()), null, 2));
+    } catch {
+      // Silently fail persistence
+    }
+  }
+}
+
+export default KnowledgeBase;

package/src/vault/pattern-learner.mjs

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Learns user query patterns over time.
+ * @module vault/pattern-learner
+ */
+
+export class PatternLearner {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.maxPatterns=500] - Max patterns to track
+   * @param {number} [options.minOccurrences=2] - Min occurrences to be a pattern
+   */
+  constructor(options = {}) {
+    this._maxPatterns = options.maxPatterns ?? 500;
+    this._minOccurrences = options.minOccurrences ?? 2;
+    /** @type {Map<string, Object>} */
+    this._patterns = new Map();
+    /** @type {string[]} Recent query history */
+    this._history = [];
+    this._maxHistory = 100;
+  }
+
+  /**
+   * Record a query and its outcome.
+   * @param {string} query - User query
+   * @param {Object} outcome - { type, tools, success, duration }
+   */
+  record(query, outcome = {}) {
+    const normalized = this._normalize(query);
+    const existing = this._patterns.get(normalized);
+
+    if (existing) {
+      existing.count++;
+      existing.lastSeen = Date.now();
+      existing.successRate = ((existing.successRate * (existing.count - 1)) + (outcome.success ? 1 : 0)) / existing.count;
+      if (outcome.tools) {
+        for (const tool of outcome.tools) {
+          existing.tools.set(tool, (existing.tools.get(tool) || 0) + 1);
+        }
+      }
+    } else {
+      const tools = new Map();
+      if (outcome.tools) {
+        for (const tool of outcome.tools) {
+          tools.set(tool, 1);
+        }
+      }
+      this._patterns.set(normalized, {
+        pattern: normalized,
+        original: query,
+        count: 1,
+        firstSeen: Date.now(),
+        lastSeen: Date.now(),
+        successRate: outcome.success ? 1 : 0,
+        tools,
+        type: outcome.type || 'unknown',
+      });
+    }
+
+    this._history.push({ query, timestamp: Date.now(), ...outcome });
+    if (this._history.length > this._maxHistory) {
+      this._history.shift();
+    }
+
+    // Evict old patterns if over limit
+    if (this._patterns.size > this._maxPatterns) {
+      const oldest = Array.from(this._patterns.values())
+        .filter(p => p.count < this._minOccurrences)
+        .sort((a, b) => a.lastSeen - b.lastSeen)[0];
+      if (oldest) this._patterns.delete(oldest.pattern);
+    }
+  }
+
+  /**
+   * Get patterns similar to a query.
+   * @param {string} query
+   * @param {number} [limit=5]
+   * @returns {Object[]}
+   */
+  findSimilar(query, limit = 5) {
+    const normalized = this._normalize(query);
+    const queryWords = normalized.split(/\s+/);
+
+    const scored = [];
+    for (const pattern of this._patterns.values()) {
+      if (pattern.count < this._minOccurrences) continue;
+      const patternWords = pattern.pattern.split(/\s+/);
+      let overlap = 0;
+      for (const word of queryWords) {
+        if (patternWords.includes(word)) overlap++;
+      }
+      const similarity = overlap / Math.max(queryWords.length, patternWords.length);
+      if (similarity > 0.2) {
+        scored.push({ ...pattern, similarity, tools: Object.fromEntries(pattern.tools || new Map()) });
+      }
+    }
+
+    scored.sort((a, b) => b.similarity - a.similarity || b.count - a.count);
+    return scored.slice(0, limit);
+  }
+
+  /**
+   * Predict likely next queries based on recent history.
+   * @param {number} [limit=3]
+   * @returns {string[]}
+   */
+  predictNext(limit = 3) {
+    if (this._history.length < 2) return [];
+
+    const recent = this._history.slice(-5).map(h => this._normalize(h.query));
+    const predictions = new Map();
+
+    for (const pattern of this._patterns.values()) {
+      if (pattern.count < this._minOccurrences) continue;
+      for (const recentQuery of recent) {
+        const similarity = this._similarity(pattern.pattern, recentQuery);
+        if (similarity > 0.3 && similarity < 1.0) {
+          predictions.set(pattern.pattern, (predictions.get(pattern.pattern) || 0) + similarity * pattern.count);
+        }
+      }
+    }
+
+    return Array.from(predictions.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, limit)
+      .map(([pattern]) => pattern);
+  }
+
+  /**
+   * Get all learned patterns.
+   * @returns {Object[]}
+   */
+  getAllPatterns() {
+    return Array.from(this._patterns.values())
+      .filter(p => p.count >= this._minOccurrences)
+      .sort((a, b) => b.count - a.count)
+      .map(p => ({ ...p, tools: Object.fromEntries(p.tools || new Map()) }));
+  }
+
+  /**
+   * Get recent query history.
+   * @param {number} [limit=20]
+   * @returns {Object[]}
+   */
+  getHistory(limit = 20) {
+    return this._history.slice(-limit);
+  }
+
+  /**
+   * Get the number of tracked patterns.
+   * @returns {number}
+   */
+  get size() {
+    return this._patterns.size;
+  }
+
+  /**
+   * Clear all patterns and history.
+   */
+  clear() {
+    this._patterns.clear();
+    this._history = [];
+  }
+
+  /**
+   * Normalize a query for pattern matching.
+   * @param {string} query
+   * @returns {string}
+   * @private
+   */
+  _normalize(query) {
+    return query.toLowerCase().trim().replace(/[^\w\s]/g, '').replace(/\s+/g, ' ');
+  }
+
+  /**
+   * Calculate similarity between two strings.
+   * @param {string} a
+   * @param {string} b
+   * @returns {number} 0-1
+   * @private
+   */
+  _similarity(a, b) {
+    const wordsA = new Set(a.split(/\s+/));
+    const wordsB = new Set(b.split(/\s+/));
+    let intersection = 0;
+    for (const word of wordsA) {
+      if (wordsB.has(word)) intersection++;
+    }
+    return intersection / Math.max(wordsA.size, wordsB.size);
+  }
+}
+
+export default PatternLearner;

package/workflows/analyze.json

@@ -0,0 +1,32 @@
+{
+  "name": "analyze",
+  "description": "Data gathering and analysis",
+  "mode": "shot",
+  "steps": [
+    {
+      "keyword": "SEARCH",
+      "description": "Gather relevant data",
+      "params": { "maxResults": 10 }
+    },
+    {
+      "keyword": "EXTRACT",
+      "description": "Extract numerical data and facts",
+      "params": { "extractNumbers": true }
+    },
+    {
+      "keyword": "FORMAT",
+      "description": "Structure data for analysis",
+      "params": { "format": "json" }
+    },
+    {
+      "keyword": "DELIVER",
+      "description": "Analyze and present findings",
+      "params": { "includeCharts": false, "includeInsights": true }
+    }
+  ],
+  "options": {
+    "enableCalculation": true,
+    "enableVisualization": false,
+    "outputFormat": "markdown"
+  }
+}

package/workflows/automate.json

@@ -0,0 +1,32 @@
+{
+  "name": "automate",
+  "description": "Multi-step task automation",
+  "mode": "shot",
+  "steps": [
+    {
+      "keyword": "SEARCH",
+      "description": "Research automation approach",
+      "params": { "maxResults": 5 }
+    },
+    {
+      "keyword": "EXTRACT",
+      "description": "Extract relevant procedures and methods",
+      "params": { "maxLength": 20000 }
+    },
+    {
+      "keyword": "FORMAT",
+      "description": "Structure automation plan",
+      "params": { "format": "steps" }
+    },
+    {
+      "keyword": "DELIVER",
+      "description": "Generate automation instructions",
+      "params": { "stepByStep": true, "includeWarnings": true }
+    }
+  ],
+  "options": {
+    "enableExecution": false,
+    "dryRun": true,
+    "outputFormat": "markdown"
+  }
+}

package/workflows/research.json

@@ -0,0 +1,37 @@
+{
+  "name": "research",
+  "description": "Multi-source web research with fact-checking",
+  "mode": "shot",
+  "steps": [
+    {
+      "keyword": "SEARCH",
+      "description": "Search multiple sources for information",
+      "params": { "engines": ["duckduckgo", "wikipedia"], "maxResults": 5 }
+    },
+    {
+      "keyword": "EXTRACT",
+      "description": "Extract key content from search results",
+      "params": { "maxLength": 10000 }
+    },
+    {
+      "keyword": "FILTER",
+      "description": "Filter for relevance and recency",
+      "params": { "minRelevance": 0.3 }
+    },
+    {
+      "keyword": "FORMAT",
+      "description": "Format findings for LLM consumption",
+      "params": { "format": "structured" }
+    },
+    {
+      "keyword": "DELIVER",
+      "description": "Synthesize final answer with LLM",
+      "params": { "verify": true, "cite": true }
+    }
+  ],
+  "options": {
+    "enableFactCheck": true,
+    "maxTokens": 4000,
+    "outputFormat": "markdown"
+  }
+}

package/workflows/summarize.json

@@ -0,0 +1,32 @@
+{
+  "name": "summarize",
+  "description": "Content compression and summarization",
+  "mode": "shot",
+  "steps": [
+    {
+      "keyword": "EXTRACT",
+      "description": "Extract main content from source",
+      "params": { "stripHtml": true, "maxLength": 50000 }
+    },
+    {
+      "keyword": "FILTER",
+      "description": "Remove boilerplate and noise",
+      "params": { "removeAds": true, "removeNav": true }
+    },
+    {
+      "keyword": "FORMAT",
+      "description": "Prepare for summarization",
+      "params": { "format": "text" }
+    },
+    {
+      "keyword": "DELIVER",
+      "description": "Generate summary with LLM",
+      "params": { "style": "concise", "maxLength": 500 }
+    }
+  ],
+  "options": {
+    "compressionRatio": 0.2,
+    "preserveKeyPoints": true,
+    "outputFormat": "text"
+  }
+}