@nxuss/lemma 0.3.3 → 0.4.0

package/README.md

@@ -1,366 +1,78 @@
-# Lemma v0.3.2
-> **The Universal AI Cache Proxy + Agent Orchestration Layer.**
+# Lemma v0.4.0
+> **The Intelligent AI Gateway — Privacy, Performance, and Precision for the Agentic Era.**
 
-Lemma is the open-core gateway for AI development. It sits between your tools (Cursor, VS Code, CLI Agents) and your models (OpenAI, Claude, Gemini, Ollama), providing a **shared semantic memory** that saves you 40-70% in API costs and makes your AI tools instant.
-
-⚡ **Why Lemma?**
-- 💰 **Stop paying twice**: Lemma caches redundant queries semantically. "Fix this bug" and "Solve this error" return the same cached answer.
-- ⚡ **Instant responses**: 3ms cache hits vs 2000ms LLM calls.
-- 🤖 **Universal Gateway**: One endpoint for OpenAI, Anthropic, and Gemini.
-- 🐝 **Agent Swarms**: Orchestrate multiple agents with shared memory.
-
-⚡ **Quick Start (IDE Proxy)**
-
-Install and launch the proxy to start saving on your API bills immediately.
-
-```bash
-npm install -g @nxuss/lemma
-lemma start
-
-# Or to launch the full development stack (Proxy + Dashboard + Hub + Chroma):
-lemma start --stack
-```
-
-**Configure your IDE:**
-
-- **Base URL:** `http://localhost:8080/v1`
-- **Gemini Base:** `http://localhost:8080/v1beta`
-
-🆓 **Free Tier:** 300 queries/month + Exact Matching.
-💎 **Pro:** Unlimited queries + Semantic Caching ($12/mo or $120/yr).
-☁️ **Cloud:** Managed infrastructure (Coming Soon).
-
-👉 [Get Lemma Pro](https://lemma.nxus.studio/upgrade)
-
-### Option 2: Multi-Agent System
-For building coordinated AI agent systems:
-
-```bash
-npm install @nxuss/lemma
-```
-👉 [Multi-Agent Guide](https://lemma.nxus.studio/docs/multi-agent)
+Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, and **Runtime Context Synchronization**.
 
 ---
 
-## The problem with AI development costs
-When you use AI assistants for development, you pay for every prompt — even when asking similar questions:
-
-1. *"How to implement JWT in Express?"*
-2. *"Explain JWT authentication in Node.js"*  ← **Same answer, paid twice**
-3. *"Show me JWT example for Express"*       ← **Same answer, paid three times**
-
-Lemma Proxy intercepts these calls and returns cached responses for similar prompts in **3ms instead of 600ms**, saving you money and time.
+## ⚡ Killer Features
 
-## The problem with multi-agent systems
-When you run multiple AI agents in parallel, they don't share context. Agent A solves a problem. Agent B gets the same problem 10 minutes later and solves it again. You pay twice, wait twice, and get the same answer.
+### 🛡️ Privacy Firewall (Semantic Scrubber)
+**Zero-Trust Prompts.** Stop leaking sensitive data. Lemma automatically detects API keys, PII, and credentials in your prompts, masking them with secure tokens before they reach the cloud. Responses are seamlessly reconstructed locally, ensuring your secrets never leave your machine.
 
-At scale this compounds fast:
-**10 agents × 500 tasks/day × 70% overlap = 3,500 redundant LLM calls/day**
+### 🚦 Complexity Router (Cost-Optimizer)
+**Intelligence Where it Matters.** Lemma analyzes the semantic complexity of every request. It autonomously routes lightweight tasks (like JSON formatting or translations) to hyper-efficient models like `gpt-4o-mini`, reserving premium models for high-reasoning challenges. Save up to 90% on simple tasks without losing quality.
 
-Lemma puts a shared semantic brain between your agents. When any agent solves something, every other agent gets that answer for free — even if they phrase the question differently.
+### 🧠 Telepathic Context Injector (Runtime Sync)
+**Bridge the Gap Between Code and Execution.** Lemma synchronizes your application's live runtime state, exceptions, and memory mutations directly with your IDE’s consciousness. Your AI assistant gains immediate "situational awareness" of crashes and state changes, allowing for instant, context-aware debugging without manual intervention.
 
-## How it works
-
-```
-Agent A ──┐
-Agent B ──┤──► SubconsciousHub ──► Semantic Cache (ChromaDB + embeddings)
-Agent C ──┘         │
-                     └──► Agent Registry + Capability Routing
-```
-
-1. Agents connect via WebSocket and register their capabilities
-2. Every task request hits the semantic cache first
-3. On a miss, the hub routes to a capable agent and stores the result
-4. On a hit, the response returns in **~20ms** — no agent invoked, no LLM called
-
-The cache is **semantic**, not exact. *"fibonacci up to n=10"* and *"compute fibonacci(10)"* resolve to the same cached answer.
+### ⚡ Shared Semantic Cache
+**Stop Paying for the Same Thought Twice.** Unlike traditional caches, Lemma understands meaning. It recognizes that *"Fix this CSS bug"* and *"Solve the styling error"* are functionally identical, returning instant (3ms) responses and saving 40-70% on total API expenditure.
 
 ---
 
-## Quick start
-
-### 1. Install and setup dependencies
-```bash
-npm install @nxuss/lemma
-
-# For semantic mode (optional, lightweight embeddings):
-npm install @xenova/transformers
-
-# For persistent storage with ChromaDB (optional):
-pip install chromadb
-chroma run --path ./chroma_data --port 8000
-
-# For ChromaDB embeddings (optional):
-ollama pull nomic-embed-text
-```
-
-### 2. Choose your mode
-
-#### Option A: Semantic Mode (Recommended) ⚡
-Zero external dependencies, true semantic matching:
-
-```typescript
-import { Lemma } from '@nxuss/lemma/embed';
-
-const lemma = await Lemma.create({
-  storage: 'semantic',  // Uses transformers.js
-  threshold: 0.85,      // Similarity threshold
-});
-
-const cachedLLM = lemma.wrap(async (query: string) => {
-  return await yourLLMCall(query);
-});
-
-await cachedLLM('weather in San Francisco');  // Calls LLM
-await cachedLLM('SF weather forecast');        // Cache HIT! ⚡
-await cachedLLM('San Francisco temperature');  // Cache HIT! ⚡
-```
-
-#### Option B: Memory Mode (Fastest)
-Exact matching, zero dependencies:
-
-```typescript
-const lemma = await Lemma.create({
-  storage: 'memory',  // Default, exact match only
-});
-```
-
-#### Option C: Server Mode (Multi-Agent)
-For multi-agent orchestration:
-
-```typescript
-import { SubconsciousHub } from '@nxuss/lemma';
-
-const hub = new SubconsciousHub({ 
-  server: { port: 8080 } 
-});
-
-await hub.start();
-console.log('WebSocket hub listening on ws://localhost:8080');
-```
-
-### 3. Connect agents (Server Mode)
-```typescript
-import WebSocket from 'ws';
-
-const ws = new WebSocket('ws://localhost:8080');
-
-ws.on('open', () => {
-  // Register with the hub
-  ws.send(JSON.stringify({
-    type: 'handshake',
-    messageId: `msg-${Date.now()}`,
-    timestamp: Date.now(),
-    payload: {
-      agentId: 'my-agent-001',
-      capabilities: [{ name: 'code-generation', description: 'Writes code', version: '1.0.0' }],
-      metadata: { version: '1.0.0' }
-    }
-  }));
-});
+## 🚀 Quick Start
 
-ws.on('message', (data) => {
-  const msg = JSON.parse(data.toString());
+Launch the Lemma ecosystem in seconds:
 
-  if (msg.type === 'handshake_ack') {
-    // Connected — send a task
-    ws.send(JSON.stringify({
-      type: 'task_request',
-      messageId: `msg-${Date.now()}`,
-      timestamp: Date.now(),
-      payload: {
-        taskId: `task-${Date.now()}`,
-        taskType: 'general',
-        description: 'Implement binary search in Python',
-        requiredCapabilities: ['code-generation'],
-        parameters: {}
-      }
-    }));
-  }
-
-  if (msg.type === 'task_response' || msg.type === 'TASK_RESPONSE') {
-    const { cached, executionTime, result } = msg.payload;
-    console.log(cached ? `⚡ Cache hit (${executionTime}ms)` : `🔄 Computed (${executionTime}ms)`);
-    console.log(result);
-  }
-
-  if (msg.type === 'task_assign') {
-    // Hub routed a task to us — process and respond
-    const { taskId, description } = msg.payload;
-    const result = yourLLM(description); // your actual LLM call
-    ws.send(JSON.stringify({
-      type: 'task_response',
-      messageId: `msg-${Date.now()}`,
-      timestamp: Date.now(),
-      payload: { taskId, success: true, result, executionTime: 1200, tokensUsed: 800 }
-    }));
-  }
-});
+```bash
+npm install -g @nxuss/lemma
+lemma start --stack
 ```
 
-### 4. See it in action
-When multiple agents request similar tasks, you'll see the cache working:
-
-```
-[agent-001] 🔄 COMPUTED  - Calculate fibonacci(10)... (1000ms)
-[agent-002] ⚡ CACHE HIT - compute the 10th fibonacci... (20ms)
-[agent-003] ⚡ CACHE HIT - fibonacci sequence up to n=10... (22ms)
-```
-**Result: 100% cache hit rate after first computation. ~20ms responses. Zero duplicate LLM calls.**
+**Point your IDE or SDK to Lemma:**
+*   **Base URL:** `http://localhost:8085/v1` (OpenAI / Anthropic Compatible)
+*   **Gemini Base:** `http://localhost:8085/v1beta`
+*   **Dashboard:** `http://localhost:3000`
 
 ---
 
-## What's inside
+## 💎 Tier Comparison
 
-### Embedded Mode — Zero-config semantic cache
-The simplest way to add semantic caching to any project:
+| Feature | 🆓 Free (Open-Core) | 💎 Pro ($12/mo) |
+| :--- | :--- | :--- |
+| **Caching** | Exact Match | **Semantic Memory (ChromaDB)** |
+| **Security** | Basic Logging | **Privacy Firewall (Auto-Masking)** |
+| **Optimization** | Manual Routing | **Autonomous Complexity Router** |
+| **IDE Sync** | Raw Log Stream | **Telepathic Context Injector** |
+| **Continuity** | Local Only | **Cloud Sync (Team Memory)** |
+| **Limits** | 300 requests/mo | **Unlimited Agentic Power** |
 
-```typescript
-import { Lemma } from '@nxuss/lemma/embed';
+---
 
-const lemma = await Lemma.create({
-  storage: 'semantic',  // or 'memory', 'chroma', 'cloud'
-  threshold: 0.85,
-  ttl: 3600000,         // 1 hour
-  cleanupInterval: 60000, // Auto-cleanup every minute
-  enableFallback: true,  // Auto-fallback on failures
-});
+## 🛠️ Developer Integration
 
-// Wrap any async function
-const cached = lemma.wrap(yourExpensiveFunction);
+### Use as an Intelligent Proxy
+Simply swap your OpenAI/Anthropic base URL in your favorite tools (Cursor, Copilot, AutoGPT). Lemma handles the caching, scrubbing, and routing transparently.
 
-// Use it
-const result = await cached('your input');
-console.log(result.fromCache); // true on cache hit
+```bash
+# Point your configuration to:
+http://localhost:8085/v1
 ```
 
-**Features:**
-- Semantic matching with lightweight embeddings (transformers.js)
-- Automatic TTL cleanup prevents memory leaks
-- Circuit breaker with automatic fallbacks (Cloud → Chroma → Memory)
-- Health monitoring with detailed metrics
-- Graceful shutdown with `lemma.stop()`
-
-**Storage options:**
-- `memory`: Exact match, zero dependencies, fastest
-- `semantic`: True semantic matching, lightweight (50MB)
-- `chroma`: Persistent semantic cache (requires ChromaDB)
-- `cloud`: Managed cache (requires API key)
-
-### SubconsciousHub — the orchestration layer
-The core of Lemma. A WebSocket server that manages agent connections, routes tasks by capability, and maintains the shared semantic cache.
-
+### Use as a Multi-Agent Hub
+For complex agent swarms that need a "Hive Mind":
 ```typescript
 import { SubconsciousHub } from '@nxuss/lemma';
-
 const hub = new SubconsciousHub({ server: { port: 8080 } });
 await hub.start();
 ```
 
-**What it handles:**
-- Agent registration and capability discovery
-- Semantic cache lookup before every task (ChromaDB + nomic-embed-text embeddings)
-- Task routing to capable agents on cache miss
-- Response storage for future cache hits
-- WebSocket heartbeat and connection lifecycle
-- Rate limiting and message sanitization
-
-### Semantic cache — the shared memory
-Built on ChromaDB with Ollama embeddings. Catches paraphrases, not just exact matches.
-
-- *"fibonacci up to n=10"*          ──► **cache hit** (similarity: 0.97)
-- *"compute the 10th fibonacci"*    ──► **cache hit** (similarity: 0.91)
-- *"fib sequence, first 10 terms"*  ──► **cache hit** (similarity: 0.88)
-
-Threshold is configurable (`SEMANTIC_THRESHOLD=0.85` by default).
-
-### Consensus engine — multi-model voting
-For high-stakes decisions, route a query through multiple models and only return when they agree.
-
-```typescript
-import { ConsensusEngine } from '@nxuss/lemma';
-
-const consensus = new ConsensusEngine({
-  minModels: 3,
-  minAgreement: 0.90,
-  maxRounds: 3,
-});
-
-const result = await consensus.requestConsensus({
-  query: 'Is this SQL query safe to run in production?',
-  models: ['llama3', 'gpt-4', 'claude-3'],
-});
-// Returns only when 3 models agree ≥90%
-```
-Supports Ollama (local), OpenAI, Anthropic, and Google models simultaneously.
-
 ---
 
-## New in v0.2.0 🎉
-
-### 1. Semantic Memory Backend
-True semantic caching without external dependencies:
-```typescript
-const lemma = await Lemma.create({
-  storage: 'semantic',
-  embeddingModel: 'Xenova/all-MiniLM-L6-v2', // Lightweight!
-});
-
-// These all match semantically:
-await lemma.run('weather in SF', fetchWeather);
-await lemma.run('San Francisco weather', fetchWeather); // HIT!
-await lemma.run('SF temperature forecast', fetchWeather); // HIT!
-```
-
-### 2. Automatic TTL Cleanup
-No more memory leaks from expired entries:
-```typescript
-const lemma = await Lemma.create({
-  ttl: 3600000,          // 1 hour expiry
-  cleanupInterval: 60000, // Check every minute
-});
-```
-
-### 3. Circuit Breaker & Fallbacks
-Automatic resilience when backends fail:
-```typescript
-const lemma = await Lemma.create({
-  storage: 'cloud',
-  enableFallback: true,
-  maxRetries: 3,
-  retryDelay: 1000,
-});
-```
-
-### 4. Enhanced Metrics & Health Monitoring
-```typescript
-const metrics = lemma.getMetrics();
-// { hits: 150, misses: 50, hitRate: 0.75, ... }
-```
-
-### 5. Dual Module Support (ESM + CJS)
-Full support for both modern and legacy Node.js projects.
+## 📊 Dashboard
+Monitor your savings, visualize agent connections, and inspect your semantic memory through the integrated real-time dashboard.
 
 ---
 
-## Install
-```bash
-npm install @nxuss/lemma
-```
-
-## Configuration
-```bash
-# .env
-WS_PORT=8080
-CHROMA_HOST=http://localhost
-CHROMA_PORT=8000
-OLLAMA_HOST=http://localhost:11434
-OLLAMA_MODEL=nomic-embed-text
-SEMANTIC_THRESHOLD=0.85
-```
-
-## Contributing
-Contributions are welcome! Visit [lemma.nxus.studio](https://lemma.nxus.studio)
-
-## License
-MIT © Nxus Studio
+MIT © Nxus Studio | [Get Lemma Pro](https://lemma.nxus.studio/upgrade)