prepia 1.0.0

package/src/edge/lite.mjs

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Lightweight edge-compatible mode with minimal memory footprint.
+ * @module edge/lite
+ */
+
+export class LiteMode {
+  /**
+   * @param {Object} [options]
+   * @param {boolean} [options.enableCache=true] - Enable caching
+   * @param {boolean} [options.enableAnalytics=false] - Disable analytics for speed
+   * @param {boolean} [options.enablePlugins=false] - Disable plugins
+   * @param {boolean} [options.enableP2P=false] - Disable P2P
+   */
+  constructor(options = {}) {
+    this._config = {
+      enableCache: options.enableCache ?? true,
+      enableAnalytics: options.enableAnalytics ?? false,
+      enablePlugins: options.enablePlugins ?? false,
+      enableP2P: options.enableP2P ?? false,
+    };
+  }
+
+  /**
+   * Get the feature flags for lite mode.
+   * @returns {Object}
+   */
+  getConfig() {
+    return { ...this._config };
+  }
+
+  /**
+   * Check if a feature is enabled.
+   * @param {string} feature
+   * @returns {boolean}
+   */
+  isEnabled(feature) {
+    return this._config[feature] ?? false;
+  }
+
+  /**
+   * Create a minimal engine configuration for edge deployment.
+   * @returns {Object}
+   */
+  createMinimalConfig() {
+    return {
+      cache: {
+        memoryMaxSize: 100,
+        memoryTTL: 60000,
+        enableDisk: false,
+      },
+      rate: {
+        providers: {},
+      },
+      tools: ['calculator', 'web-search'],
+      analytics: this._config.enableAnalytics,
+      plugins: this._config.enablePlugins,
+      p2p: this._config.enableP2P,
+    };
+  }
+
+  /**
+   * Estimate memory usage for the current configuration.
+   * @returns {Object}
+   */
+  estimateMemory() {
+    let bytes = 1024; // Base overhead
+    if (this._config.enableCache) bytes += 50 * 1024; // ~50KB for cache structures
+    if (this._config.enableAnalytics) bytes += 20 * 1024;
+    if (this._config.enablePlugins) bytes += 30 * 1024;
+    if (this._config.enableP2P) bytes += 40 * 1024;
+    return {
+      estimatedBytes: bytes,
+      estimatedKB: Math.round(bytes / 1024),
+      estimatedMB: Math.round(bytes / (1024 * 1024) * 100) / 100,
+    };
+  }
+
+  /**
+   * Enable or disable a feature.
+   * @param {string} feature
+   * @param {boolean} enabled
+   */
+  setFeature(feature, enabled) {
+    if (feature in this._config) {
+      this._config[feature] = enabled;
+    }
+  }
+}
+
+export default LiteMode;

package/src/guard/checker.mjs

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Output quality verification.
+ * @module guard/checker
+ */
+
+/**
+ * @typedef {Object} QualityScore
+ * @property {number} overall - Overall score (0-1)
+ * @property {number} completeness - How complete the answer is (0-1)
+ * @property {number} coherence - How coherent the text is (0-1)
+ * @property {number} relevance - How relevant to the query (0-1)
+ * @property {string[]} flags - Quality issues found
+ * @property {string[]} suggestions - Improvement suggestions
+ */
+
+/**
+ * Check the quality of an LLM output.
+ * @param {string} output - The LLM output text
+ * @param {Object} [context]
+ * @param {string} [context.query] - Original query
+ * @param {number} [context.expectedLength] - Expected output length
+ * @returns {QualityScore}
+ */
+export function checkQuality(output, context = {}) {
+  if (!output || typeof output !== 'string') {
+    return {
+      overall: 0,
+      completeness: 0,
+      coherence: 0,
+      relevance: 0,
+      flags: ['Empty or invalid output'],
+      suggestions: ['Provide a non-empty response'],
+    };
+  }
+
+  const flags = [];
+  const suggestions = [];
+  const trimmed = output.trim();
+
+  // Completeness check
+  let completeness = 1.0;
+  if (trimmed.length < 10) {
+    completeness -= 0.5;
+    flags.push('Output is very short');
+    suggestions.push('Provide a more detailed response');
+  }
+  if (trimmed.endsWith('...') || trimmed.endsWith('…')) {
+    completeness -= 0.3;
+    flags.push('Output appears truncated');
+  }
+  if (context.expectedLength && trimmed.length < context.expectedLength * 0.5) {
+    completeness -= 0.2;
+    flags.push('Output shorter than expected');
+  }
+
+  // Coherence check
+  let coherence = 1.0;
+  const sentences = trimmed.split(/[.!?]+/).filter(s => s.trim().length > 0);
+  if (sentences.length > 1) {
+    // Check for repetitive sentences
+    const unique = new Set(sentences.map(s => s.trim().toLowerCase()));
+    const repetitionRatio = unique.size / sentences.length;
+    if (repetitionRatio < 0.5) {
+      coherence -= 0.4;
+      flags.push('High repetition detected');
+      suggestions.push('Reduce repetitive content');
+    }
+  }
+  // Check for broken sentences
+  const brokenPattern = /\b(\w+)\s+\1\s+\1\b/g;
+  if (brokenPattern.test(trimmed)) {
+    coherence -= 0.3;
+    flags.push('Broken/repetitive text detected');
+  }
+
+  // Relevance check
+  let relevance = 0.8; // Default reasonable relevance
+  if (context.query) {
+    const queryWords = new Set(context.query.toLowerCase().split(/\s+/).filter(w => w.length > 3));
+    const outputWords = new Set(trimmed.toLowerCase().split(/\s+/));
+    let matches = 0;
+    for (const word of queryWords) {
+      if (outputWords.has(word)) matches++;
+    }
+    relevance = queryWords.size > 0 ? Math.min(1, matches / queryWords.size + 0.3) : 0.8;
+  }
+
+  // Check for common issues
+  if (/I (?:can't|cannot|am unable to|don't know)/i.test(trimmed)) {
+    flags.push('Output expresses uncertainty');
+  }
+  if (/sorry|apologize|apologies/i.test(trimmed) && trimmed.length < 100) {
+    completeness -= 0.3;
+    flags.push('Output is primarily an apology');
+  }
+
+  completeness = Math.max(0, Math.min(1, completeness));
+  coherence = Math.max(0, Math.min(1, coherence));
+  relevance = Math.max(0, Math.min(1, relevance));
+
+  const overall = (completeness * 0.4 + coherence * 0.3 + relevance * 0.3);
+
+  return {
+    overall: Math.round(overall * 100) / 100,
+    completeness: Math.round(completeness * 100) / 100,
+    coherence: Math.round(coherence * 100) / 100,
+    relevance: Math.round(relevance * 100) / 100,
+    flags,
+    suggestions,
+  };
+}
+
+/**
+ * Check if output passes minimum quality threshold.
+ * @param {string} output
+ * @param {number} [threshold=0.5]
+ * @returns {boolean}
+ */
+export function passesThreshold(output, threshold = 0.5) {
+  return checkQuality(output).overall >= threshold;
+}
+
+export default { checkQuality, passesThreshold };

package/src/guard/fact-checker.mjs

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Cross-reference verification against cached knowledge.
+ * @module guard/fact-checker
+ */
+
+/**
+ * @typedef {Object} FactCheckResult
+ * @property {boolean} verified - Whether claims could be verified
+ * @property {number} confidence - Confidence score (0-1)
+ * @property {Object[]} claims - Individual claim results
+ * @property {string[]} contradictions - Found contradictions
+ */
+
+/**
+ * Extract factual claims from text.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function extractClaims(text) {
+  if (!text) return [];
+  const claims = [];
+
+  // Sentences that look like factual claims
+  const sentences = text.split(/[.!?]+/).filter(s => s.trim().length > 10);
+
+  for (const sentence of sentences) {
+    const trimmed = sentence.trim();
+    // Skip questions and opinions
+    if (/^(what|who|when|where|why|how|is|are|do|does|can|could|would|should)\b/i.test(trimmed)) continue;
+    if (/^(i think|in my opinion|perhaps|maybe|it seems)/i.test(trimmed)) continue;
+
+    // Look for factual patterns
+    if (
+      /\d+/.test(trimmed) || // Contains numbers
+      /\b(is|are|was|were|has|have|had)\b/i.test(trimmed) || // State verbs
+      /\b(according to|research shows|studies indicate|data suggests)\b/i.test(trimmed) // Attribution
+    ) {
+      claims.push(trimmed);
+    }
+  }
+
+  return claims;
+}
+
+/**
+ * Verify claims against a knowledge base.
+ * @param {string} text - Text to fact-check
+ * @param {Object} knowledgeBase - Knowledge base instance
+ * @returns {Promise<FactCheckResult>}
+ */
+export async function factCheck(text, knowledgeBase) {
+  const claims = extractClaims(text);
+  if (claims.length === 0) {
+    return { verified: true, confidence: 0.5, claims: [], contradictions: [] };
+  }
+
+  const results = [];
+  const contradictions = [];
+  let totalConfidence = 0;
+
+  for (const claim of claims) {
+    const keywords = claim.toLowerCase().split(/\s+/).filter(w => w.length > 4);
+    const searchResults = await knowledgeBase.search(keywords.join(' '), { limit: 3 });
+
+    let verified = false;
+    let confidence = 0;
+
+    if (searchResults.length > 0) {
+      // Check if any knowledge entry supports or contradicts the claim
+      for (const entry of searchResults) {
+        const entryText = typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value);
+        const claimWords = new Set(claim.toLowerCase().split(/\s+/));
+        const entryWords = new Set(entryText.toLowerCase().split(/\s+/));
+
+        let overlap = 0;
+        for (const word of claimWords) {
+          if (entryWords.has(word) && word.length > 3) overlap++;
+        }
+
+        const similarity = overlap / Math.max(claimWords.size, 1);
+        if (similarity > 0.3) {
+          verified = true;
+          confidence = Math.min(1, similarity + (entry.confidence || 0.5) * 0.3);
+        }
+      }
+    }
+
+    // Heuristic confidence for unverified claims
+    if (!verified) {
+      confidence = 0.3; // Low confidence for unverifiable claims
+    }
+
+    totalConfidence += confidence;
+    results.push({ claim, verified, confidence });
+  }
+
+  return {
+    verified: results.every(r => r.verified),
+    confidence: claims.length > 0 ? totalConfidence / claims.length : 0.5,
+    claims: results,
+    contradictions,
+  };
+}
+
+export default { extractClaims, factCheck };

package/src/guard/hallucination.mjs

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Hallucination detection patterns.
+ * @module guard/hallucination
+ */
+
+/**
+ * @typedef {Object} HallucinationResult
+ * @property {boolean} detected - Whether hallucination patterns were found
+ * @property {number} score - Hallucination likelihood (0-1, higher = more likely)
+ * @property {Object[]} flags - Specific issues found
+ */
+
+/**
+ * Detect potential hallucinations in LLM output.
+ * @param {string} text - LLM output to check
+ * @returns {HallucinationResult}
+ */
+export function detectHallucination(text) {
+  if (!text || typeof text !== 'string') {
+    return { detected: false, score: 0, flags: [] };
+  }
+
+  const flags = [];
+  let score = 0;
+
+  // Check for suspicious URLs
+  const urlPattern = /https?:\/\/[^\s]+/g;
+  const urls = text.match(urlPattern) || [];
+  for (const url of urls) {
+    // Check for obviously fake domains
+    if (/\.xyz\b|\.tk\b|\.ml\b|\.ga\b|\.cf\b/i.test(url)) {
+      flags.push({ type: 'suspicious_url', detail: `Suspicious TLD: ${url}` });
+      score += 0.3;
+    }
+    // Check for made-up-looking paths
+    if (/\/[a-z]{20,}\//i.test(url)) {
+      flags.push({ type: 'suspicious_url', detail: `Suspiciously long path: ${url}` });
+      score += 0.2;
+    }
+  }
+
+  // Check for fake statistics
+  const statPatterns = [
+    /(?:approximately|about|roughly|around)\s+\d+\.?\d*\s*%/gi,
+    /\d+\.?\d*\s*(?:percent|percentage)\s+of/gi,
+    /studies?\s+(?:show|indicate|suggest|found)\s+that\s+\d+/gi,
+    /according\s+to\s+(?:a\s+)?(?:recent|new|latest)\s+(?:study|research|report)/gi,
+  ];
+  for (const pattern of statPatterns) {
+    const matches = text.match(pattern) || [];
+    for (const match of matches) {
+      // Vague attribution is suspicious
+      if (/according to (?:a |the )?(?:recent|new|latest|some)/i.test(match)) {
+        flags.push({ type: 'vague_attribution', detail: match });
+        score += 0.2;
+      }
+    }
+  }
+
+  // Check for invented quotes
+  const quotePattern = /[""]([^""]{20,})[""](?:\s*[-–—]\s*(?:\w+)|(?:\s+said\s+))/g;
+  let quoteMatch;
+  while ((quoteMatch = quotePattern.exec(text)) !== null) {
+    // Quotes without proper attribution
+    if (!/(?:said|stated|wrote|according to|noted|explained)\s+\w+\s+\w+/.test(text.substring(Math.max(0, quoteMatch.index - 50), quoteMatch.index + quoteMatch[0].length + 50))) {
+      flags.push({ type: 'unverified_quote', detail: quoteMatch[0].substring(0, 80) });
+      score += 0.2;
+    }
+  }
+
+  // Check for overly specific numbers without sources
+  const specificStats = text.match(/\b\d{1,3}(?:,\d{3})+(?:\.\d+)?\b/g) || [];
+  if (specificStats.length > 3 && !/source|reference|study|report|data|census|survey/i.test(text)) {
+    flags.push({ type: 'unsourced_statistics', detail: `${specificStats.length} specific numbers without sources` });
+    score += 0.15;
+  }
+
+  // Check for hedging language that might indicate uncertainty
+  const hedging = (text.match(/\b(may|might|could|possibly|perhaps|allegedly|reportedly|supposedly)\b/gi) || []).length;
+  if (hedging > 5) {
+    flags.push({ type: 'excessive_hedging', detail: `${hedging} hedging words detected` });
+    score += 0.1;
+  }
+
+  // Check for contradictory statements
+  const contradictions = [
+    { positive: /\balways\b/gi, negative: /\bnever\b/gi },
+    { positive: /\bincrease[sd]?\b/gi, negative: /\bdecrease[sd]?\b/gi },
+    { positive: /\bmore\b/gi, negative: /\bless\b/gi },
+  ];
+  for (const { positive, negative } of contradictions) {
+    const posMatches = text.match(positive) || [];
+    const negMatches = text.match(negative) || [];
+    if (posMatches.length > 0 && negMatches.length > 2) {
+      flags.push({ type: 'potential_contradiction', detail: 'Contains both positive and negative qualifiers' });
+      score += 0.1;
+      break;
+    }
+  }
+
+  return {
+    detected: score > 0.3,
+    score: Math.min(1, score),
+    flags,
+  };
+}
+
+export default { detectHallucination };

package/src/index.mjs

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Prepia - AI middleware that reduces LLM quota usage by 80-95%.
+ * Main entry point and public API.
+ * @module prepia
+ */
+
+export { PrepiaEngine } from './core/engine.mjs';
+export { decompose, partitionTasks } from './core/task-decomposer.mjs';
+export { packageContext, estimateTokens } from './core/context-packager.mjs';
+export { generatePrompt, mergePrompts } from './core/prepimshot.mjs';
+export { emit, on, once, off, removeAll } from './core/event-bus.mjs';
+
+export { Orchestrator } from './tools/orchestrator.mjs';
+export { search as webSearch } from './tools/web-search.mjs';
+export { scrape as webScrape } from './tools/web-scraper.mjs';
+export { evaluate as calculate } from './tools/calculator.mjs';
+export * as fileOps from './tools/file-ops.mjs';
+export * as httpClient from './tools/http-client.mjs';
+
+export { CacheManager } from './cache/manager.mjs';
+export { MemoryStore } from './cache/memory-store.mjs';
+export { DiskStore } from './cache/disk-store.mjs';
+
+export { ModelRouter } from './models/router.mjs';
+export { classify, canHandleLocally, getLocalResponse, Complexity } from './models/local-model.mjs';
+export * as provider from './models/provider.mjs';
+
+export { RateShield } from './rate/shield.mjs';
+export { TokenBucket, SlidingWindow } from './rate/limiter.mjs';
+
+export { DAG } from './chain/dag.mjs';
+export { Scheduler } from './chain/scheduler.mjs';
+export { Executor } from './chain/executor.mjs';
+
+export { KnowledgeBase } from './vault/knowledge-base.mjs';
+export { PatternLearner } from './vault/pattern-learner.mjs';
+
+export { PluginLoader } from './plugins/loader.mjs';
+export { PluginRegistry } from './plugins/registry.mjs';
+export { Sandbox } from './plugins/sandbox.mjs';
+
+export { checkQuality, passesThreshold } from './guard/checker.mjs';
+export { factCheck, extractClaims } from './guard/fact-checker.mjs';
+export { detectHallucination } from './guard/hallucination.mjs';
+
+export { detectPersona, getPersonas, getPersona } from './persona/detector.mjs';
+
+export { Tracker } from './analytics/tracker.mjs';
+export { generateReport, generateSummary } from './analytics/dashboard.mjs';
+
+export { StreamHandler, Phases } from './stream/handler.mjs';
+
+export { sanitize, validateParams, sanitizeOutput } from './security/sanitizer.mjs';
+export { detectPII, redactPII, containsPII } from './security/privacy.mjs';
+
+export { Daemon } from './shadow/daemon.mjs';
+export { LiteMode } from './edge/lite.mjs';
+export { Optimizer } from './morph/optimizer.mjs';
+export { P2PNetwork } from './network/p2p.mjs';
+
+export { parse as parseScript, validate as validateScript } from './script/parser.mjs';
+export { ScriptExecutor } from './script/executor.mjs';
+
+export { Server, createServer } from './api/server.mjs';
+
+/** Version */
+export const VERSION = '1.0.0';

package/src/models/local-model.mjs

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview Lightweight local pattern matching / rule engine.
+ * Handles common queries without LLM calls.
+ * @module models/local-model
+ */
+
+/**
+ * Query complexity levels.
+ * @enum {string}
+ */
+export const Complexity = {
+  SIMPLE: 'simple',
+  MEDIUM: 'medium',
+  COMPLEX: 'complex',
+};
+
+/**
+ * Pattern definitions for local matching.
+ */
+const PATTERNS = [
+  // Greetings
+  {
+    pattern: /^(hi|hello|hey|greetings|good\s+(morning|afternoon|evening))[\s!.]*$/i,
+    handler: () => ({ content: 'Hello! How can I help you?', type: 'greeting', complexity: Complexity.SIMPLE }),
+  },
+  // Time/date queries
+  {
+    pattern: /what\s+(?:time|date|day)\s+is\s+it|what(?:'s| is) (?:the )?(?:current )?(?:time|date|day)/i,
+    handler: () => {
+      const now = new Date();
+      return {
+        content: `Current date and time: ${now.toISOString()}`,
+        type: 'datetime',
+        complexity: Complexity.SIMPLE,
+      };
+    },
+  },
+  // Simple math
+  {
+    pattern: /^[\d\s+\-*/().%^]+$/,
+    handler: (query) => {
+      try {
+        // Simple arithmetic validation - must only contain math chars
+        const cleaned = query.replace(/\s/g, '');
+        if (!/^[\d+\-*/().%^]+$/.test(cleaned)) return null;
+        // Use Function constructor for safe eval (no access to globals)
+        const result = new Function(`"use strict"; return (${cleaned})`)();
+        if (typeof result === 'number' && isFinite(result)) {
+          return { content: String(result), type: 'math', complexity: Complexity.SIMPLE };
+        }
+      } catch {}
+      return null;
+    },
+  },
+  // Unit conversions
+  {
+    pattern: /(\d+\.?\d*)\s*(km|mi|miles?|meters?|feet|ft|inches?|in|cm|mm|kg|lbs?|pounds?|oz|ounces?|g|grams?|celsius|fahrenheit|°[cf])\s+(?:to|in|as)\s+(km|mi|miles?|meters?|feet|ft|inches?|in|cm|mm|kg|lbs?|pounds?|oz|ounces?|g|grams?|celsius|fahrenheit|°[cf])/i,
+    handler: () => null, // Handled by calculator
+  },
+  // Yes/no questions
+  {
+    pattern: /^(is|are|was|were|do|does|did|can|could|will|would|should|has|have)\s/i,
+    handler: (query) => ({
+      content: null, // Needs LLM
+      type: 'question',
+      complexity: Complexity.MEDIUM,
+      hint: 'This appears to be a factual question that may benefit from web search.',
+    }),
+  },
+  // Definitions
+  {
+    pattern: /^what(?:'s| is| are)\s+(?:a |an |the )?(.+)/i,
+    handler: (query, match) => ({
+      content: null,
+      type: 'definition',
+      topic: match[1],
+      complexity: Complexity.MEDIUM,
+    }),
+  },
+  // How-to
+  {
+    pattern: /^how\s+(?:do|to|can)\s+(.+)/i,
+    handler: (query, match) => ({
+      content: null,
+      type: 'howto',
+      topic: match[1],
+      complexity: Complexity.MEDIUM,
+    }),
+  },
+  // Summarize requests
+  {
+    pattern: /^(summarize|summarise|tldr|tl;dr|brief)\s/i,
+    handler: () => ({
+      content: null,
+      type: 'summarization',
+      complexity: Complexity.MEDIUM,
+    }),
+  },
+];
+
+/**
+ * Classify and attempt to handle a query locally.
+ * @param {string} query - User query
+ * @returns {Object} Result with content (if handled locally), type, and complexity
+ */
+export function classify(query) {
+  if (typeof query !== 'string') {
+    return { content: null, type: 'unknown', complexity: Complexity.COMPLEX };
+  }
+
+  const trimmed = query.trim();
+  if (trimmed.length === 0) {
+    return { content: '', type: 'empty', complexity: Complexity.SIMPLE };
+  }
+
+  for (const { pattern, handler } of PATTERNS) {
+    const match = trimmed.match(pattern);
+    if (match) {
+      const result = handler(trimmed, match);
+      if (result) return result;
+    }
+  }
+
+  // Default: needs LLM
+  return {
+    content: null,
+    type: 'general',
+    complexity: estimateComplexity(trimmed),
+  };
+}
+
+/**
+ * Estimate query complexity based on heuristics.
+ * @param {string} query
+ * @returns {string}
+ */
+function estimateComplexity(query) {
+  const wordCount = query.split(/\s+/).length;
+  const hasMultipleQuestions = (query.match(/\?/g) || []).length > 1;
+  const hasConjunctions = /\b(and|but|or|however|although|because)\b/i.test(query);
+
+  if (wordCount < 10 && !hasMultipleQuestions && !hasConjunctions) {
+    return Complexity.SIMPLE;
+  }
+  if (wordCount > 30 || hasMultipleQuestions || (wordCount > 15 && hasConjunctions)) {
+    return Complexity.COMPLEX;
+  }
+  return Complexity.MEDIUM;
+}
+
+/**
+ * Check if a query can be fully handled locally (no LLM needed).
+ * @param {string} query
+ * @returns {boolean}
+ */
+export function canHandleLocally(query) {
+  const result = classify(query);
+  return result.content !== null && result.content !== undefined;
+}
+
+/**
+ * Get a local response for a query (returns null if LLM needed).
+ * @param {string} query
+ * @returns {string|null}
+ */
+export function getLocalResponse(query) {
+  const result = classify(query);
+  return result.content;
+}
+
+export default { classify, canHandleLocally, getLocalResponse, Complexity };