@weavelogic/knowledge-graph-agent 0.2.0 → 0.4.0

package/dist/agents/rules-engine.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Rules Engine
+ *
+ * Event-driven rule execution engine with async processing, condition evaluation,
+ * error isolation, and performance tracking.
+ *
+ * @module agents/rules-engine
+ */
+import { type Logger } from '../utils/index.js';
+/**
+ * Trigger types for rule execution
+ */
+export type RuleTrigger = 'file:add' | 'file:change' | 'file:unlink' | 'graph:update' | 'agent:complete' | 'manual';
+/**
+ * Rule priority levels
+ */
+export type RulePriority = 'low' | 'normal' | 'high' | 'critical';
+/**
+ * Rule execution status
+ */
+export type RuleExecutionStatus = 'pending' | 'running' | 'success' | 'failure' | 'skipped';
+/**
+ * Context provided to rules during execution
+ */
+export interface RuleContext {
+    /** The trigger event that caused this execution */
+    trigger: RuleTrigger;
+    /** Timestamp when the event occurred */
+    timestamp: Date;
+    /** Path to the file (for file-related triggers) */
+    filePath?: string;
+    /** Previous file content (for file:change) */
+    previousContent?: string;
+    /** Current file content */
+    currentContent?: string;
+    /** Graph-related data (for graph:update) */
+    graphData?: {
+        nodesAdded?: number;
+        nodesRemoved?: number;
+        edgesModified?: number;
+    };
+    /** Agent completion data (for agent:complete) */
+    agentData?: {
+        agentId: string;
+        taskId: string;
+        result: 'success' | 'failure';
+        duration: number;
+    };
+    /** Custom metadata that can be attached to context */
+    metadata?: Record<string, unknown>;
+    /** Reference to the rules engine for chaining */
+    engine?: RulesEngine;
+}
+/**
+ * Condition function that determines if a rule should execute
+ */
+export type RuleCondition = (context: RuleContext) => boolean | Promise<boolean>;
+/**
+ * Action function that performs the rule's work
+ */
+export type RuleAction = (context: RuleContext) => void | Promise<void>;
+/**
+ * Rule definition
+ */
+export interface AgentRule {
+    /** Unique identifier for the rule */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Triggers that activate this rule */
+    triggers: RuleTrigger[];
+    /** Condition to evaluate before executing (optional) */
+    condition?: RuleCondition;
+    /** Action to execute */
+    action: RuleAction;
+    /** Rule priority (default: 'normal') */
+    priority?: RulePriority;
+    /** Whether the rule is enabled (default: true) */
+    enabled?: boolean;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Maximum execution time in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Whether to continue execution on failure (default: true) */
+    continueOnFailure?: boolean;
+}
+/**
+ * Execution log entry
+ */
+export interface RuleExecutionLog {
+    /** Rule ID */
+    ruleId: string;
+    /** Rule name */
+    ruleName: string;
+    /** Execution status */
+    status: RuleExecutionStatus;
+    /** Trigger that caused execution */
+    trigger: RuleTrigger;
+    /** Start timestamp */
+    startedAt: Date;
+    /** End timestamp */
+    completedAt?: Date;
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Error message if failed */
+    error?: string;
+    /** Whether condition was evaluated */
+    conditionEvaluated?: boolean;
+    /** Result of condition evaluation */
+    conditionResult?: boolean;
+    /** Context snapshot (partial) */
+    contextSnapshot?: {
+        filePath?: string;
+        trigger: RuleTrigger;
+        timestamp: Date;
+    };
+}
+/**
+ * Rule execution statistics
+ */
+export interface RuleStatistics {
+    /** Rule ID */
+    ruleId: string;
+    /** Rule name */
+    ruleName: string;
+    /** Total executions */
+    totalExecutions: number;
+    /** Successful executions */
+    successCount: number;
+    /** Failed executions */
+    failureCount: number;
+    /** Skipped executions (condition false) */
+    skippedCount: number;
+    /** Average execution time in milliseconds */
+    averageExecutionTime: number;
+    /** Min execution time */
+    minExecutionTime: number;
+    /** Max execution time */
+    maxExecutionTime: number;
+    /** Last execution timestamp */
+    lastExecutedAt?: Date;
+    /** Last successful execution */
+    lastSuccessAt?: Date;
+    /** Last failure timestamp */
+    lastFailureAt?: Date;
+}
+/**
+ * Engine-wide statistics
+ */
+export interface EngineStatistics {
+    /** Total rules registered */
+    totalRules: number;
+    /** Enabled rules count */
+    enabledRules: number;
+    /** Total executions across all rules */
+    totalExecutions: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Average execution time across all rules */
+    averageExecutionTime: number;
+    /** Rules currently executing */
+    activeExecutions: number;
+    /** Per-rule statistics */
+    ruleStats: Map<string, RuleStatistics>;
+    /** Per-trigger statistics */
+    triggerStats: Map<RuleTrigger, {
+        totalExecutions: number;
+        successCount: number;
+        averageTime: number;
+    }>;
+}
+/**
+ * Rules engine configuration
+ */
+export interface RulesEngineConfig {
+    /** Maximum concurrent rule executions (default: 10) */
+    maxConcurrency?: number;
+    /** Default timeout for rules in milliseconds (default: 30000) */
+    defaultTimeout?: number;
+    /** Size of the execution log circular buffer (default: 1000) */
+    logBufferSize?: number;
+    /** Whether to enable detailed logging (default: false) */
+    verbose?: boolean;
+    /** Custom logger instance */
+    logger?: Logger;
+}
+/**
+ * Event-driven rules engine with async processing and error isolation
+ */
+export declare class RulesEngine {
+    private rules;
+    private executionLogs;
+    private ruleStats;
+    private triggerStats;
+    private activeExecutions;
+    private readonly logger;
+    private readonly config;
+    constructor(config?: RulesEngineConfig);
+    /**
+     * Register a new rule
+     */
+    registerRule(rule: AgentRule): void;
+    /**
+     * Register multiple rules at once
+     */
+    registerRules(rules: AgentRule[]): void;
+    /**
+     * Unregister a rule by ID
+     */
+    unregisterRule(ruleId: string): boolean;
+    /**
+     * Get a rule by ID
+     */
+    getRule(ruleId: string): AgentRule | undefined;
+    /**
+     * Get all registered rules
+     */
+    getAllRules(): AgentRule[];
+    /**
+     * Get rules by trigger type
+     */
+    getRulesByTrigger(trigger: RuleTrigger): AgentRule[];
+    /**
+     * Enable a rule
+     */
+    enableRule(ruleId: string): boolean;
+    /**
+     * Disable a rule
+     */
+    disableRule(ruleId: string): boolean;
+    /**
+     * Trigger rule execution for an event
+     */
+    trigger(trigger: RuleTrigger, context?: Partial<RuleContext>): Promise<RuleExecutionLog[]>;
+    /**
+     * Execute a single rule
+     */
+    private executeRule;
+    /**
+     * Execute a rule by ID with custom context
+     */
+    executeRuleById(ruleId: string, context?: Partial<RuleContext>): Promise<RuleExecutionLog | null>;
+    /**
+     * Wrap a promise with a timeout
+     */
+    private withTimeout;
+    /**
+     * Update statistics after rule execution
+     */
+    private updateStats;
+    /**
+     * Get statistics for a specific rule
+     */
+    getRuleStatistics(ruleId: string): RuleStatistics | undefined;
+    /**
+     * Get engine-wide statistics
+     */
+    getStatistics(): EngineStatistics;
+    /**
+     * Get execution logs (most recent first)
+     */
+    getExecutionLogs(limit?: number): RuleExecutionLog[];
+    /**
+     * Get logs for a specific rule
+     */
+    getLogsForRule(ruleId: string, limit?: number): RuleExecutionLog[];
+    /**
+     * Get logs for a specific trigger
+     */
+    getLogsForTrigger(trigger: RuleTrigger, limit?: number): RuleExecutionLog[];
+    /**
+     * Get failed execution logs
+     */
+    getFailedLogs(limit?: number): RuleExecutionLog[];
+    /**
+     * Clear execution logs
+     */
+    clearLogs(): void;
+    /**
+     * Reset all statistics
+     */
+    resetStatistics(): void;
+    /**
+     * Get a summary of the engine state
+     */
+    getSummary(): {
+        rulesCount: number;
+        enabledCount: number;
+        triggersConfigured: RuleTrigger[];
+        activeExecutions: number;
+        logsCount: number;
+    };
+}
+/**
+ * Create a new rules engine instance
+ */
+export declare function createRulesEngine(config?: RulesEngineConfig): RulesEngine;
+/**
+ * Create a simple rule definition
+ */
+export declare function createRule(id: string, name: string, triggers: RuleTrigger[], action: RuleAction, options?: Partial<Omit<AgentRule, 'id' | 'name' | 'triggers' | 'action'>>): AgentRule;
+/**
+ * Create a conditional rule
+ */
+export declare function createConditionalRule(id: string, name: string, triggers: RuleTrigger[], condition: RuleCondition, action: RuleAction, options?: Partial<Omit<AgentRule, 'id' | 'name' | 'triggers' | 'condition' | 'action'>>): AgentRule;
+/**
+ * Create a file change logging rule
+ */
+export declare function createFileChangeLogRule(logger?: Logger): AgentRule;
+/**
+ * Create a graph update notification rule
+ */
+export declare function createGraphUpdateNotificationRule(callback: (context: RuleContext) => void | Promise<void>): AgentRule;
+/**
+ * Create an agent completion handler rule
+ */
+export declare function createAgentCompletionRule(handler: (agentData: NonNullable<RuleContext['agentData']>) => void | Promise<void>): AgentRule;
+//# sourceMappingURL=rules-engine.d.ts.map

package/dist/agents/rules-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-engine.d.ts","sourceRoot":"","sources":["../../src/agents/rules-engine.ts"],"names":[],"mappings":"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"}