@nxuss/lemma 0.3.2 → 0.4.0

package/README.md

@@ -1,522 +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.
+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**.
 
 ---
 
-## ⚡ 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
-```
-
-**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:
+## ⚡ Killer Features
 
-```bash
-npm install @nxuss/lemma
-```
-
-👉 **[Multi-Agent Guide](#quick-start)**
+### 🛡️ 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.
 
----
+### 🚦 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.
 
-## The problem with AI development costs
+### 🧠 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.
 
-When you use AI assistants for development, you pay for every prompt — even when asking similar questions:
-
-```
-"How to implement JWT in Express?"
-"Explain JWT authentication in Node.js"  ← Same answer, paid twice
-"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.
+### ⚡ 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.
 
 ---
 
-## 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.
+## 🚀 Quick Start
 
-At scale this compounds fast:
+Launch the Lemma ecosystem in seconds:
 
-```
-10 agents × 500 tasks/day × 70% overlap = 3,500 redundant LLM calls/day
+```bash
+npm install -g @nxuss/lemma
+lemma start --stack
 ```
 
-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.
+**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`
 
 ---
 
-## 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
+## 💎 Tier Comparison
 
-The cache is semantic, not exact. "fibonacci up to n=10" and "compute fibonacci(10)" resolve to the same cached answer.
+| 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** |
 
 ---
 
-## Quick start
+## 🛠️ Developer Integration
 
-### 1. Install and setup dependencies
+### 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.
 
 ```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
-});
+# Point your configuration to:
+http://localhost:8085/v1
 ```
 
-#### Option C: Server Mode (Multi-Agent)
-
-#### 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' }
-    }
-  }));
-});
-
-ws.on('message', (data) => {
-  const msg = JSON.parse(data.toString());
-
-  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 }
-    }));
-  }
-});
-```
-
-### 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.
-
----
-
-## What's inside
-
-### Embedded Mode — Zero-config semantic cache
-
-The simplest way to add semantic caching to any project:
-
-```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
-});
-
-// Wrap any async function
-const cached = lemma.wrap(yourExpensiveFunction);
-
-// Use it
-const result = await cached('your input');
-console.log(result.fromCache); // true on cache hit
-```
-
-**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
-});
-
-// Expired entries are automatically removed
-// No manual cleanup needed!
-```
-
-### 3. Circuit Breaker & Fallbacks
-
-Automatic resilience when backends fail:
-
-```typescript
-const lemma = await Lemma.create({
-  storage: 'cloud',
-  enableFallback: true,  // Auto-fallback on failure
-  maxRetries: 3,
-  retryDelay: 1000,
-});
-
-// If cloud fails → falls back to chroma
-// If chroma fails → falls back to memory
-// Automatic recovery when backend comes back
-
-lemma.on('backend-degraded', ({ from, to }) => {
-  console.log(`Degraded: ${from} → ${to}`);
-});
-
-lemma.on('backend-recovered', ({ backend }) => {
-  console.log(`Recovered: ${backend}`);
-});
-```
-
-### 4. Enhanced Metrics & Health Monitoring
-
-```typescript
-const metrics = lemma.getMetrics();
-console.log(metrics);
-// {
-//   hits: 150,
-//   misses: 50,
-//   hitRate: 0.75,
-//   backendHealth: 'healthy',
-//   failureCount: 0,
-//   evictedCount: 23,
-//   lastCleanupAt: 1234567890
-// }
-
-const health = lemma.getBackendHealth();
-console.log(health);
-// {
-//   state: 'CLOSED',
-//   currentBackend: 'semantic',
-//   failureCount: 0,
-//   totalFailures: 0
-// }
-```
-
-### 5. Dual Module Support (ESM + CJS)
-
-```typescript
-// ESM
-import { Lemma } from '@nxuss/lemma/embed';
-import { ConsensusEngine } from '@nxuss/lemma/consensus';
-import { SpeculativeEngine } from '@nxuss/lemma/speculative';
-
-// CJS
-const { Lemma } = require('@nxuss/lemma/embed');
-const { ConsensusEngine } = require('@nxuss/lemma/consensus');
-```
-
-**New exports:**
-- `@nxuss/lemma/consensus` - Multi-model consensus
-- `@nxuss/lemma/speculative` - Speculative execution
-- `@nxuss/lemma/security` - Security utilities
-- `@nxuss/lemma/protocol` - IAP protocol
-- `@nxuss/lemma/langchain` - LangChain SDK
-- `@nxuss/lemma/crewai` - CrewAI SDK
-
-See [MIGRATION_GUIDE.md](docs/MIGRATION_GUIDE.md) for upgrade instructions.
-
----
-
-## Install
-
-```bash
-npm install @nxuss/lemma
-```
-
-**Optional dependencies (install as needed):**
-
-```bash
-# For semantic mode (lightweight embeddings)
-npm install @xenova/transformers
-
-# For persistent storage with ChromaDB
-pip install chromadb
-chroma run --path ./chroma_data --port 8000
-
-# For ChromaDB embeddings
-ollama pull nomic-embed-text
-```
-
-**Zero dependencies required** for basic memory mode!
-
----
-
-## 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   # similarity cutoff (0–1)
-ENABLE_CACHING=true
-AUTH_ENABLED=false        # set true in production
-```
-
----
-
-## Examples & Documentation
-
-For complete examples including:
-- Single agent setup
-- Multi-agent swarms
-- Consensus voting
-- Security & authentication
-- LangChain/CrewAI integration
-
-Visit [lemma.nxus.studio/docs](https://lemma.nxus.studio/docs)
-
----
-
-## Who this is for
-
-- Teams running **LangChain, CrewAI, or custom agent frameworks** who need shared memory across agents
-- Systems where **multiple agents handle overlapping queries** — support bots, research pipelines, code assistants
-- Anyone whose **LLM bill scales with agent count** rather than unique queries
-
-Lemma is designed for multi-agent systems where coordination and shared memory provide immediate value.
-
 ---
 
-## Production deployment
-
-Lemma can be deployed to any Node.js hosting environment. For production setup guides including:
-- Docker deployment
-- API key management
-- Security configuration
-- Monitoring & observability
-
-Visit [lemma.nxus.studio/docs/deployment](https://lemma.nxus.studio/docs/deployment)
-
----
-
-## Cloud hosting (coming soon)
-
-Managed Lemma instances with zero infrastructure setup. Check pricing and availability at [lemma.nxus.studio](https://lemma.nxus.studio)
+## 📊 Dashboard
+Monitor your savings, visualize agent connections, and inspect your semantic memory through the integrated real-time dashboard.
 
 ---
 
-## Contributing
-
-Contributions are welcome! For development setup and guidelines, visit [lemma.nxus.studio](https://lemma.nxus.studio)
-
----
-
-## License
-
-MIT © [Nxus Studio](https://nxus.studio)
+MIT © Nxus Studio | [Get Lemma Pro](https://lemma.nxus.studio/upgrade)