@panguard-ai/core 0.1.0

package/dist/ai/response-parser.js

@@ -0,0 +1,195 @@
+/**
+ * LLM response parsing utilities
+ * LLM 回應解析工具
+ *
+ * Parses raw LLM text responses into structured data objects.
+ * Supports JSON extraction from markdown code blocks and plain text fallback.
+ * 將原始 LLM 文字回應解析為結構化資料物件。
+ * 支援從 Markdown 程式碼區塊提取 JSON 以及純文字回退。
+ *
+ * @module @panguard-ai/core/ai/response-parser
+ */
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('ai:response-parser');
+/**
+ * Valid severity values for validation
+ * 用於驗證的有效嚴重等級值
+ * @internal
+ */
+const VALID_SEVERITIES = new Set([
+    'info',
+    'low',
+    'medium',
+    'high',
+    'critical',
+]);
+/**
+ * Attempt to extract a JSON object from a raw string
+ * 嘗試從原始字串中提取 JSON 物件
+ *
+ * Tries in order: direct JSON.parse, markdown code block extraction, brace extraction.
+ * 依序嘗試：直接 JSON.parse、Markdown 程式碼區塊提取、大括號提取。
+ *
+ * @param raw - Raw LLM response text / 原始 LLM 回應文字
+ * @returns Parsed object or null if parsing fails / 解析的物件，或解析失敗時回傳 null
+ * @internal
+ */
+function extractJson(raw) {
+    const trimmed = raw.trim();
+    // Strategy 1: Direct JSON.parse
+    // 策略 1：直接 JSON.parse
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === 'object' && parsed !== null) {
+            return parsed;
+        }
+    }
+    catch {
+        // Not pure JSON, try next strategy
+        // 非純 JSON，嘗試下一個策略
+    }
+    // Strategy 2: Extract from markdown code block (```json ... ``` or ``` ... ```)
+    // 策略 2：從 Markdown 程式碼區塊提取
+    const codeBlockMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+    if (codeBlockMatch?.[1]) {
+        try {
+            const parsed = JSON.parse(codeBlockMatch[1].trim());
+            if (typeof parsed === 'object' && parsed !== null) {
+                return parsed;
+            }
+        }
+        catch {
+            // Code block content is not valid JSON
+            // 程式碼區塊內容非有效 JSON
+        }
+    }
+    // Strategy 3: Find first { ... } block (greedy inner match)
+    // 策略 3：尋找第一個 { ... } 區塊
+    const braceStart = trimmed.indexOf('{');
+    const braceEnd = trimmed.lastIndexOf('}');
+    if (braceStart !== -1 && braceEnd > braceStart) {
+        try {
+            const jsonCandidate = trimmed.slice(braceStart, braceEnd + 1);
+            const parsed = JSON.parse(jsonCandidate);
+            if (typeof parsed === 'object' && parsed !== null) {
+                return parsed;
+            }
+        }
+        catch {
+            // Brace extraction failed
+            // 大括號提取失敗
+        }
+    }
+    return null;
+}
+/**
+ * Validate and coerce a severity string
+ * 驗證並強制轉換嚴重等級字串
+ *
+ * @param value - Raw severity value / 原始嚴重等級值
+ * @returns Valid Severity or 'medium' as default / 有效嚴重等級或預設 'medium'
+ * @internal
+ */
+function coerceSeverity(value) {
+    if (typeof value === 'string' && VALID_SEVERITIES.has(value.toLowerCase())) {
+        return value.toLowerCase();
+    }
+    return 'medium';
+}
+/**
+ * Validate and coerce a confidence value
+ * 驗證並強制轉換信心值
+ *
+ * @param value - Raw confidence value / 原始信心值
+ * @returns Number between 0 and 1, default 0.5 / 0 到 1 之間的數字，預設 0.5
+ * @internal
+ */
+function coerceConfidence(value) {
+    if (typeof value === 'number' && isFinite(value)) {
+        return Math.max(0, Math.min(1, value));
+    }
+    if (typeof value === 'string') {
+        const num = parseFloat(value);
+        if (isFinite(num)) {
+            return Math.max(0, Math.min(1, num));
+        }
+    }
+    return 0.5;
+}
+/**
+ * Parse a raw LLM response into an AnalysisResult
+ * 將原始 LLM 回應解析為 AnalysisResult
+ *
+ * Attempts JSON parsing first, then falls back to treating the entire
+ * response as a text summary.
+ * 首先嘗試 JSON 解析，然後回退到將整個回應視為文字摘要。
+ *
+ * @param raw - Raw LLM response text / 原始 LLM 回應文字
+ * @returns Parsed analysis result / 解析的分析結果
+ */
+export function parseAnalysisResponse(raw) {
+    const json = extractJson(raw);
+    if (json) {
+        logger.debug('Successfully parsed analysis response as JSON', {
+            keys: Object.keys(json),
+        });
+        const recommendations = Array.isArray(json['recommendations'])
+            ? json['recommendations'].map(String)
+            : typeof json['recommendations'] === 'string'
+                ? [json['recommendations']]
+                : [];
+        return {
+            summary: typeof json['summary'] === 'string' ? json['summary'] : raw.slice(0, 500),
+            severity: coerceSeverity(json['severity']),
+            confidence: coerceConfidence(json['confidence']),
+            recommendations,
+            rawResponse: raw,
+        };
+    }
+    // Fallback: treat the entire response as a text summary
+    // 回退：將整個回應視為文字摘要
+    logger.debug('JSON parsing failed, using text fallback for analysis response');
+    return {
+        summary: raw.slice(0, 2000),
+        severity: 'medium',
+        confidence: 0.3,
+        recommendations: [],
+        rawResponse: raw,
+    };
+}
+/**
+ * Parse a raw LLM response into a ThreatClassification
+ * 將原始 LLM 回應解析為 ThreatClassification
+ *
+ * Attempts JSON parsing first, then falls back to a generic classification.
+ * 首先嘗試 JSON 解析，然後回退到通用分類。
+ *
+ * @param raw - Raw LLM response text / 原始 LLM 回應文字
+ * @returns Parsed threat classification / 解析的威脅分類
+ */
+export function parseClassificationResponse(raw) {
+    const json = extractJson(raw);
+    if (json) {
+        logger.debug('Successfully parsed classification response as JSON', {
+            keys: Object.keys(json),
+        });
+        return {
+            category: typeof json['category'] === 'string' ? json['category'] : 'Unknown',
+            technique: typeof json['technique'] === 'string' ? json['technique'] : 'T0000',
+            severity: coerceSeverity(json['severity']),
+            confidence: coerceConfidence(json['confidence']),
+            description: typeof json['description'] === 'string' ? json['description'] : raw.slice(0, 500),
+        };
+    }
+    // Fallback: generic unclassified threat
+    // 回退：通用未分類威脅
+    logger.debug('JSON parsing failed, using text fallback for classification response');
+    return {
+        category: 'Unknown',
+        technique: 'T0000',
+        severity: 'medium',
+        confidence: 0.2,
+        description: raw.slice(0, 500),
+    };
+}
+//# sourceMappingURL=response-parser.js.map

package/dist/ai/response-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-parser.js","sourceRoot":"","sources":["../../src/ai/response-parser.ts"],"names":[],"mappings":"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"}

package/dist/ai/token-tracker.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Token usage tracking and cost estimation
+ * Token 使用追蹤與費用估算
+ *
+ * Tracks cumulative token usage across LLM requests and calculates
+ * estimated costs based on provider-specific pricing.
+ * 追蹤跨 LLM 請求的累計 Token 使用量，並根據供應商定價計算估算費用。
+ *
+ * @module @panguard-ai/core/ai/token-tracker
+ */
+import type { LLMProviderType, TokenUsage } from './types.js';
+/**
+ * Tracks token usage and estimates cost for an LLM provider
+ * 追蹤 LLM 供應商的 Token 使用量並估算費用
+ */
+export declare class TokenTracker {
+    private readonly provider;
+    private readonly model;
+    /**
+     * Cumulative token usage / 累計 Token 使用量
+     * @internal
+     */
+    private usage;
+    /**
+     * Create a new TokenTracker instance
+     * 建立新的 TokenTracker 實例
+     *
+     * @param provider - The LLM provider type / LLM 供應商類型
+     * @param model - The model name / 模型名稱
+     */
+    constructor(provider: LLMProviderType, model: string);
+    /**
+     * Record token usage from a single request
+     * 記錄單次請求的 Token 使用量
+     *
+     * @param promptTokens - Number of prompt tokens used / 使用的提示詞 Token 數
+     * @param completionTokens - Number of completion tokens used / 使用的完成回應 Token 數
+     */
+    track(promptTokens: number, completionTokens: number): void;
+    /**
+     * Get current cumulative token usage
+     * 取得目前累計 Token 使用量
+     *
+     * @returns A copy of the current token usage / 目前 Token 使用量的副本
+     */
+    getUsage(): TokenUsage;
+    /**
+     * Reset all usage counters to zero
+     * 重置所有使用量計數器為零
+     */
+    reset(): void;
+    /**
+     * Calculate the estimated cost based on cumulative usage
+     * 根據累計使用量計算估算費用
+     *
+     * @returns Estimated cost in USD / 估算費用（美元）
+     * @internal
+     */
+    private calculateCost;
+    /**
+     * Look up pricing for the current provider and model
+     * 查詢目前供應商和模型的定價
+     *
+     * Falls back to provider default, then to zero cost.
+     * 回退到供應商預設值，然後回退到零費用。
+     *
+     * @returns Pricing tier / 定價層級
+     * @internal
+     */
+    private getPricing;
+}
+//# sourceMappingURL=token-tracker.d.ts.map

package/dist/ai/token-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-tracker.d.ts","sourceRoot":"","sources":["../../src/ai/token-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA8C9D;;;GAGG;AACH,qBAAa,YAAY;IAoBrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IApBxB;;;OAGG;IACH,OAAO,CAAC,KAAK,CAKX;IAEF;;;;;;OAMG;gBAEgB,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,MAAM;IAGhC;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAO3D;;;;;OAKG;IACH,QAAQ,IAAI,UAAU;IAItB;;;OAGG;IACH,KAAK,IAAI,IAAI;IASb;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;;;;;OASG;IACH,OAAO,CAAC,UAAU;CAuBnB"}

package/dist/ai/token-tracker.js

@@ -0,0 +1,145 @@
+/**
+ * Token usage tracking and cost estimation
+ * Token 使用追蹤與費用估算
+ *
+ * Tracks cumulative token usage across LLM requests and calculates
+ * estimated costs based on provider-specific pricing.
+ * 追蹤跨 LLM 請求的累計 Token 使用量，並根據供應商定價計算估算費用。
+ *
+ * @module @panguard-ai/core/ai/token-tracker
+ */
+/**
+ * Approximate pricing table for supported providers and models
+ * 支援的供應商和模型的近似定價表
+ *
+ * Pricing is per 1M tokens in USD.
+ * 定價為每 1M Token 的美元費用。
+ *
+ * @internal
+ */
+const PRICING = {
+    // Ollama: free (local inference)
+    // Ollama：免費（本地推論）
+    'ollama:default': { input: 0, output: 0 },
+    // Claude models (current generation)
+    'claude:claude-opus-4-6': { input: 15, output: 75 },
+    'claude:claude-sonnet-4-6': { input: 3, output: 15 },
+    'claude:claude-haiku-4-5-20251001': { input: 0.8, output: 4 },
+    // Claude models (previous generation)
+    'claude:claude-sonnet-4-20250514': { input: 3, output: 15 },
+    'claude:claude-3-5-sonnet-20241022': { input: 3, output: 15 },
+    'claude:claude-3-haiku-20240307': { input: 0.25, output: 1.25 },
+    'claude:claude-3-opus-20240229': { input: 15, output: 75 },
+    // OpenAI models
+    'openai:gpt-4o': { input: 2.5, output: 10 },
+    'openai:gpt-4o-mini': { input: 0.15, output: 0.6 },
+    'openai:gpt-4-turbo': { input: 10, output: 30 },
+    'openai:gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+};
+/**
+ * Tracks token usage and estimates cost for an LLM provider
+ * 追蹤 LLM 供應商的 Token 使用量並估算費用
+ */
+export class TokenTracker {
+    provider;
+    model;
+    /**
+     * Cumulative token usage / 累計 Token 使用量
+     * @internal
+     */
+    usage = {
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        estimatedCost: 0,
+    };
+    /**
+     * Create a new TokenTracker instance
+     * 建立新的 TokenTracker 實例
+     *
+     * @param provider - The LLM provider type / LLM 供應商類型
+     * @param model - The model name / 模型名稱
+     */
+    constructor(provider, model) {
+        this.provider = provider;
+        this.model = model;
+    }
+    /**
+     * Record token usage from a single request
+     * 記錄單次請求的 Token 使用量
+     *
+     * @param promptTokens - Number of prompt tokens used / 使用的提示詞 Token 數
+     * @param completionTokens - Number of completion tokens used / 使用的完成回應 Token 數
+     */
+    track(promptTokens, completionTokens) {
+        this.usage.promptTokens += promptTokens;
+        this.usage.completionTokens += completionTokens;
+        this.usage.totalTokens += promptTokens + completionTokens;
+        this.usage.estimatedCost = this.calculateCost();
+    }
+    /**
+     * Get current cumulative token usage
+     * 取得目前累計 Token 使用量
+     *
+     * @returns A copy of the current token usage / 目前 Token 使用量的副本
+     */
+    getUsage() {
+        return { ...this.usage };
+    }
+    /**
+     * Reset all usage counters to zero
+     * 重置所有使用量計數器為零
+     */
+    reset() {
+        this.usage = {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+            estimatedCost: 0,
+        };
+    }
+    /**
+     * Calculate the estimated cost based on cumulative usage
+     * 根據累計使用量計算估算費用
+     *
+     * @returns Estimated cost in USD / 估算費用（美元）
+     * @internal
+     */
+    calculateCost() {
+        const pricing = this.getPricing();
+        const inputCost = (this.usage.promptTokens / 1_000_000) * pricing.input;
+        const outputCost = (this.usage.completionTokens / 1_000_000) * pricing.output;
+        return Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000;
+    }
+    /**
+     * Look up pricing for the current provider and model
+     * 查詢目前供應商和模型的定價
+     *
+     * Falls back to provider default, then to zero cost.
+     * 回退到供應商預設值，然後回退到零費用。
+     *
+     * @returns Pricing tier / 定價層級
+     * @internal
+     */
+    getPricing() {
+        const key = `${this.provider}:${this.model}`;
+        if (PRICING[key]) {
+            return PRICING[key];
+        }
+        // Fallback: match by provider prefix
+        // 回退：按供應商前綴匹配
+        const providerDefault = `${this.provider}:default`;
+        if (PRICING[providerDefault]) {
+            return PRICING[providerDefault];
+        }
+        // All Ollama models are free (local)
+        // 所有 Ollama 模型免費（本地推論）
+        if (this.provider === 'ollama') {
+            return { input: 0, output: 0 };
+        }
+        // Unknown model: return zero to avoid incorrect charges
+        // 未知模型：回傳零以避免錯誤計費
+        return { input: 0, output: 0 };
+    }
+}
+//# sourceMappingURL=token-tracker.js.map

package/dist/ai/token-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-tracker.js","sourceRoot":"","sources":["../../src/ai/token-tracker.ts"],"names":[],"mappings":"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"}

package/dist/ai/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * AI/LLM unified interface type definitions
+ * AI/LLM 統一介面型別定義
+ *
+ * Defines the contracts for all LLM providers, analysis results,
+ * threat classifications, and token usage tracking.
+ * 定義所有 LLM 供應商、分析結果、威脅分類和 Token 使用追蹤的契約。
+ *
+ * @module @panguard-ai/core/ai/types
+ */
+import type { Language, Severity, SecurityEvent } from '../types.js';
+/**
+ * Supported LLM provider types
+ * 支援的 LLM 供應商類型
+ */
+export type LLMProviderType = 'ollama' | 'claude' | 'openai';
+/**
+ * Configuration for initializing an LLM provider
+ * 初始化 LLM 供應商的配置
+ */
+export interface LLMConfig {
+    /** Provider type / 供應商類型 */
+    provider: LLMProviderType;
+    /** Model name (e.g., 'llama3', 'claude-sonnet-4-20250514', 'gpt-4o') / 模型名稱 */
+    model: string;
+    /** API endpoint for Ollama, default 'http://localhost:11434' / Ollama API 端點 */
+    endpoint?: string;
+    /** API key for Claude/OpenAI / Claude/OpenAI API 金鑰 */
+    apiKey?: string;
+    /** Response language / 回應語言 */
+    lang: Language;
+    /** Sampling temperature, default 0.3 / 取樣溫度 */
+    temperature?: number;
+    /** Maximum output tokens, default 2048 / 最大輸出 Token 數 */
+    maxTokens?: number;
+    /** Request timeout in milliseconds, default 30000 / 請求逾時時間（毫秒） */
+    timeout?: number;
+}
+/**
+ * Result of an AI-powered security analysis
+ * AI 驅動的安全分析結果
+ */
+export interface AnalysisResult {
+    /** Human-readable summary of the analysis / 人類可讀的分析摘要 */
+    summary: string;
+    /** Assessed severity level / 評估的嚴重等級 */
+    severity: Severity;
+    /** Confidence score from 0 to 1 / 信心分數（0 到 1） */
+    confidence: number;
+    /** Actionable recommendations / 可執行的建議 */
+    recommendations: string[];
+    /** Raw LLM response for debugging / 原始 LLM 回應（供除錯用） */
+    rawResponse?: string;
+}
+/**
+ * MITRE ATT&CK-based threat classification
+ * 基於 MITRE ATT&CK 的威脅分類
+ */
+export interface ThreatClassification {
+    /** MITRE ATT&CK tactic category / MITRE ATT&CK 戰術分類 */
+    category: string;
+    /** MITRE ATT&CK technique ID (e.g., 'T1059') / MITRE ATT&CK 技術 ID */
+    technique: string;
+    /** Assessed severity level / 評估的嚴重等級 */
+    severity: Severity;
+    /** Confidence score from 0 to 1 / 信心分數（0 到 1） */
+    confidence: number;
+    /** Description of the classified threat / 分類威脅的描述 */
+    description: string;
+}
+/**
+ * Token usage and cost tracking
+ * Token 使用量與費用追蹤
+ */
+export interface TokenUsage {
+    /** Number of tokens in the prompt / 提示詞 Token 數量 */
+    promptTokens: number;
+    /** Number of tokens in the completion / 完成回應 Token 數量 */
+    completionTokens: number;
+    /** Total tokens (prompt + completion) / 總 Token 數量 */
+    totalTokens: number;
+    /** Estimated cost in USD / 估算費用（美元） */
+    estimatedCost: number;
+}
+/**
+ * Unified interface for all LLM providers
+ * 所有 LLM 供應商的統一介面
+ *
+ * Implementations must provide security-focused analysis, classification,
+ * and summarization capabilities.
+ * 實作必須提供安全導向的分析、分類和摘要功能。
+ */
+export interface LLMProvider {
+    /** The provider type identifier / 供應商類型識別碼 */
+    readonly providerType: LLMProviderType;
+    /** The model name being used / 使用的模型名稱 */
+    readonly model: string;
+    /**
+     * Analyze a security prompt with optional context
+     * 分析安全提示詞，可附帶上下文
+     *
+     * @param prompt - The analysis prompt / 分析提示詞
+     * @param context - Optional additional context / 可選的額外上下文
+     * @returns Analysis result / 分析結果
+     */
+    analyze(prompt: string, context?: string): Promise<AnalysisResult>;
+    /**
+     * Classify a security event using MITRE ATT&CK framework
+     * 使用 MITRE ATT&CK 框架分類安全事件
+     *
+     * @param event - The security event to classify / 要分類的安全事件
+     * @returns Threat classification / 威脅分類
+     */
+    classify(event: SecurityEvent): Promise<ThreatClassification>;
+    /**
+     * Summarize multiple security events into a report
+     * 將多個安全事件摘要為報告
+     *
+     * @param events - Array of security events / 安全事件陣列
+     * @returns Summary text / 摘要文字
+     */
+    summarize(events: SecurityEvent[]): Promise<string>;
+    /**
+     * Check if the provider is available and properly configured
+     * 檢查供應商是否可用且配置正確
+     *
+     * @returns True if provider is ready / 供應商就緒時回傳 true
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get cumulative token usage statistics
+     * 取得累計 Token 使用統計
+     *
+     * @returns Token usage data / Token 使用資料
+     */
+    getTokenUsage(): TokenUsage;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ai/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ai/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,EAAE,QAAQ,CAAC;IACnB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,QAAQ,EAAE,QAAQ,CAAC;IACnB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEnE;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE9D;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,aAAa,IAAI,UAAU,CAAC;CAC7B"}

package/dist/ai/types.js

@@ -0,0 +1,12 @@
+/**
+ * AI/LLM unified interface type definitions
+ * AI/LLM 統一介面型別定義
+ *
+ * Defines the contracts for all LLM providers, analysis results,
+ * threat classifications, and token usage tracking.
+ * 定義所有 LLM 供應商、分析結果、威脅分類和 Token 使用追蹤的契約。
+ *
+ * @module @panguard-ai/core/ai/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/ai/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/ai/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}