@ik-firewall/core 🛡️🧠

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

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.

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:

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:

{
  "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.

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