@salimassili/ai-costguard 1.1.3

package/dist/core/ExplainabilityLayer.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * ExplainabilityLayer.ts - Trust Through Transparency
+ *
+ * Every blocked request MUST show:
+ * - Why it was blocked
+ * - Cost prediction breakdown
+ * - Policy rule triggered
+ * - Confidence score
+ *
+ * No black-box decisions allowed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainabilityLayer = exports.ExplainabilityLayer = void 0;
+/**
+ * Explainability Layer
+ *
+ * Generates human-readable explanations for all decisions.
+ * Critical for trust and adoption in enterprise settings.
+ */
+class ExplainabilityLayer {
+    constructor() {
+        this.documentationBaseUrl = 'https://docs.ai-execution-control.com';
+    }
+    /**
+     * Generate comprehensive explanation for a decision
+     */
+    explain(request, executionResult, behaviorAnalysis, costPrediction, budgetAnalysis) {
+        const sections = [];
+        const recommendations = [];
+        // 1. Decision Summary
+        sections.push(this.createDecisionSection(request, executionResult));
+        // 2. Cost Breakdown
+        if (costPrediction && budgetAnalysis) {
+            sections.push(this.createCostSection(costPrediction, budgetAnalysis));
+            recommendations.push(...costPrediction.recommendations);
+        }
+        // 3. Policy Rules
+        if (executionResult.policyRulesTriggered.length > 0) {
+            sections.push(this.createPolicySection(executionResult));
+        }
+        // 4. Behavior Analysis
+        if (behaviorAnalysis) {
+            sections.push(this.createBehaviorSection(behaviorAnalysis));
+            recommendations.push(...behaviorAnalysis.recommendations);
+        }
+        // 5. Confidence & Evidence
+        sections.push(this.createConfidenceSection(executionResult, behaviorAnalysis));
+        // Build summary
+        const summary = this.buildSummary(request, executionResult, behaviorAnalysis, costPrediction);
+        return {
+            summary,
+            decision: request.decision,
+            confidence: executionResult.confidence,
+            sections,
+            recommendations: [...new Set(recommendations)], // dedupe
+            documentationLinks: this.getDocumentationLinks(executionResult),
+            appealProcess: request.decision === 'block' ? {
+                available: true,
+                reason: 'You can override this block with explicit approval',
+                contact: 'support@ai-execution-control.com',
+            } : undefined,
+        };
+    }
+    /**
+     * Format explanation for CLI output
+     */
+    formatForCLI(output) {
+        const lines = [];
+        // Header
+        lines.push('');
+        lines.push(`🔍 EXECUTION DECISION EXPLANATION`);
+        lines.push(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+        lines.push('');
+        // Decision badge
+        const decisionEmoji = output.decision === 'block' ? '🔴' :
+            output.decision === 'throttle' ? '🟡' : '🟢';
+        const decisionText = output.decision.toUpperCase();
+        lines.push(`${decisionEmoji} DECISION: ${decisionText}`);
+        lines.push(`Confidence: ${Math.round(output.confidence * 100)}%`);
+        lines.push('');
+        // Sections
+        for (const section of output.sections) {
+            lines.push(`${section.icon} ${section.title}`);
+            lines.push(section.content);
+            if (section.details) {
+                for (const detail of section.details) {
+                    lines.push(`  • ${detail}`);
+                }
+            }
+            if (section.data) {
+                for (const [key, value] of Object.entries(section.data)) {
+                    lines.push(`  ${key}: ${value}`);
+                }
+            }
+            lines.push('');
+        }
+        // Recommendations
+        if (output.recommendations.length > 0) {
+            lines.push('💡 RECOMMENDATIONS');
+            for (const rec of output.recommendations) {
+                lines.push(`  → ${rec}`);
+            }
+            lines.push('');
+        }
+        // Documentation
+        if (output.documentationLinks.length > 0) {
+            lines.push('📚 Learn more:');
+            for (const link of output.documentationLinks.slice(0, 3)) {
+                lines.push(`  ${link}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Format explanation for JSON/API response
+     */
+    formatForAPI(output) {
+        return {
+            summary: output.summary,
+            decision: output.decision,
+            confidence: output.confidence,
+            sections: output.sections.map(s => ({
+                title: s.title,
+                content: s.content,
+                details: s.details,
+                data: s.data,
+            })),
+            recommendations: output.recommendations,
+            documentation: output.documentationLinks,
+            appeal: output.appealProcess,
+        };
+    }
+    /**
+     * Format for dashboard/web UI
+     */
+    formatForDashboard(output) {
+        // Return as-is, UI components handle rendering
+        return output;
+    }
+    createDecisionSection(request, result) {
+        const decisionDescriptions = {
+            allow: 'Request approved for execution',
+            throttle: 'Request approved with rate limiting',
+            block: 'Request blocked due to policy violations',
+        };
+        return {
+            title: 'Decision Summary',
+            icon: '⚖️',
+            content: decisionDescriptions[request.decision],
+            details: [
+                `Request ID: ${request.requestId}`,
+                `Provider: ${request.provider}`,
+                `Model: ${request.model || 'N/A'}`,
+                `Timestamp: ${new Date(request.timestamp).toISOString()}`,
+                `Reason: ${result.reason}`,
+            ],
+        };
+    }
+    createCostSection(prediction, budget) {
+        const usedPercent = Math.round(budget.currentSpend / budget.budgetLimit * 100);
+        const predictedPercent = Math.round(prediction.predictedTotal / budget.budgetLimit * 100);
+        return {
+            title: 'Cost Analysis',
+            icon: '💰',
+            content: `Budget: $${budget.currentSpend.toFixed(2)} / $${budget.budgetLimit.toFixed(2)} used (${usedPercent}%)`,
+            details: [
+                `Current spend: $${budget.currentSpend.toFixed(4)}`,
+                `Predicted total: $${prediction.predictedTotal.toFixed(4)} (${predictedPercent}% of budget)`,
+                `Worst case: $${prediction.worstCase.toFixed(4)}`,
+                `Remaining budget: $${budget.remainingBudget.toFixed(4)}`,
+                `Will exceed budget: ${budget.willExceed ? 'YES' : 'NO'}`,
+            ],
+            data: {
+                'Risk Level': prediction.riskLevel.toUpperCase(),
+                'Confidence': `${Math.round(prediction.confidence * 100)}%`,
+                'Burn Rate': `$${budget.burnRate.toFixed(4)}/min`,
+            },
+            visual: 'progress',
+        };
+    }
+    createPolicySection(result) {
+        return {
+            title: 'Policy Enforcement',
+            icon: '📋',
+            content: `${result.policyRulesTriggered.length} policy rule(s) triggered`,
+            details: result.policyRulesTriggered.map(rule => `Rule: ${rule}`),
+            visual: 'list',
+        };
+    }
+    createBehaviorSection(analysis) {
+        const details = [];
+        if (analysis.loop.detected) {
+            details.push(`⚠️ Loop detected (${analysis.loop.loopType}): ${analysis.loop.confidence > 0.9 ? 'High confidence' : 'Medium confidence'}`);
+        }
+        if (analysis.redundancy.score > 0.5) {
+            details.push(`⚠️ Redundancy score: ${Math.round(analysis.redundancy.score * 100)}%`);
+        }
+        if (analysis.branching.isRunaway) {
+            details.push(`⚠️ Runaway branching detected (depth: ${analysis.branching.maxDepth})`);
+        }
+        if (analysis.retry.isRetryStorm) {
+            details.push(`⚠️ Retry storm detected (${analysis.retry.retryCount} retries)`);
+        }
+        return {
+            title: 'Behavior Analysis',
+            icon: '🧠',
+            content: `Workflow step ${analysis.totalCost > 0 ? 'with' : 'without'} anomalous patterns`,
+            details: details.length > 0 ? details : ['No anomalous patterns detected'],
+            data: {
+                'Workflow Steps': analysis.totalRequests || 0,
+                'Loop Detected': analysis.loop.detected ? 'YES' : 'NO',
+                'Redundancy Score': `${Math.round(analysis.redundancy.score * 100)}%`,
+                'Branch Depth': analysis.branching.maxDepth,
+                'Risk Score': `${analysis.riskScore}/100`,
+            },
+            visual: 'gauge',
+        };
+    }
+    createConfidenceSection(result, behaviorAnalysis) {
+        const confidencePercent = Math.round(result.confidence * 100);
+        const confidenceLevel = confidencePercent >= 90 ? 'Very High' :
+            confidencePercent >= 70 ? 'High' :
+                confidencePercent >= 50 ? 'Medium' : 'Low';
+        return {
+            title: 'Decision Confidence',
+            icon: '🎯',
+            content: `Confidence level: ${confidenceLevel} (${confidencePercent}%)`,
+            details: [
+                `Decision algorithm: Multi-factor analysis`,
+                `Data sources: Policy engine, Behavior graph, Cost prediction`,
+                `Behavioral data: ${behaviorAnalysis ? 'Available' : 'Not applicable'}`,
+            ],
+            data: {
+                'Confidence': `${confidencePercent}%`,
+                'Latency': `${(result.latencyMs ?? 0).toFixed(2)}ms`,
+                'Data Quality': behaviorAnalysis ? 'High' : 'Medium',
+            },
+        };
+    }
+    buildSummary(request, result, behaviorAnalysis, costPrediction) {
+        const parts = [];
+        if (request.decision === 'block') {
+            parts.push('Execution blocked.');
+        }
+        else if (request.decision === 'throttle') {
+            parts.push('Execution allowed with rate limiting.');
+        }
+        else {
+            parts.push('Execution approved.');
+        }
+        parts.push(`Reason: ${result.reason}`);
+        if (behaviorAnalysis?.loop.detected) {
+            parts.push('Behavioral anomaly: Loop detected.');
+        }
+        if (costPrediction?.riskLevel === 'high' || costPrediction?.riskLevel === 'critical') {
+            parts.push(`Cost risk: ${costPrediction.riskLevel}.`);
+        }
+        return parts.join(' ');
+    }
+    getDocumentationLinks(result) {
+        const links = [];
+        links.push(`${this.documentationBaseUrl}/decisions/${result.decision}`);
+        if (result.policyRulesTriggered.length > 0) {
+            links.push(`${this.documentationBaseUrl}/policies/overview`);
+        }
+        if (result.costPrediction) {
+            links.push(`${this.documentationBaseUrl}/cost-prediction`);
+        }
+        return links;
+    }
+}
+exports.ExplainabilityLayer = ExplainabilityLayer;
+// Export singleton
+exports.explainabilityLayer = new ExplainabilityLayer();
+//# sourceMappingURL=ExplainabilityLayer.js.map

package/dist/core/ExplainabilityLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExplainabilityLayer.js","sourceRoot":"","sources":["../../src/core/ExplainabilityLayer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AA0EH;;;;;GAKG;AACH,MAAa,mBAAmB;IAAhC;QACU,yBAAoB,GAAW,uCAAuC,CAAC;IAuTjF,CAAC;IArTC;;OAEG;IACH,OAAO,CACL,OAA2B,EAC3B,eAAwC,EACxC,gBAAmC,EACnC,cAA+B,EAC/B,cAA+B;QAE/B,MAAM,QAAQ,GAAyB,EAAE,CAAC;QAC1C,MAAM,eAAe,GAAa,EAAE,CAAC;QAErC,sBAAsB;QACtB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;QAEpE,oBAAoB;QACpB,IAAI,cAAc,IAAI,cAAc,EAAE,CAAC;YACrC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC;YACtE,eAAe,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;QAC1D,CAAC;QAED,kBAAkB;QAClB,IAAI,eAAe,CAAC,oBAAoB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC,CAAC;QAC3D,CAAC;QAED,uBAAuB;QACvB,IAAI,gBAAgB,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,CAAC,CAAC;YAC5D,eAAe,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;QAC5D,CAAC;QAED,2BAA2B;QAC3B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC,CAAC;QAE/E,gBAAgB;QAChB,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,CAAC,CAAC;QAE9F,OAAO;YACL,OAAO;YACP,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,UAAU,EAAE,eAAe,CAAC,UAAU;YACtC,QAAQ;YACR,eAAe,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,CAAC,EAAE,SAAS;YACzD,kBAAkB,EAAE,IAAI,CAAC,qBAAqB,CAAC,eAAe,CAAC;YAC/D,aAAa,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC;gBAC5C,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,oDAAoD;gBAC5D,OAAO,EAAE,kCAAkC;aAC5C,CAAC,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAyB;QACpC,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,SAAS;QACT,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,iBAAiB;QACjB,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACrC,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAClE,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACnD,KAAK,CAAC,IAAI,CAAC,GAAG,aAAa,cAAc,YAAY,EAAE,CAAC,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,WAAW;QACX,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAE5B,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpB,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;oBACrC,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBACxD,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;YAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,kBAAkB;QAClB,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;gBACzC,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;YAC3B,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,gBAAgB;QAChB,IAAI,MAAM,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;gBACzD,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAyB;QACpC,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAClC,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,IAAI,EAAE,CAAC,CAAC,IAAI;aACb,CAAC,CAAC;YACH,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,aAAa,EAAE,MAAM,CAAC,kBAAkB;YACxC,MAAM,EAAE,MAAM,CAAC,aAAa;SAC7B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,kBAAkB,CAAC,MAAyB;QAC1C,+CAA+C;QAC/C,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,qBAAqB,CAC3B,OAA2B,EAC3B,MAA+B;QAE/B,MAAM,oBAAoB,GAA2B;YACnD,KAAK,EAAE,gCAAgC;YACvC,QAAQ,EAAE,qCAAqC;YAC/C,KAAK,EAAE,0CAA0C;SAClD,CAAC;QAEF,OAAO;YACL,KAAK,EAAE,kBAAkB;YACzB,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,QAAQ,CAAC;YAC/C,OAAO,EAAE;gBACP,eAAe,OAAO,CAAC,SAAS,EAAE;gBAClC,aAAa,OAAO,CAAC,QAAQ,EAAE;gBAC/B,UAAU,OAAO,CAAC,KAAK,IAAI,KAAK,EAAE;gBAClC,cAAc,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE;gBACzD,WAAW,MAAM,CAAC,MAAM,EAAE;aAC3B;SACF,CAAC;IACJ,CAAC;IAEO,iBAAiB,CACvB,UAA0B,EAC1B,MAAsB;QAEtB,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,CAAC;QAC/E,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,cAAc,GAAG,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,CAAC;QAE1F,OAAO;YACL,KAAK,EAAE,eAAe;YACtB,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,YAAY,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,WAAW,IAAI;YAChH,OAAO,EAAE;gBACP,mBAAmB,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;gBACnD,qBAAqB,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,gBAAgB,cAAc;gBAC5F,gBAAgB,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;gBACjD,sBAAsB,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;gBACzD,uBAAuB,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;aAC1D;YACD,IAAI,EAAE;gBACJ,YAAY,EAAE,UAAU,CAAC,SAAS,CAAC,WAAW,EAAE;gBAChD,YAAY,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG;gBAC3D,WAAW,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;aAClD;YACD,MAAM,EAAE,UAAU;SACnB,CAAC;IACJ,CAAC;IAEO,mBAAmB,CAAC,MAA+B;QACzD,OAAO;YACL,KAAK,EAAE,oBAAoB;YAC3B,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,GAAG,MAAM,CAAC,oBAAoB,CAAC,MAAM,2BAA2B;YACzE,OAAO,EAAE,MAAM,CAAC,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC;YACjE,MAAM,EAAE,MAAM;SACf,CAAC;IACJ,CAAC;IAEO,qBAAqB,CAAC,QAA0B;QACtD,MAAM,OAAO,GAAa,EAAE,CAAC;QAE7B,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,qBAAqB,QAAQ,CAAC,IAAI,CAAC,QAAQ,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC;QAC5I,CAAC;QAED,IAAI,QAAQ,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,wBAAwB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvF,CAAC;QAED,IAAI,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,yCAAyC,QAAQ,CAAC,SAAS,CAAC,QAAQ,GAAG,CAAC,CAAC;QACxF,CAAC;QAED,IAAI,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,4BAA4B,QAAQ,CAAC,KAAK,CAAC,UAAU,WAAW,CAAC,CAAC;QACjF,CAAC;QAED,OAAO;YACL,KAAK,EAAE,mBAAmB;YAC1B,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,iBAAiB,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,qBAAqB;YAC1F,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,gCAAgC,CAAC;YAC1E,IAAI,EAAE;gBACJ,gBAAgB,EAAE,QAAQ,CAAC,aAAa,IAAI,CAAC;gBAC7C,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;gBACtD,kBAAkB,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG;gBACrE,cAAc,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ;gBAC3C,YAAY,EAAE,GAAG,QAAQ,CAAC,SAAS,MAAM;aAC1C;YACD,MAAM,EAAE,OAAO;SAChB,CAAC;IACJ,CAAC;IAEO,uBAAuB,CAC7B,MAA+B,EAC/B,gBAAmC;QAEnC,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC;QAC9D,MAAM,eAAe,GAAG,iBAAiB,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;YACxC,iBAAiB,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;gBAClC,iBAAiB,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;QAElE,OAAO;YACL,KAAK,EAAE,qBAAqB;YAC5B,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,qBAAqB,eAAe,KAAK,iBAAiB,IAAI;YACvE,OAAO,EAAE;gBACP,2CAA2C;gBAC3C,8DAA8D;gBAC9D,oBAAoB,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,EAAE;aACxE;YACD,IAAI,EAAE;gBACJ,YAAY,EAAE,GAAG,iBAAiB,GAAG;gBACrC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;gBACpD,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;aACrD;SACF,CAAC;IACJ,CAAC;IAEO,YAAY,CAClB,OAA2B,EAC3B,MAA+B,EAC/B,gBAAmC,EACnC,cAA+B;QAE/B,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACpC,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAEvC,IAAI,gBAAgB,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,cAAc,EAAE,SAAS,KAAK,MAAM,IAAI,cAAc,EAAE,SAAS,KAAK,UAAU,EAAE,CAAC;YACrF,KAAK,CAAC,IAAI,CAAC,cAAc,cAAc,CAAC,SAAS,GAAG,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAEO,qBAAqB,CAAC,MAA+B;QAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,oBAAoB,cAAc,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAExE,IAAI,MAAM,CAAC,oBAAoB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,oBAAoB,oBAAoB,CAAC,CAAC;QAC/D,CAAC;QAED,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,oBAAoB,kBAAkB,CAAC,CAAC;QAC7D,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAxTD,kDAwTC;AAED,mBAAmB;AACN,QAAA,mBAAmB,GAAG,IAAI,mBAAmB,EAAE,CAAC"}

package/dist/core/LearningSystem.d.ts

@@ -0,0 +1,124 @@
+/**
+ * LearningSystem.ts - Behavioral Dataset Moat
+ *
+ * Stores anonymized execution patterns:
+ * - Loops and failure patterns
+ * - Cost explosions
+ * - Anomalous agent behaviors
+ *
+ * This is the ONLY long-term defensibility layer.
+ * Improves detection accuracy over time without storing raw sensitive data.
+ */
+export interface AnonymizedPattern {
+    id: string;
+    timestamp: number;
+    patternType: 'loop' | 'cost_explosion' | 'retry_storm' | 'redundancy' | 'anomaly';
+    inputHash: string;
+    actionSequenceHash: string;
+    actionCount: number;
+    durationMs: number;
+    totalCost: number;
+    depth: number;
+    branchFactor: number;
+    outcome: 'blocked' | 'throttled' | 'completed' | 'failed';
+    preventedCost: number;
+    detectionVersion: string;
+    confidence: number;
+}
+export interface PatternSignature {
+    inputHash: string;
+    actionSequenceHash: string;
+    patternType: string;
+}
+export interface DetectionImprovement {
+    patternType: string;
+    version: string;
+    totalDetections: number;
+    truePositives: number;
+    falsePositives: number;
+    accuracy: number;
+    averageConfidence: number;
+}
+export interface CommunityPattern {
+    patternHash: string;
+    patternType: string;
+    occurrenceCount: number;
+    averageCost: number;
+    detectionStrategy: string;
+    contributedBy: string;
+}
+/**
+ * Learning System - Dataset Moat
+ *
+ * Design principles:
+ * 1. NO raw sensitive data stored (only hashes and metrics)
+ * 2. Patterns improve detection algorithms
+ * 3. Community contributions strengthen the moat
+ * 4. Exportable for research/compliance
+ */
+export declare class LearningSystem {
+    private dataDir;
+    private patternsFile;
+    private improvementsFile;
+    private patterns;
+    private maxPatternsPerType;
+    private currentVersion;
+    constructor();
+    private ensureDirectory;
+    private loadPatterns;
+    private savePatterns;
+    /**
+     * Record an anonymized pattern
+     * No raw sensitive data is stored - only fingerprints and metrics
+     */
+    recordPattern(params: {
+        patternType: AnonymizedPattern['patternType'];
+        input: string;
+        actionSequence: string[];
+        actionCount: number;
+        durationMs: number;
+        totalCost: number;
+        depth: number;
+        branchFactor: number;
+        outcome: AnonymizedPattern['outcome'];
+        preventedCost: number;
+        confidence: number;
+    }): AnonymizedPattern;
+    /**
+     * Find similar patterns
+     * Used to improve detection confidence
+     */
+    findSimilarPatterns(input: string, actionSequence: string[], patternType?: string): AnonymizedPattern[];
+    /**
+     * Get detection improvement metrics
+     */
+    getImprovements(): DetectionImprovement[];
+    /**
+     * Get patterns for export (anonymized)
+     * Can be shared with community for research
+     */
+    exportPatterns(patternType?: string, limit?: number): AnonymizedPattern[];
+    /**
+     * Import community patterns
+     * Strengthens the moat with collective knowledge
+     */
+    importCommunityPatterns(communityPatterns: CommunityPattern[]): number;
+    /**
+     * Get pattern statistics
+     */
+    getStats(): {
+        totalPatterns: number;
+        patternsByType: Record<string, number>;
+        totalPreventedCost: number;
+        averageAccuracy: number;
+    };
+    /**
+     * Clear all patterns
+     */
+    clear(): void;
+    private findPatternByHash;
+    private hashString;
+    private generateId;
+}
+export declare const learningSystem: LearningSystem;
+//# sourceMappingURL=LearningSystem.d.ts.map

package/dist/core/LearningSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LearningSystem.d.ts","sourceRoot":"","sources":["../../src/core/LearningSystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,gBAAgB,GAAG,aAAa,GAAG,YAAY,GAAG,SAAS,CAAC;IAElF,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAE3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IAErB,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,aAAa,EAAE,MAAM,CAAC;IAEtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,kBAAkB,CAAiB;IAC3C,OAAO,CAAC,cAAc,CAAmB;;IAWzC,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,YAAY;IAYpB;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE;QACpB,WAAW,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;QAC9C,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACtC,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,iBAAiB;IAgCrB;;;OAGG;IACH,mBAAmB,CACjB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EAAE,EACxB,WAAW,CAAC,EAAE,MAAM,GACnB,iBAAiB,EAAE;IAyBtB;;OAEG;IACH,eAAe,IAAI,oBAAoB,EAAE;IAwCzC;;;OAGG;IACH,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,MAAa,GAAG,iBAAiB,EAAE;IAa/E;;;OAGG;IACH,uBAAuB,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,GAAG,MAAM;IAwCtE;;OAEG;IACH,QAAQ,IAAI;QACV,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,kBAAkB,EAAE,MAAM,CAAC;QAC3B,eAAe,EAAE,MAAM,CAAC;KACzB;IA4BD;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,UAAU;CAGnB;AAGD,eAAO,MAAM,cAAc,gBAAuB,CAAC"}