prepia 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prepia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# Prepia
+
+**AI Middleware that reduces LLM quota usage by 80-95%**
+
+Prepia is a smart middleware layer that sits between AI agents and LLMs. Instead of making many LLM calls for complex tasks, Prepia handles the heavy lifting (searching, scraping, processing, caching) and sends ONE optimized call to the LLM.
+
+## Architecture
+
+```
+                    ┌─────────────────────────────────────┐
+                    │           AI Agent / Client          │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │          Prepia API Server           │
+                    │      (REST / CLI / Programmatic)     │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │           Core Engine                │
+                    │  ┌─────────┬──────────┬───────────┐ │
+                    │  │ Task    │ Context  │ PrepiShot │ │
+                    │  │Decompose│ Packager │ Optimizer │ │
+                    │  └────┬────┴────┬─────┴─────┬─────┘ │
+                    └───────┼─────────┼───────────┼───────┘
+                            │         │           │
+         ┌──────────────────┼─────────┼───────────┼──────────────────┐
+         │                  │         │           │                  │
+    ┌────▼────┐      ┌─────▼────┐ ┌──▼───┐ ┌────▼─────┐   ┌───────▼──────┐
+    │  Tools  │      │  Cache   │ │Models│ │  Chain   │   │   Security   │
+    │Orchestr.│      │ Manager  │ │Router│ │Scheduler │   │  Sanitizer   │
+    └────┬────┘      └──────────┘ └──────┘ └──────────┘   └──────────────┘
+         │
+    ┌────┼────┬────────┬──────────┐
+    │    │    │        │          │
+  Web  Web  File   Calc    HTTP
+ Search Scraper Ops  ulator  Client
+```
+
+## Installation
+
+```bash
+# Clone or copy the prepia directory
+cd prepia
+
+# No npm install needed - uses only Node.js built-in modules!
+# Requires Node.js >= 22.0.0
+
+# Make CLI executable
+chmod +x bin/prepia.mjs
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Process a simple query (flash mode - instant, no LLM)
+node bin/prepia.mjs process "What is 15% of 200?" --mode flash
+
+# Process with one LLM call (shot mode - default)
+node bin/prepia.mjs process "Explain quantum computing"
+
+# Start the API server
+node bin/prepia.mjs serve --port 3000
+
+# View analytics
+node bin/prepia.mjs analytics
+```
+
+### Programmatic
+
+```javascript
+import { PrepiaEngine } from './src/index.mjs';
+
+const engine = new PrepiaEngine();
+
+// Flash mode - handles locally, no LLM needed
+const result = await engine.process('Calculate 15% of 200', { mode: 'flash' });
+console.log(result.answer); // "30"
+
+// Shot mode - one optimized LLM call
+const result2 = await engine.process('Summarize the latest AI trends', { mode: 'shot' });
+console.log(result2.answer);
+
+// Get analytics
+const analytics = engine.getAnalytics();
+console.log(analytics.metrics);
+```
+
+### API
+
+```bash
+# Start server
+node bin/prepia.mjs serve
+
+# Submit a task
+curl -X POST http://localhost:3000/task \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is machine learning?", "mode": "shot"}'
+
+# Health check
+curl http://localhost:3000/status
+
+# Analytics
+curl http://localhost:3000/analytics
+```
+
+## API Reference
+
+### POST /task
+Submit a task for processing.
+
+**Body:**
+```json
+{
+  "query": "Your question or task",
+  "mode": "flash|shot|stream",
+  "options": {}
+}
+```
+
+**Response:**
+```json
+{
+  "answer": "The response text",
+  "mode": "shot",
+  "usedLLM": true,
+  "taskId": "task_123_abc",
+  "provider": "openai",
+  "tokens": { "prompt": 100, "completion": 50, "total": 150 },
+  "quality": { "overall": 0.85 },
+  "duration": 1234
+}
+```
+
+### GET /status
+Health check endpoint.
+
+### GET /analytics
+Usage statistics and cost savings.
+
+### POST /cache/clear
+Clear all caches.
+
+### GET /plugins
+List registered plugins.
+
+### POST /config
+Update engine configuration.
+
+## Processing Modes
+
+| Mode | Description | LLM Calls | Best For |
+|------|-------------|-----------|----------|
+| `flash` | Instant local answers | 0 | Math, greetings, time queries |
+| `shot` | One optimized LLM call | 1 | Most tasks (default) |
+| `stream` | Progressive updates | 1 | Long-running tasks |
+
+## Configuration
+
+```javascript
+const engine = new PrepiaEngine({
+  cache: {
+    memoryMaxSize: 1000,      // Max memory cache entries
+    memoryTTL: 300000,        // Memory TTL (5 min)
+    diskTTL: 3600000,         // Disk TTL (1 hour)
+    enableDisk: true,         // Enable disk persistence
+    cacheDir: '.prepia/cache' // Cache directory
+  },
+  config: {
+    maxContextTokens: 4000,   // Max context for LLM
+    defaultMode: 'shot',      // Default processing mode
+    enableLocalModel: true,   // Use local pattern matching
+    enableCache: true,        // Enable caching
+    enableQualityCheck: true  // Check output quality
+  },
+  rate: {
+    providers: {
+      openai: { requestsPerMinute: 60, tokensPerMinute: 100000 }
+    }
+  }
+});
+```
+
+## Plugin Development
+
+### Plugin Structure
+
+```
+my-plugin/
+├── manifest.json    # Plugin metadata
+└── index.mjs        # Plugin code
+```
+
+### manifest.json
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "My custom plugin",
+  "main": "index.mjs",
+  "dependencies": []
+}
+```
+
+### Plugin Interface
+
+```javascript
+// index.mjs
+export async function init(context) {
+  // Called when plugin is initialized
+}
+
+export async function execute(params) {
+  // Called when plugin is executed
+  return { result: 'done' };
+}
+
+export async function cleanup() {
+  // Called when plugin is cleaned up
+}
+```
+
+## PrepiScript
+
+Custom task definition language:
+
+```
+TASK "Research and Summarize"
+SEARCH "quantum computing breakthroughs 2024"
+EXTRACT key_findings
+FILTER relevance > 0.7
+FORMAT markdown
+DELIVER output
+```
+
+## Testing
+
+```bash
+# Run all tests
+node --test tests/**/*.test.mjs
+
+# Run unit tests only
+node --test tests/core/*.test.mjs tests/tools/*.test.mjs tests/cache/*.test.mjs
+
+# Run integration tests
+node --test tests/integration/*.test.mjs
+
+# Run API tests
+node --test tests/api/*.test.mjs
+```
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `core/engine` | Main orchestrator |
+| `core/task-decomposer` | Breaks tasks into sub-tasks |
+| `core/context-packager` | Compresses context for LLM |
+| `core/prepimshot` | One-shot prompt optimization |
+| `tools/orchestrator` | Tool routing and execution |
+| `tools/web-search` | Web search (DuckDuckGo, Wikipedia) |
+| `tools/web-scraper` | Content extraction |
+| `tools/calculator` | Safe math evaluation |
+| `cache/manager` | Cache orchestration |
+| `cache/memory-store` | LRU memory cache |
+| `cache/disk-store` | Persistent disk cache |
+| `models/router` | Multi-LLM routing |
+| `models/local-model` | Local pattern matching |
+| `models/provider` | LLM provider abstraction |
+| `rate/shield` | Rate limit protection |
+| `rate/limiter` | Token bucket / sliding window |
+| `chain/dag` | Task dependency graph |
+| `chain/scheduler` | Parallel task scheduler |
+| `chain/executor` | Task execution engine |
+| `vault/knowledge-base` | Persistent knowledge store |
+| `vault/pattern-learner` | Query pattern learning |
+| `plugins/loader` | Plugin discovery |
+| `plugins/registry` | Plugin lifecycle management |
+| `plugins/sandbox` | Plugin execution sandbox |
+| `guard/checker` | Output quality verification |
+| `guard/fact-checker` | Cross-reference verification |
+| `guard/hallucination` | Hallucination detection |
+| `persona/detector` | Context-aware persona selection |
+| `analytics/tracker` | Usage tracking |
+| `analytics/dashboard` | Cost/efficiency reporting |
+| `stream/handler` | Real-time progress updates |
+| `security/sanitizer` | Input/output sanitization |
+| `security/privacy` | PII detection and redaction |
+| `shadow/daemon` | Background task daemon |
+| `edge/lite` | Lightweight edge mode |
+| `morph/optimizer` | Workflow optimization |
+| `network/p2p` | Distributed task sharing |
+| `script/parser` | PrepiScript parser |
+| `script/executor` | PrepiScript executor |
+| `api/server` | HTTP API server |
+| `api/routes` | API route handlers |
+| `api/middleware` | Request/response middleware |
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Write tests for new functionality
+4. Ensure all tests pass: `node --test tests/**/*.test.mjs`
+5. Submit a pull request
+
+## License
+
+MIT

package/bin/prepia.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Prepia CLI - command-line interface.
+ * @module bin/prepia
+ */
+
+import { PrepiaEngine } from '../src/core/engine.mjs';
+import { generateReport, generateSummary } from '../src/analytics/dashboard.mjs';
+
+const HELP = `
+Prepia - AI Middleware CLI
+Usage: prepia [command] [options]
+
+Commands:
+  process <query>     Process a task through Prepia
+  status              Show engine status
+  analytics           Show usage analytics
+  cache clear         Clear all caches
+  serve               Start API server
+  help                Show this help
+
+Options:
+  --mode <flash|shot|stream>  Processing mode (default: shot)
+  --port <number>             API server port (default: 3000)
+  --json                      Output as JSON
+
+Examples:
+  prepia process "What is the capital of France?"
+  prepia process "Calculate 15% of 200" --mode flash
+  prepia serve --port 8080
+  prepia analytics --json
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === 'help' || command === '--help') {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  const engine = new PrepiaEngine({ cache: { enableDisk: false } });
+
+  switch (command) {
+    case 'process': {
+      const query = args.slice(1).find(a => !a.startsWith('--'));
+      if (!query) {
+        console.error('Error: Missing query. Usage: prepia process "<query>"');
+        process.exit(1);
+      }
+      const modeIdx = args.indexOf('--mode');
+      const mode = modeIdx >= 0 ? args[modeIdx + 1] : 'shot';
+      const json = args.includes('--json');
+
+      try {
+        const result = await engine.process(query, { mode });
+        if (json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log('\n' + result.answer);
+          console.log(`\n[${result.mode}] ${result.usedLLM ? 'LLM used' : 'Local'} | ${result.duration}ms`);
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'status': {
+      const metrics = engine.getAnalytics().metrics;
+      console.log(`Prepia v1.0.0`);
+      console.log(`Tasks processed: ${metrics.tasksProcessed}`);
+      console.log(`LLM efficiency: ${(metrics.efficiency * 100).toFixed(0)}%`);
+      break;
+    }
+
+    case 'analytics': {
+      const data = engine.getAnalytics();
+      if (args.includes('--json')) {
+        console.log(JSON.stringify(data, null, 2));
+      } else {
+        console.log(generateReport(data.metrics, data.savings));
+      }
+      break;
+    }
+
+    case 'cache': {
+      if (args[1] === 'clear') {
+        await engine.clearCache();
+        console.log('Cache cleared.');
+      } else {
+        console.log('Usage: prepia cache clear');
+      }
+      break;
+    }
+
+    case 'serve': {
+      const portIdx = args.indexOf('--port');
+      const port = portIdx >= 0 ? parseInt(args[portIdx + 1]) : 3000;
+      const { createServer } = await import('../src/api/server.mjs');
+      await createServer(engine, { port });
+      console.log(`Prepia API server running on http://localhost:${port}`);
+      break;
+    }
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(`Fatal: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "prepia",
+  "version": "1.0.0",
+  "description": "AI middleware that reduces LLM quota usage by 80-95% through smart caching, task decomposition, and context optimization",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "prepia": "bin/prepia.mjs"
+  },
+  "scripts": {
+    "start": "node src/api/server.mjs",
+    "test": "node --test tests/**/*.test.mjs",
+    "test:unit": "node --test tests/core/*.test.mjs tests/tools/*.test.mjs tests/cache/*.test.mjs tests/models/*.test.mjs tests/rate/*.test.mjs tests/chain/*.test.mjs tests/vault/*.test.mjs tests/plugins/*.test.mjs tests/guard/*.test.mjs tests/analytics/*.test.mjs tests/security/*.test.mjs tests/script/*.test.mjs",
+    "test:integration": "node --test tests/integration/*.test.mjs",
+    "test:api": "node --test tests/api/*.test.mjs",
+    "cli": "node bin/prepia.mjs"
+  },
+  "keywords": [
+    "ai",
+    "middleware",
+    "llm",
+    "cache",
+    "optimization",
+    "agent",
+    "openai",
+    "anthropic",
+    "token-saving",
+    "quota",
+    "ai-agent",
+    "prepia"
+  ],
+  "author": "Atum246",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atum246/prepia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Atum246/prepia/issues"
+  },
+  "homepage": "https://github.com/Atum246/prepia#readme",
+  "files": [
+    "src/",
+    "bin/",
+    "skill/",
+    "workflows/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skill/SKILL.md

@@ -0,0 +1,148 @@
+# Prepia - AI Middleware Skill
+
+## What is Prepia?
+
+Prepia is a smart middleware layer that sits between AI agents and LLMs. It reduces LLM quota usage by 80-95% by:
+
+- **Caching** results to avoid redundant LLM calls
+- **Decomposing** complex tasks into sub-tasks
+- **Handling locally** what doesn't need an LLM (calculations, searches, file ops)
+- **Optimizing context** to minimize token usage
+- **Quality checking** outputs for reliability
+
+## Installation
+
+```bash
+cd prepia && npm install  # No external deps - just for package.json scripts
+# Or use directly:
+node bin/prepia.mjs --help
+```
+
+## How to Submit Tasks
+
+### Via CLI
+```bash
+node bin/prepia.mjs process "What is the capital of France?"
+node bin/prepia.mjs process "Calculate 15% of 200" --mode flash
+```
+
+### Via API
+```bash
+curl -X POST http://localhost:3000/task \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is machine learning?", "mode": "shot"}'
+```
+
+### Via Code
+```javascript
+import { PrepiaEngine } from 'prepia';
+
+const engine = new PrepiaEngine();
+const result = await engine.process("Summarize quantum computing");
+console.log(result.answer);
+```
+
+## Processing Modes
+
+| Mode | Description | LLM Calls | Best For |
+|------|-------------|-----------|----------|
+| `flash` | Instant local answers | 0 | Simple questions, math, greetings |
+| `shot` | One optimized LLM call | 1 | Most tasks (default) |
+| `stream` | Progressive with updates | 1 | Long-running tasks |
+
+## How to Read Responses
+
+Response object structure:
+```javascript
+{
+  answer: "The answer text",      // Main response
+  mode: "shot",                   // Processing mode used
+  usedLLM: true,                  // Whether LLM was called
+  taskId: "task_123_abc",        // Unique task ID
+  provider: "openai",            // LLM provider used (if any)
+  tokens: { prompt: 100, completion: 50, total: 150 },
+  quality: { overall: 0.85, completeness: 0.9, coherence: 0.8 },
+  duration: 1234                 // Processing time in ms
+}
+```
+
+## Configuration
+
+### Engine Options
+```javascript
+const engine = new PrepiaEngine({
+  cache: { memoryMaxSize: 1000, enableDisk: true },
+  config: { maxContextTokens: 4000, enableLocalModel: true },
+  model: { providers: [{ name: 'openai', type: 'openai', apiKey: '...' }] }
+});
+```
+
+### Model Providers
+```javascript
+import { ModelRouter } from 'prepia';
+
+const router = new ModelRouter({
+  providers: [
+    { name: 'openai', type: 'openai', apiKey: '...', priority: 10 },
+    { name: 'anthropic', type: 'anthropic', apiKey: '...', priority: 5 },
+  ]
+});
+```
+
+## Workflow Examples
+
+### Web Research
+```javascript
+const result = await engine.process(
+  "Research the latest developments in quantum computing 2024",
+  { mode: 'shot' }
+);
+```
+
+### Data Analysis
+```javascript
+const result = await engine.process(
+  "Calculate the compound interest on $10000 at 5% for 10 years",
+  { mode: 'flash' }
+);
+```
+
+### Content Summarization
+```javascript
+const result = await engine.process(
+  "Summarize the key points from this article: [paste article text]",
+  { mode: 'shot' }
+);
+```
+
+## PrepiScript
+
+Custom task definition language:
+```
+TASK "Research and Summarize"
+SEARCH "quantum computing breakthroughs 2024"
+EXTRACT key_findings
+FORMAT markdown
+DELIVER output
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "No providers configured" | Set up a model router with API keys |
+| Cache not working | Check disk permissions for `.prepia/cache/` |
+| Slow responses | Use `flash` mode for simple queries |
+| Rate limited | Prepia auto-throttles; wait or add more providers |
+| Low quality output | Check quality score; may need better context |
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | /task | Submit a task |
+| GET | /status | Health check |
+| GET | /analytics | Usage stats |
+| POST | /cache/clear | Clear cache |
+| GET | /plugins | List plugins |
+| POST | /config | Update config |

package/skill/config.json

@@ -0,0 +1,29 @@
+{
+  "name": "prepia",
+  "version": "1.0.0",
+  "description": "AI middleware that reduces LLM quota usage by 80-95%",
+  "triggers": [
+    "research",
+    "search",
+    "find",
+    "look up",
+    "calculate",
+    "compute",
+    "summarize",
+    "analyze",
+    "automate",
+    "prepia"
+  ],
+  "defaultMode": "shot",
+  "enableCache": true,
+  "enableLocalModel": true,
+  "enableQualityCheck": true,
+  "maxContextTokens": 4000,
+  "supportedModes": ["flash", "shot", "stream"],
+  "workflows": {
+    "research": "workflows/research.json",
+    "summarize": "workflows/summarize.json",
+    "analyze": "workflows/analyze.json",
+    "automate": "workflows/automate.json"
+  }
+}