@ik-firewall/core 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+# @ik-firewall/core 🛡️🧠
+
+[![npm version](https://badge.fury.io/js/@ik-firewall%2Fcore.svg)](https://badge.fury.io/js/@ik-firewall%2Fcore)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+**IK Firewall** is an advanced, semantic-driven LLM Middleware and Prompt Optimizer. 
+It sits as a protective and optimizing layer between your application and Large Language Models (like OpenAI, Anthropic, DeepSeek, or local models). 
+
+> **⚠️ DISCLAIMER: LIVE TEST PHASE**
+> This package is currently in a live testing and benchmark phase. While it is fully functional, it is officially unannounced and documentation is subject to rapid changes. Use in production at your own discretion. 
+
+By analyzing the *Cognitive Depth*, *Metaphorical Scale*, and *Domain* of incoming user requests, the IK Firewall compresses inputs, applies rigorous semantic guardrails (Constitutional AI), and ensures that you get high-fidelity responses from cheaper models (like `gpt-4o-mini`) that rival the quality of expensive flagship models (like `gpt-4o`).
+
+## 🚀 Key Features
+
+*   **Semantic Prompt Compression (`crystallize`):** Removes structural noise and redundant phrasing without losing critical "Immutable Entities" (anchors). Drastically cuts down token usage.
+*   **Deep Cognitive Audit (`analyze`):** Classifies the specific required Intelligence Quotient (IQ Tier), Intent Mode (Engineering, Legal, Medical, Finance), and Abstract/Directness ratios of user input.
+*   **Provider-Agnostic Routing:** Supports OpenAI, Anthropic, DeepSeek, Google Gemini, and fully offline local models (`llama.cpp`).
+*   **Heuristic Gatekeeper:** Deflects simple inputs and flags unsafe or out-of-bounds requests before hitting expensive APIs, using an active `safeMode`.
+*   **Automated Usage Tracking:** Built-in calculation of token usage, latency, and estimated cost savings with pluggable telemetry hooks.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @ik-firewall/core
+# or
+yarn add @ik-firewall/core
+# or
+pnpm add @ik-firewall/core
+```
+
+---
+
+## 🛠️ Quick Start
+
+### 1. Initialization and Configuration
+
+Initialize the core instance anywhere in your Edge, Serverless, or Node.js environment.
+
+```typescript
+import { IKFirewallCore } from '@ik-firewall/core';
+
+// Create a globally accessible singleton instance
+const ik = IKFirewallCore.getInstance({
+  aggressiveness: 0.15,         // How hard to compress the prompt (0.0 to 1.0)
+  precisionBias: 3.5,           // Threshold to trigger higher IQ logic
+  balance: 0.5,                 // 0.0 (Speed/Efficiency) <--> 1.0 (Nuance/Depth)
+  safeMode: true,               // Enable strict boundary evaluations
+  allowedScopes: ['read_only'], // Requires safeMode: true
+  providerMode: 'openai'        // 'openai', 'anthropic', 'deepseek', 'gemini', 'local', 'hybrid'
+});
+
+// Optional: Pass telemetry hooks
+const ikWithHooks = IKFirewallCore.getInstance(config, {
+  onStatus: (msg) => console.log(`[IK_LOG]: ${msg}`),
+  onAuditComplete: (metrics) => console.log(`Audit metrics generated!`)
+});
+```
+
+### 2. The Core Pipeline (Audit -> Crystallize -> Execute)
+
+The standard flow for processing user input through the firewall before sending it to your target LLM:
+
+```typescript
+async function handleUserChat(userMessage: string) {
+  const ik = IKFirewallCore.getInstance();
+  
+  // 1. Analyze the input semantically
+  // This detects the domain, required depth, and creates a cognitive blueprint
+  const metrics = await ik.analyze(userMessage);
+
+  // 2. Compress the prompt using the metrics
+  // This removes noise while preserving domain-critical anchors
+  const optimizedPrompt = ik.crystallize(userMessage, metrics);
+
+  // 3. (Optional) Check Constitutional Guardrails
+  if (metrics.semanticInsights?.requiresHumanIntervention) {
+    throw new Error("IK_GATEKEEPER: Request exceeds permitted autonomy boundaries.");
+  }
+
+  // 4. Send the optimized prompt and the generated "Agent Directive" to your LLM
+  // You now pay for fewer tokens but inject deep semantic context!
+  const llmResponse = await myLlmProvider.chat({
+    systemContext: metrics.agentDirective, // Powerful instructions generated by the IK Analysis
+    message: optimizedPrompt               // The compressed user input
+  });
+
+  return llmResponse;
+}
+```
+
+---
+
+## 🧬 Understanding IKMetrics
+
+The `.analyze()` method is the heart of the engine. It returns an `IKMetrics` object that defines the genetic makeup of the request:
+
+```json
+{
+  "dm": 1.5,
+  "ei": 0.5,
+  "precisionBoost": true,
+  "agentDirective": "IK_ADAPTER_ACTIVE: TRUE... DOMAIN: ENGINEERING... Režim rada: ANALITIČKI...",
+  "semanticInsights": {
+    "detectedDomain": "ENGINEERING",
+    "intentMode": "ENGINEERING",
+    "cognitiveDepth": "L1-DIRECT",
+    "requiredIQTier": "TIER_1",
+    "immutableEntities": ["React", "Tailwind", "Zod", "sortiranje"],
+    "toneVector": { "abstraction": 0.1, "directness": 0.8, "density": 0.9 },
+    "boundaryScore": 0,
+    "requiresHumanIntervention": false
+  }
+}
+```
+
+### High-Stakes Domains Auto-Detection
+The firewall is extremely conservative by default (`GENERAL` domain) but aggressively switches logic if it detects:
+* `LEGAL`: Demands literal precision, protects arbitration/termination clauses.
+* `MEDICAL`: Protects symptoms and differential diagnoses.
+* `FINANCE`: Secures formulas and risk assessments.
+* `ENGINEERING`: Secures technology stacks and logical steps.
+
+---
+
+## 🛡️ Safe Mode & Autonomy Boundaries
+
+By enabling `safeMode` and providing `allowedScopes`, the firewall acts as a literal shield.
+
+```typescript
+ik.setConfig({
+  safeMode: true,
+  allowedScopes: ['Customer_Support_FAQ', 'Order_Tracking']
+});
+```
+If a user tries to prompt-inject the bot to drop database tables or write generic poetry, the Heuristic Gatekeeper will intercept it, setting `metrics.semanticInsights.requiresHumanIntervention = true` and logging an `authority_exceeded` event.
+
+---
+
+## 📈 Benchmarks
+
+In blind tests, comparing an unoptimized `gpt-4o` request against an IK-Optimized `gpt-4o-mini` request:
+- **Cost Savings:** Up to 65% reduction in token costs (due to `crystallize` compression and `mini` routing).
+- **Quality:** Evaluators ranked IK-Optimized responses functionally equivalent to or better than raw `gpt-4o` on strictly precise domains (Legal, Medical, Finance) because the `agentDirective` forces the smaller model to maintain high structural fidelity.
+
+---
+
+## 📝 License
+
+MIT © Stefan Vasic