npm package: @ik-firewall/core
Description: The core IK Firewall engine for semantic-driven AI optimization.
Author: IK-Firewall Team
Latest version: 2.6.5

# @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