@ik-firewall/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,683 @@
+type ModelRole = 'high_performance' | 'cost_optimized' | 'audit_layer';
+type ProviderMode = 'openai' | 'anthropic' | 'deepseek' | 'gemini' | 'local' | 'hybrid';
+type RuntimeStrategy = 'internal' | 'sidecar' | 'wasm';
+type ContextMode = 'FIRST_MESSAGE' | 'EVERY_MESSAGE' | 'SYSTEM_ONLY';
+type PromptLength = 'SHORT' | 'MEDIUM' | 'LONG';
+type PromptType = 'TECHNICAL_ANALYSIS' | 'REASONING' | 'EXPLANATION' | 'SUMMARIZATION' | 'CODING' | 'DEBUGGING' | 'DECISION_MAKING' | 'CREATIVITY' | 'PHILOSOPHY' | 'ADVERSARIAL' | 'FUZZY_PROBLEM' | 'LEARNING_ADVICE' | 'POETRY' | 'STORY' | 'ANALYTICAL_PHILOSOPHY' | 'DEV_PROBLEM' | 'CRITICAL_THINKING' | 'HYBRID_DOMAIN' | 'INSTRUCTION_FOLLOWING' | 'REAL_WORLD_BUSINESS';
+interface TestPrompt {
+    id: string;
+    type: PromptType;
+    length?: PromptLength;
+    title: string;
+    content: string;
+}
+interface IKConfig {
+    aggressiveness: number;
+    forcedEfficiency?: boolean;
+    precisionBias: number;
+    balance: number;
+    gatekeeperEnabled: boolean;
+    locale?: string;
+    providerMode: ProviderMode;
+    runtimeStrategy: RuntimeStrategy;
+    localAuditEndpoint?: string;
+    centralReportEndpoint?: string;
+    fallbackToCloudAudit?: boolean;
+    modelConfig?: {
+        modelType: '1b' | '0.5b' | 'custom';
+        modelPath?: string;
+    };
+    cqThresholds?: {
+        low: number;
+        high: number;
+    };
+    safeMode?: boolean;
+    allowedScopes?: string[];
+    customBoundaryKeywords?: string[];
+    plugins?: {
+        id: string;
+        enabled: boolean;
+        config?: any;
+    }[];
+    customContext?: string;
+    contextMode?: ContextMode;
+    instanceConfigs?: Record<string, Partial<IKConfig>>;
+    isEnabled?: boolean;
+}
+interface IKPluginInfo {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    enabled: boolean;
+    type: 'methodology' | 'safety' | 'utility';
+}
+interface IKMetrics {
+    dm: number;
+    ei: number;
+    inputLength: number;
+    precisionBoost: boolean;
+    kft: number;
+    opt: number;
+    agentDirective?: string;
+    handoff_logic?: {
+        model: string;
+        reason: string;
+        mustEscalate: boolean;
+    };
+    approach?: {
+        category: string;
+        subtype: string;
+    };
+    semanticInsights?: {
+        metaphoricalScale: number;
+        conceptualUnits: number;
+        conceptualUnitsCount: number;
+        redundancyRatio: number;
+        conceptualBlueprint: string;
+        noiseClusters?: string[];
+        toneVector?: {
+            abstraction: number;
+            directness: number;
+            density: number;
+        };
+        immutableEntities?: string[];
+        intentMode?: 'ENGINEERING' | 'CONCEPTUAL' | 'SPECIALIZED';
+        cognitiveDepth?: 'L1-DIRECT' | 'L2-ANALYTICAL' | 'L3-CONCEPTUAL' | 'HYBRID-MULTI-LAYER';
+        activeLayers?: ('L1' | 'L2' | 'L3')[];
+        precisionRequired?: boolean;
+        semanticProof?: number;
+        cognitiveKinetic?: number;
+        engine_tuning_recommendation?: string;
+        detectedDomain?: string;
+        illocutionaryPoint?: 'ASSERTIVE' | 'DIRECTIVE' | 'COMMISSIVE' | 'EXPRESSIVE' | 'DECLARATIVE';
+        rhetoricalRatio?: {
+            ethos: number;
+            pathos: number;
+            logos: number;
+        };
+        expectancyViolation?: {
+            detected: boolean;
+            reason: string;
+            shiftSeverity: number;
+        };
+        approach?: {
+            category: string;
+            subtype: string;
+        };
+        gatekeeperFlag?: string;
+        kognitiveTrace: string[];
+        kft?: number;
+        opt?: number;
+        usageMetadata?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        };
+        rawAuditResponse?: string;
+        finalCrystallizedPrompt?: string;
+        requiredIQTier?: 'TIER_1' | 'TIER_2' | 'TIER_3';
+        routingReason?: string;
+        routingPath?: string;
+        cqScore?: number;
+        archetype?: 'CRYSTAL' | 'FLUID' | 'NEURAL' | 'DYNAMIC';
+        ambiguityTolerance?: number;
+        logicalFocus?: string;
+        detectedLanguage?: string;
+        boundaryScore?: number;
+        requiresHumanIntervention?: boolean;
+    };
+}
+interface AIResponse {
+    content: string;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+type AIProvider = (prompt: string, role: ModelRole) => Promise<AIResponse>;
+interface UsageData {
+    instanceId: string;
+    model_used: string;
+    routingPath: string;
+    input_tokens: number;
+    output_tokens: number;
+    optimized_tokens?: number;
+    tokens_saved: number;
+    cost_saved: number;
+    timestamp: string;
+    is_local: boolean;
+    cq_score: number;
+    clientOrigin?: string;
+    trace?: any;
+}
+interface IKHooks {
+    onDNAChange?: (dna: number) => void;
+    onAuditComplete?: (metrics: IKMetrics) => void;
+    onStatus?: (message: string) => void;
+    onUsageReported?: (usage: UsageData) => void;
+    onAuthorityExceeded?: (metrics: IKMetrics, prompt: string) => void | Promise<void>;
+}
+
+declare abstract class BaseProvider {
+    /**
+     * Primary method to send a prompt to the AI model.
+     * @param prompt The constructed prompt to send.
+     * @param role The role of the model (audit_layer, cost_optimized, etc.)
+     */
+    abstract call(prompt: string, role: ModelRole): Promise<AIResponse>;
+    /**
+     * Optional method to check if the provider is healthy.
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+/**
+ * OpenAIProvider wraps a functional AIProvider into the BaseProvider class.
+ * This ensures backward compatibility while allowing for the new abstraction layer.
+ */
+declare class OpenAIProvider extends BaseProvider {
+    private functionalProvider;
+    constructor(provider: AIProvider);
+    call(prompt: string, role: ModelRole): Promise<AIResponse>;
+}
+
+declare class LocalProvider extends BaseProvider {
+    private endpoint;
+    constructor(endpoint?: string);
+    call(prompt: string, role: ModelRole): Promise<AIResponse>;
+    healthCheck(): Promise<boolean>;
+}
+
+/**
+ * AnthropicProvider wraps a functional AIProvider into the BaseProvider class.
+ * This ensures the core logic can seamlessly route to Anthropic models (Claude)
+ * using the same unified abstraction layer.
+ */
+declare class AnthropicProvider extends BaseProvider {
+    private functionalProvider;
+    constructor(provider: AIProvider);
+    call(prompt: string, role: ModelRole): Promise<AIResponse>;
+}
+
+/**
+ * DeepSeekProvider wraps a functional AIProvider into the BaseProvider class.
+ * This ensures the core logic can seamlessly route to DeepSeek models
+ * using the same unified abstraction layer.
+ */
+declare class DeepSeekProvider extends BaseProvider {
+    private functionalProvider;
+    constructor(provider: AIProvider);
+    call(prompt: string, role: ModelRole): Promise<AIResponse>;
+}
+
+/**
+ * GeminiProvider wraps a functional AIProvider into the BaseProvider class.
+ * This ensures the core logic can seamlessly route to Google Gemini models
+ * using the same unified abstraction layer.
+ */
+declare class GeminiProvider extends BaseProvider {
+    private functionalProvider;
+    constructor(provider: AIProvider);
+    call(prompt: string, role: ModelRole): Promise<AIResponse>;
+}
+
+/**
+ * IK FIREWALL: THE CORE ALGORITHM (STANDALONE VERSION)
+ * Version: 2.1.0 (Modular & Provider-Agnostic)
+ */
+declare class IKFirewallCore {
+    private static instance;
+    static readonly CONSTANTS: {
+        DNA: {
+            MIN: number;
+            MAX: number;
+            HARDENING_SYSTEM: number;
+            HARDENING_MODERATE: number;
+            HARDENING_DOMAIN: number;
+            SOFTENING_STEP: number;
+            STRICT_THRESHOLD: number;
+            FLUID_THRESHOLD: number;
+            RANK_MIN: number;
+            RANK_MAX: number;
+        };
+        PRECISION: {
+            BIAS_DEFAULT: number;
+            METAPHOR_THRESHOLD: number;
+            REDUNDANCY_BOOST_LIMIT: number;
+            BALANCE_BOOST_THRESHOLD: number;
+            BOOST_EI_THRESHOLD: number;
+        };
+        HEURISTICS: {
+            UNIK_LENGTH_DIVISOR: number;
+            COMPLEXITY_SKIP_THRESHOLD: number;
+            INPUT_SUBSTRING_LIMIT: number;
+        };
+        AI: {
+            TEMPERATURE: number;
+            DM_LENGTH_DIVISOR: number;
+            CRYSTALLIZATION_LENGTH_RATIO: number;
+            CRYSTALLIZATION_SP_THRESHOLD: number;
+            BLUEPRINT_DENSITY_WARNING: number;
+            THRESHOLD_MIN: number;
+            THRESHOLD_MAX: number;
+            DM_THRESHOLD_DIVISOR: number;
+            AGGRESSIVENESS_WEIGHT: number;
+        };
+        TONE: {
+            CONVERSATIONAL_DIRECTNESS: number;
+            SLANG_DIRECTNESS: number;
+            ABSTRACTION_THRESHOLD: number;
+            DIRECTNESS_THRESHOLD: number;
+            STABLE_VAL: number;
+            KFT_DEFAULT: number;
+            OPT_DEFAULT: number;
+        };
+        AESTHETICS: {
+            CRYSTAL_THRESHOLD: number;
+            BRIDGE_THRESHOLD: number;
+            FLUID_THRESHOLD: number;
+        };
+    };
+    private gatekeeper;
+    private configManager;
+    private sessionDNA;
+    hooks?: IKHooks;
+    private cloudProvider?;
+    private localProvider;
+    private orchestrator;
+    private usageTracker;
+    constructor(config?: Partial<IKConfig>, hooks?: IKHooks, cloudProvider?: AIProvider | BaseProvider);
+    static getInstance(config?: Partial<IKConfig>, hooks?: IKHooks): IKFirewallCore;
+    setConfig(newConfig: Partial<IKConfig>): void;
+    getConfig(): IKConfig;
+    getPlugins(): IKPluginInfo[];
+    getSessionDNA(): number;
+    getInstanceConfigs(): Record<string, Partial<IKConfig>>;
+    setInstanceConfig(instanceId: string, config: Partial<IKConfig>): void;
+    /**
+     * Discovers available providers by checking environment variables and local health.
+     */
+    getAvailableProviders(): Promise<{
+        [provider: string]: {
+            available: boolean;
+            reason?: string;
+        };
+    }>;
+    /**
+     * Returns the model name based on its role and current configuration.
+     */
+    getModel(role: ModelRole): string;
+    /**
+     * Returns aggregated cognitive analytics (Stub for Phase 7).
+     */
+    getAnalytics(): {
+        totalSavings: number;
+        tokensSaved: number;
+        roi: number;
+        sessionCount: number;
+    };
+    setSessionDNA(dna: number): void;
+    logConsumption(params: {
+        instanceId: string;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        optimizedTokens?: number;
+        cqScore: number;
+        routingPath: string;
+        clientOrigin?: string;
+        trace?: any;
+    }): Promise<void>;
+    /**
+     * Primary Analysis Entry Point
+     */
+    analyze(input: string, provider?: AIProvider | BaseProvider, personaName?: string, locale?: string, instanceId?: string): Promise<IKMetrics>;
+    private getEmptyMetrics;
+    private createHeuristicMetrics;
+    private sniffDNA;
+    analyzeAIAssisted(input: string, provider?: AIProvider | BaseProvider, personaName?: string, instanceId?: string, configOverride?: Partial<IKConfig>): Promise<IKMetrics>;
+    private calculateDNARank;
+    private constructAuditPrompt;
+    private getFallbackMetrics;
+    crystallize(input: string, metrics?: IKMetrics, locale?: string): string;
+    private miniCrystallize;
+    getAgentDirective(personaName: string, userInsights?: IKMetrics['semanticInsights'], locale?: string): string;
+    private getApproachGuidance;
+}
+
+/**
+ * HeuristicGatekeeper: Implementation of local, non-API cognitive checks.
+ * Optimized for sub-millisecond execution.
+ * Now uses Multilingual Heuristic Dictionaries (MHD).
+ */
+declare class HeuristicGatekeeper {
+    private static readonly CONSTANTS;
+    analyze(input: string): {
+        complexityScore: number;
+        intentMode: 'ENGINEERING' | 'CONCEPTUAL' | 'SPECIALIZED';
+    };
+    /**
+     * Fast heuristic check for boundary communication (Safe Mode / Audit Ai)
+     * High score means AI/User might be breaking authorization rules.
+     */
+    evaluateBoundaryCommunication(input: string, customKeywords?: string[]): {
+        boundaryScore: number;
+        requiresHumanIntervention: boolean;
+    };
+}
+
+/**
+ * IK Multilingual Heuristic Dictionary (MHD)
+ * Compiled domain-specific keyword lists.
+ */
+declare const Dictionaries: {
+    engineering: string[];
+    conceptual: string[];
+    construction: string[];
+    medical: string[];
+    legal: string[];
+    finance: string[];
+    structural: string[];
+    relational: string[];
+    meta: {
+        en: {
+            immutable_desc: string;
+            blueprint_desc: string;
+            noise_desc: string;
+            audit_title: string;
+            audit_intro: string;
+            lang_rule: string;
+            schema_intro: string;
+            guide_title: string;
+            role_eng: string;
+            role_conceptual: string;
+            mode_l1: string;
+            mode_l2: string;
+            mode_l3: string;
+            mode_hybrid: string;
+            audit_rules_title: string;
+            audit_rule_1: string;
+            audit_rule_2: string;
+            audit_rule_3: string;
+            audit_rule_4: string;
+            audit_rule_5: string;
+            audit_rule_6: string;
+            eng_guide: string;
+            conceptual_guide: string;
+            steering_title: string;
+            priority_desc: string;
+            precision_gate: string;
+            params_title: string;
+            abstraction_title: string;
+            directness_title: string;
+            density_title: string;
+            adaptation_title: string;
+            adapt_rule_1: string;
+            adapt_rule_2: string;
+            adapt_rule_3: string;
+            tuning_desc: string;
+            medical_guardrail: string;
+            legal_precision: string;
+            finance_risk: string;
+            philo_protection: string;
+            slang_examples: string;
+            system_prompt_patterns: string;
+            structural_noise: string;
+            meta_audit_meta_role: string;
+            meta_audit_objectivity: string;
+            meta_audit_blueprint_density: string;
+            meta_audit_schema_logic: string;
+            meta_audit_transform_rule: string;
+            logic_anchor_title: string;
+            logic_anchor_rule: string;
+            anti_eloquence_rule: string;
+            meta_audit_narrative_protection: string;
+            kft_opt_rule: string;
+            meta_audit_meta_pragmatic_stance: string;
+            guidance_REFLECTIVE: string;
+            guidance_NARRATIVE: string;
+            guidance_PROBLEM_ORIENTED: string;
+            guidance_REFLECTIVE_NARRATIVE: string;
+            guidance_DIRECTIVE: string;
+            guidance_ARGUMENTATIVE: string;
+            guidance_DIALOGICAL: string;
+            interface_distinction_rule: string;
+            persona_narrator: string;
+            suppress_listing: string;
+            persona_professional: string;
+            persona_sharp: string;
+            persona_empathetic: string;
+            persona_provocative: string;
+            persona_lock: string;
+            persona_lock_fluid: string;
+            tone_high_stakes: string;
+            tone_engineering: string;
+            tone_fluid: string;
+            tone_warm: string;
+            tone_rapport: string;
+            tone_objective: string;
+            label_cognitive_resonance: string;
+            label_authoritative_blueprint: string;
+            label_authoritative_blueprint_desc: string;
+            label_performative_intent: string;
+            label_rhetorical_balance: string;
+            guidance_commissive: string;
+            guidance_directive: string;
+            aesthetic_logic_crystal: string;
+            aesthetic_strategic_bridge: string;
+            aesthetic_natural_flow: string;
+            aesthetic_neutral: string;
+            execution_mode_creative: string;
+            construction_precision: string;
+            tone_engineering_rapport: string;
+            iq_classification_title: string;
+            iq_tier_1_desc: string;
+            iq_tier_2_desc: string;
+            iq_tier_3_desc: string;
+            iq_routing_rule: string;
+            archetype_title: string;
+            archetype_crystal: string;
+            archetype_fluid: string;
+            archetype_neural: string;
+            archetype_dynamic: string;
+            essence_indexing_rule: string;
+            logical_focus_desc: string;
+        };
+        sr: {
+            immutable_desc: string;
+            blueprint_desc: string;
+            noise_desc: string;
+            audit_title: string;
+            audit_intro: string;
+            lang_rule: string;
+            schema_intro: string;
+            guide_title: string;
+            role_eng: string;
+            role_conceptual: string;
+            mode_l1: string;
+            mode_l2: string;
+            mode_l3: string;
+            mode_hybrid: string;
+            audit_rules_title: string;
+            audit_rule_1: string;
+            audit_rule_2: string;
+            audit_rule_3: string;
+            audit_rule_4: string;
+            audit_rule_5: string;
+            audit_rule_6: string;
+            eng_guide: string;
+            conceptual_guide: string;
+            steering_title: string;
+            priority_desc: string;
+            precision_gate: string;
+            params_title: string;
+            abstraction_title: string;
+            directness_title: string;
+            density_title: string;
+            adaptation_title: string;
+            adapt_rule_1: string;
+            adapt_rule_2: string;
+            adapt_rule_3: string;
+            tuning_desc: string;
+            medical_guardrail: string;
+            legal_precision: string;
+            finance_risk: string;
+            philo_protection: string;
+            slang_examples: string;
+            system_prompt_patterns: string;
+            structural_noise: string;
+            meta_audit_meta_role: string;
+            meta_audit_objectivity: string;
+            meta_audit_blueprint_density: string;
+            meta_audit_schema_logic: string;
+            meta_audit_transform_rule: string;
+            logic_anchor_title: string;
+            logic_anchor_rule: string;
+            anti_eloquence_rule: string;
+            meta_audit_narrative_protection: string;
+            kft_opt_rule: string;
+            meta_audit_meta_pragmatic_stance: string;
+            guidance_REFLECTIVE: string;
+            guidance_NARRATIVE: string;
+            guidance_PROBLEM_ORIENTED: string;
+            guidance_REFLECTIVE_NARRATIVE: string;
+            guidance_DIRECTIVE: string;
+            guidance_ARGUMENTATIVE: string;
+            guidance_DIALOGICAL: string;
+            interface_distinction_rule: string;
+            persona_professional: string;
+            persona_sharp: string;
+            persona_empathetic: string;
+            persona_provocative: string;
+            persona_narrator: string;
+            suppress_listing: string;
+            persona_lock: string;
+            persona_lock_fluid: string;
+            tone_high_stakes: string;
+            tone_engineering: string;
+            tone_fluid: string;
+            tone_warm: string;
+            tone_rapport: string;
+            tone_objective: string;
+            label_cognitive_resonance: string;
+            label_authoritative_blueprint: string;
+            label_authoritative_blueprint_desc: string;
+            label_performative_intent: string;
+            label_rhetorical_balance: string;
+            guidance_commissive: string;
+            guidance_directive: string;
+            guidance_DIDACTIC: string;
+            guidance_STRATEGIC: string;
+            guidance_CLINICAL: string;
+            guidance_PERSUASIVE: string;
+            aesthetic_logic_crystal: string;
+            aesthetic_strategic_bridge: string;
+            aesthetic_natural_flow: string;
+            aesthetic_neutral: string;
+            execution_mode_creative: string;
+            construction_precision: string;
+            tone_engineering_rapport: string;
+            iq_classification_title: string;
+            iq_tier_1_desc: string;
+            iq_tier_2_desc: string;
+            iq_tier_3_desc: string;
+            iq_routing_rule: string;
+            archetype_title: string;
+            archetype_crystal: string;
+            archetype_fluid: string;
+            archetype_neural: string;
+            archetype_dynamic: string;
+            essence_indexing_rule: string;
+            logical_focus_desc: string;
+        };
+        stances: {
+            categories: {
+                id: string;
+                subtypes: string[];
+                primaryIllocution: string;
+            }[];
+            illocutionaryPoints: {
+                ASSERTIVE: string;
+                DIRECTIVE: string;
+                COMMISSIVE: string;
+                EXPRESSIVE: string;
+                DECLARATIVE: string;
+            };
+        };
+    };
+    boundary: string[];
+};
+declare const DictionaryRegex: {
+    engineering: RegExp;
+    conceptual: RegExp;
+    construction: RegExp;
+    medical: RegExp;
+    legal: RegExp;
+    finance: RegExp;
+    structural: RegExp;
+    relational: RegExp;
+    boundary: RegExp;
+};
+
+interface TestCase {
+    category: string;
+    type: 'RAZVODNJENA' | 'ZBIJENA' | 'NORMAL';
+    length: 'KRACI' | 'DUZI';
+    text: string;
+}
+interface TestResult {
+    sp: number;
+    ck: number;
+    dm: number;
+    rec: string;
+    duration: number;
+}
+declare class SurgicalTester {
+    private static instance;
+    private core;
+    private constructor();
+    static getInstance(): SurgicalTester;
+    runTest(text: string): Promise<TestResult[]>;
+    calculateAverages(results: TestResult[]): {
+        avgSp: number;
+        avgCk: number;
+        avgDm: number;
+    };
+}
+
+interface StressTestCase {
+    category: string;
+    type: 'RAZVODNJENA' | 'ZBIJENA' | 'NORMAL';
+    length: 'KRACI' | 'DUZI';
+    text: string;
+}
+interface StressReport {
+    category: string;
+    type: string;
+    length: string;
+    averages: {
+        dm: string;
+        sp: string;
+        ck: string;
+        units: number;
+    };
+    recommendation: string;
+    status: string;
+}
+declare class StressTester {
+    private static instance;
+    private core;
+    private constructor();
+    static getInstance(): StressTester;
+    runSuite(testCases: StressTestCase[]): Promise<StressReport[]>;
+}
+
+declare const IKBenchmarks: {
+    SHORT_TEST: TestPrompt[];
+    BIG_TEST: TestPrompt[];
+};
+
+export { type AIProvider, type AIResponse, AnthropicProvider, BaseProvider, type ContextMode, DeepSeekProvider, Dictionaries, DictionaryRegex, GeminiProvider, HeuristicGatekeeper, IKBenchmarks, type IKConfig, IKFirewallCore, type IKHooks, type IKMetrics, type IKPluginInfo, LocalProvider, type ModelRole, OpenAIProvider, type PromptLength, type PromptType, type ProviderMode, type RuntimeStrategy, type StressReport, type StressTestCase, StressTester, SurgicalTester, type TestCase, type TestPrompt, type TestResult, type UsageData };