decision_agent 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fac7efbaf0c8afd76053d21e611eca64f5880d5b6434720fd90ae34549f6244d
-  data.tar.gz: ecc22d0a9bb19053fd103b06f2c1be768db432b6d9ed715eac8adddcbd6f68dc
+  metadata.gz: a6adecd350c20f336995ee4954e26f9be65dee45fb9d31838be996eda5928d3d
+  data.tar.gz: cb55474c53415d83a4d8a66598b8a4fcfd526472c5419612d9491df4ea02832f
 SHA512:
-  metadata.gz: b7a0be6ad95512697b6e49a8145668cde64256051db57a39cf925edbd93886d7772cb93026a9af7a9eaea2e9968756ec628ca94d0ebc5a0d1aef0c409eeae97d
-  data.tar.gz: 06777a3c4155b1adff552f712a05a0d4bd2694c6f8af631e36611528c050cf1ea711268230dba6d1a64522e127c0c312b7221fd5d36bdc56f69009b0a98c17e4
+  metadata.gz: f2f14271db7d5ba25d3e3604396c221cce07ed62824025d1686c4950a06cf2f064cd5498053aa49f613d09e8a0da62fccdc880f293209cb6e30dfe3119fe567c
+  data.tar.gz: b32ddb86d61e4588d4db68e6a4f441b2a35688918ddde831ef6b47a19782dfd36f68931d1cd9e1885f59fae1f63af96f683401c6f382e119c7fb23477940075c

data/README.md

@@ -11,11 +11,13 @@ A production-grade, deterministic, explainable, and auditable decision engine fo
 
 ## Why DecisionAgent?
 
+DecisionAgent is designed for applications that require **deterministic, explainable, and auditable** decision-making:
+
 - ✅ **Deterministic** - Same input always produces same output
 - ✅ **Explainable** - Every decision includes human-readable reasoning
 - ✅ **Auditable** - Reproduce any historical decision exactly
 - ✅ **Framework-agnostic** - Pure Ruby, works anywhere
-- ✅ **Production-ready** - Comprehensive testing, error handling, and versioning
+- ✅ **Production-ready** - Comprehensive testing ([Coverage Report](coverage.md)), error handling, and versioning
 
 ## Installation
 
@@ -24,6 +26,7 @@ gem install decision_agent
 ```
 
 Or add to your Gemfile:
+
 ```ruby
 gem 'decision_agent'
 ```
@@ -57,11 +60,38 @@ puts result.confidence    # => 0.9
 puts result.explanations  # => ["High value transaction"]
 ```
 
-## Web UI - Visual Rule Builder
+See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
+
+## Key Features
+
+### Decision Making
+- **Multiple Evaluators** - Combine rule-based, ML, and custom logic
+- **Conflict Resolution** - Weighted average, consensus, threshold, max weight
+- **Rich Context** - Nested data, dot notation, flexible operators
+- **Advanced Operators** - String, numeric, date/time, collection, and geospatial operators
+
+### Auditability & Compliance
+- **Complete Audit Trails** - Every decision fully logged
+- **Deterministic Replay** - Reproduce historical decisions exactly
+- **RFC 8785 Canonical JSON** - Industry-standard deterministic hashing
+- **Compliance Ready** - HIPAA, SOX, regulatory compliance support
+
+### Developer Experience
+- **Pluggable Architecture** - Custom evaluators, scoring, audit adapters
+- **Framework Agnostic** - Works with Rails, Sinatra, or standalone
+- **JSON Rule DSL** - Non-technical users can write rules
+- **Visual Rule Builder** - Web UI for rule management
 
-The DecisionAgent Web UI provides a visual interface for building and testing rules.
+### Production Features
+- **Real-time Monitoring** - Live dashboard with WebSocket updates
+- **Prometheus Export** - Industry-standard metrics format
+- **Intelligent Alerting** - Anomaly detection with customizable rules
+- **Grafana Integration** - Pre-built dashboards and alert rules
+- **Version Control** - Full rule version control and rollback
+- **Thread-Safe** - Safe for multi-threaded servers and background jobs
+- **High Performance** - 10,000+ decisions/second, ~0.1ms latency
 
-### Standalone Usage
+## Web UI - Visual Rule Builder
 
 Launch the visual rule builder:
 
@@ -71,246 +101,50 @@ decision_agent web
 
 Open [http://localhost:4567](http://localhost:4567) in your browser.
 
-### Mount in Rails
-
-Add to your `config/routes.rb`:
+### Integration
 
+**Rails:**
 ```ruby
 require 'decision_agent/web/server'
-
 Rails.application.routes.draw do
-  # Mount DecisionAgent Web UI
-  mount DecisionAgent::Web::Server, at: '/decision_agent'
-end
-```
-
-Then visit `http://localhost:3000/decision_agent` in your browser.
-
-**With Authentication:**
-
-```ruby
-authenticate :user, ->(user) { user.admin? } do
   mount DecisionAgent::Web::Server, at: '/decision_agent'
 end
 ```
 
-### Mount in Rack/Sinatra Apps
-
+**Rack/Sinatra:**
 ```ruby
-# config.ru
 require 'decision_agent/web/server'
-
 map '/decision_agent' do
   run DecisionAgent::Web::Server
 end
 ```
 
-<img width="1622" height="820" alt="Screenshot" src="https://github.com/user-attachments/assets/687e9ff6-669a-40f9-be27-085c614392d4" />
-
-See [Web UI Rails Integration Guide](wiki/WEB_UI_RAILS_INTEGRATION.md) for detailed setup instructions.
+See [Web UI Integration Guide](docs/WEB_UI_RAILS_INTEGRATION.md) for detailed setup.
 
 ## Monitoring & Analytics
 
 Real-time monitoring, metrics, and alerting for production environments.
 
-### Quick Start
-
 ```ruby
 require 'decision_agent/monitoring/metrics_collector'
 require 'decision_agent/monitoring/dashboard_server'
 
-# Initialize metrics collection
 collector = DecisionAgent::Monitoring::MetricsCollector.new(window_size: 3600)
-
-# Start real-time dashboard
 DecisionAgent::Monitoring::DashboardServer.start!(
   port: 4568,
   metrics_collector: collector
 )
-
-# Record decisions
-agent = DecisionAgent::Agent.new(evaluators: [evaluator])
-result = agent.decide(context: { amount: 1500 })
-collector.record_decision(result, context, duration_ms: 25.5)
 ```
 
 Open [http://localhost:4568](http://localhost:4568) for the monitoring dashboard.
 
-### Features
-
-- **Real-time Dashboard** - Live metrics with WebSocket updates
-- **Prometheus Export** - Industry-standard metrics format
-- **Intelligent Alerting** - Anomaly detection with customizable rules
-- **Grafana Integration** - Pre-built dashboards and alert rules
-- **Custom KPIs** - Track business-specific metrics
-- **Thread-Safe** - Production-ready performance
-
-### Prometheus & Grafana
-
-```yaml
-# prometheus.yml
-scrape_configs:
-  - job_name: 'decision_agent'
-    static_configs:
-      - targets: ['localhost:4568']
-    metrics_path: '/metrics'
-```
-
-Import the pre-built Grafana dashboard from [grafana/decision_agent_dashboard.json](grafana/decision_agent_dashboard.json).
-
-### Alert Management
-
-```ruby
-alert_manager = DecisionAgent::Monitoring::AlertManager.new(
-  metrics_collector: collector
-)
+**Features:**
+- Real-time dashboard with WebSocket updates
+- Prometheus metrics export
+- Intelligent alerting with anomaly detection
+- Grafana integration with pre-built dashboards
 
-# Add alert rules
-alert_manager.add_rule(
-  name: 'High Error Rate',
-  condition: AlertManager.high_error_rate(threshold: 0.1),
-  severity: :critical
-)
-
-# Register alert handlers
-alert_manager.add_handler do |alert|
-  SlackNotifier.notify("🚨 #{alert[:message]}")
-end
-
-# Start monitoring
-alert_manager.start_monitoring(interval: 60)
-```
-
-See [Monitoring & Analytics Guide](wiki/MONITORING_AND_ANALYTICS.md) for complete documentation.
-
-
-## Key Features
-
-### Decision Making
-- **Multiple Evaluators** - Combine rule-based, ML, and custom logic
-- **Conflict Resolution** - Weighted average, consensus, threshold, max weight
-- **Rich Context** - Nested data, dot notation, flexible operators
-
-### Auditability
-- **Complete Audit Trails** - Every decision fully logged
-- **Deterministic Replay** - Reproduce historical decisions exactly
-- **Compliance Ready** - HIPAA, SOX, regulatory compliance support
-
-### Flexibility
-- **Pluggable Architecture** - Custom evaluators, scoring, audit adapters
-- **Framework Agnostic** - Works with Rails, Sinatra, or standalone
-- **JSON Rule DSL** - Non-technical users can write rules
-- **Visual Rule Builder** - Web UI for rule management
-
-### Monitoring & Observability
-- **Real-time Metrics** - Live dashboard with WebSocket updates (<1 second latency)
-- **Prometheus Export** - Industry-standard metrics format at `/metrics` endpoint
-- **Intelligent Alerting** - Anomaly detection with customizable rules and severity levels
-- **Grafana Integration** - Pre-built dashboards and alert configurations in `grafana/` directory
-- **Custom KPIs** - Track business-specific metrics with thread-safe operations
-- **MonitoredAgent** - Drop-in replacement that auto-records all metrics
-- **AlertManager** - Built-in anomaly detection (error rates, latency spikes, low confidence)
-
-### Production Ready
-- **Comprehensive Testing** - 90%+ code coverage
-- **Error Handling** - Clear, actionable error messages
-- **Versioning** - Full rule version control and rollback
-- **Performance** - Fast, zero external dependencies
-- **Thread-Safe** - Safe for multi-threaded servers and background jobs
-
-## Examples
-
-```ruby
-# Multiple evaluators with conflict resolution
-agent = DecisionAgent::Agent.new(
-  evaluators: [rule_evaluator, ml_evaluator],
-  scoring_strategy: DecisionAgent::Scoring::Consensus.new(minimum_agreement: 0.7),
-  audit_adapter: DecisionAgent::Audit::LoggerAdapter.new
-)
-
-# Complex rules with nested conditions
-rules = {
-  version: "1.0",
-  ruleset: "fraud_detection",
-  rules: [{
-    id: "suspicious_activity",
-    if: {
-      all: [
-        { field: "amount", op: "gt", value: 10000 },
-        { any: [
-          { field: "user.country", op: "in", value: ["XX", "YY"] },
-          { field: "velocity", op: "gt", value: 5 }
-        ]}
-      ]
-    },
-    then: { decision: "flag_for_review", weight: 0.95, reason: "Suspicious patterns detected" }
-  }]
-}
-```
-
-See [examples/](examples/) for complete working examples.
-
-## Thread-Safety Guarantees
-
-DecisionAgent is designed to be **thread-safe and FAST** for use in multi-threaded environments:
-
-### Performance
-- **10,000+ decisions/second** throughput
-- **~0.1ms average latency** per decision
-- **Zero performance overhead** from thread-safety
-- **Linear scalability** with thread count
-
-### Safe Concurrent Usage
-- **Agent instances** can be shared across threads safely
-- **Evaluators** are immutable after initialization
-- **Decisions and Evaluations** are deeply frozen
-- **File storage** uses mutex-protected operations
-
-### Best Practices
-```ruby
-# Safe: Reuse agent instance across threads
-agent = DecisionAgent::Agent.new(evaluators: [evaluator])
-
-Thread.new { agent.decide(context: { user_id: 1 }) }
-Thread.new { agent.decide(context: { user_id: 2 }) }
-
-# Safe: Share evaluators across agent instances
-evaluator = DecisionAgent::Evaluators::JsonRuleEvaluator.new(rules_json: rules)
-agent1 = DecisionAgent::Agent.new(evaluators: [evaluator])
-agent2 = DecisionAgent::Agent.new(evaluators: [evaluator])
-```
-
-### What's Frozen
-All data structures are deeply frozen to prevent mutation:
-- Decision objects (decision, confidence, explanations, evaluations)
-- Evaluation objects (decision, weight, reason, metadata)
-- Context data
-- Rule definitions in evaluators
-
-This ensures safe concurrent access without race conditions.
-
-### RFC 8785 Canonical JSON
-DecisionAgent uses **RFC 8785 (JSON Canonicalization Scheme)** for deterministic audit hashing:
-
-- **Industry Standard** - Official IETF specification for canonical JSON
-- **Cryptographically Sound** - Ensures deterministic hashing of decision payloads
-- **Reproducible** - Same decision always produces same audit hash
-- **Interoperable** - Compatible with other systems using RFC 8785
-
-Every decision includes a deterministic SHA-256 hash in the audit payload, enabling:
-- Tamper detection in audit logs
-- Exact replay verification
-- Regulatory compliance documentation
-
-Learn more: [RFC 8785 Specification](https://datatracker.ietf.org/doc/html/rfc8785)
-
-### Performance Benchmark
-Run the included benchmark to verify zero overhead:
-```bash
-ruby examples/thread_safe_performance.rb
-```
-
-See [THREAD_SAFETY.md](wiki/THREAD_SAFETY.md) for detailed implementation guide and [PERFORMANCE_AND_THREAD_SAFETY.md](wiki/PERFORMANCE_AND_THREAD_SAFETY.md) for detailed performance analysis.
+See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complete documentation.
 
 ## When to Use DecisionAgent
 
@@ -328,31 +162,48 @@ See [THREAD_SAFETY.md](wiki/THREAD_SAFETY.md) for detailed implementation guide
 
 ## Documentation
 
-**Getting Started**
+### Getting Started
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Examples](examples/README.md)
-
-**Core Features**
-- [Versioning System](wiki/VERSIONING.md) - Version control for rules
-- [Web UI](wiki/WEB_UI.md) - Visual rule builder
-- [Web UI Setup](wiki/WEB_UI_SETUP.md) - Setup guide
-- [Web UI Rails Integration](wiki/WEB_UI_RAILS_INTEGRATION.md) - Mount in Rails/Rack apps
-- [Monitoring & Analytics](wiki/MONITORING_AND_ANALYTICS.md) - Real-time monitoring, metrics, and alerting
-- [Monitoring Architecture](wiki/MONITORING_ARCHITECTURE.md) - System architecture and design
-
-**Performance & Thread-Safety**
-- [Performance & Thread-Safety Summary](wiki/PERFORMANCE_AND_THREAD_SAFETY.md) - Benchmarks and production readiness
-- [Thread-Safety Implementation](wiki/THREAD_SAFETY.md) - Technical implementation guide
-
-**Reference**
-- [API Contract](wiki/API_CONTRACT.md) - Full API reference
-- [Changelog](wiki/CHANGELOG.md) - Version history
-
-**More Resources**
-- [Wiki Home](wiki/README.md) - Documentation index
+- [Code Examples](docs/CODE_EXAMPLES.md) - Comprehensive code snippets
+- [Examples Directory](examples/README.md) - Working examples with explanations
+
+### Core Features
+- [Advanced Operators](docs/ADVANCED_OPERATORS.md) - String, numeric, date/time, collection, and geospatial operators
+- [Versioning System](docs/VERSIONING.md) - Version control for rules
+- [A/B Testing](docs/AB_TESTING.md) - Compare rule versions with statistical analysis
+- [Web UI](docs/WEB_UI.md) - Visual rule builder
+- [Web UI Setup](docs/WEB_UI_SETUP.md) - Setup guide
+- [Web UI Rails Integration](docs/WEB_UI_RAILS_INTEGRATION.md) - Mount in Rails/Rack apps
+- [Monitoring & Analytics](docs/MONITORING_AND_ANALYTICS.md) - Real-time monitoring, metrics, and alerting
+- [Monitoring Architecture](docs/MONITORING_ARCHITECTURE.md) - System architecture and design
+
+### Performance & Thread-Safety
+- [Performance & Thread-Safety Summary](docs/PERFORMANCE_AND_THREAD_SAFETY.md) - Benchmarks and production readiness
+- [Thread-Safety Implementation](docs/THREAD_SAFETY.md) - Technical implementation guide
+
+### Reference
+- [API Contract](docs/API_CONTRACT.md) - Full API reference
+- [Changelog](docs/CHANGELOG.md) - Version history
+- [Code Coverage Report](coverage.md) - Test coverage statistics
+
+### More Resources
+- [Documentation Home](docs/README.md) - Documentation index
 - [GitHub Issues](https://github.com/samaswin87/decision_agent/issues) - Report bugs or request features
 
+## Thread-Safety & Performance
+
+DecisionAgent is designed to be **thread-safe and FAST** for use in multi-threaded environments:
+
+- **10,000+ decisions/second** throughput
+- **~0.1ms average latency** per decision
+- **Zero performance overhead** from thread-safety
+- **Linear scalability** with thread count
+
+All data structures are deeply frozen to prevent mutation, ensuring safe concurrent access without race conditions.
+
+See [Thread-Safety Guide](docs/THREAD_SAFETY.md) and [Performance Analysis](docs/PERFORMANCE_AND_THREAD_SAFETY.md) for details.
+
 ## Contributing
 
 1. Fork the repository
@@ -363,8 +214,8 @@ See [THREAD_SAFETY.md](wiki/THREAD_SAFETY.md) for detailed implementation guide
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/samaswin87/decision_agent/issues)
-- **Documentation**: [Wiki](wiki/README.md)
-- **Examples**: [examples/](examples/)
+- **Documentation**: [Documentation](docs/README.md)
+- **Examples**: [Examples Directory](examples/README.md)
 
 ## License
 

data/lib/decision_agent/ab_testing/ab_testing_agent.rb

@@ -10,18 +10,23 @@ module DecisionAgent
       # @param evaluators [Array] Base evaluators (can be overridden by versioned rules)
       # @param scoring_strategy [Scoring::Base] Scoring strategy
       # @param audit_adapter [Audit::Adapter] Audit adapter
+      # @param cache_agents [Boolean] Whether to cache agents by version_id (default: true)
       def initialize(
         ab_test_manager:,
         version_manager: nil,
         evaluators: [],
         scoring_strategy: nil,
-        audit_adapter: nil
+        audit_adapter: nil,
+        cache_agents: true
       )
         @ab_test_manager = ab_test_manager
         @version_manager = version_manager || ab_test_manager.version_manager
         @base_evaluators = evaluators
         @scoring_strategy = scoring_strategy
         @audit_adapter = audit_adapter
+        @cache_agents = cache_agents
+        @agent_cache = {} # Cache agents by version_id
+        @agent_cache_mutex = Mutex.new
       end
 
       # Make a decision with A/B testing support
@@ -64,21 +69,29 @@ module DecisionAgent
         @ab_test_manager.active_tests
       end
 
+      # Clear the agent cache (useful for testing or when versions are updated)
+      def clear_agent_cache!
+        @agent_cache_mutex.synchronize { @agent_cache.clear }
+      end
+
+      # Get cache statistics
+      def cache_stats
+        @agent_cache_mutex.synchronize do
+          {
+            cached_agents: @agent_cache.size,
+            version_ids: @agent_cache.keys
+          }
+        end
+      end
+
       private
 
       def decide_with_ab_test(context, feedback, ab_test_id, user_id)
         # Assign variant
         assignment = @ab_test_manager.assign_variant(test_id: ab_test_id, user_id: user_id)
 
-        # Get the version for the assigned variant
-        version = @version_manager.get_version(version_id: assignment[:version_id])
-        raise VersionNotFoundError, "Version not found: #{assignment[:version_id]}" unless version
-
-        # Build evaluators from the versioned rule content
-        evaluators = build_evaluators_from_version(version)
-
-        # Create agent with version-specific evaluators
-        agent = build_agent(evaluators)
+        # Get or build cached agent for this version
+        agent = get_or_build_agent_for_version(assignment[:version_id])
 
         # Make decision
         decision = agent.decide(context: context, feedback: feedback)
@@ -105,6 +118,29 @@ module DecisionAgent
         }
       end
 
+      # Get or build agent for a specific version (with caching)
+      def get_or_build_agent_for_version(version_id)
+        return build_agent_for_version(version_id) unless @cache_agents
+
+        # Check cache first (fast path without lock for reads)
+        cached = @agent_cache[version_id]
+        return cached if cached
+
+        # Cache miss - acquire lock and build
+        @agent_cache_mutex.synchronize do
+          # Double-check after acquiring lock (another thread may have built it)
+          @agent_cache[version_id] ||= build_agent_for_version(version_id)
+        end
+      end
+
+      def build_agent_for_version(version_id)
+        version = @version_manager.get_version(version_id: version_id)
+        raise VersionNotFoundError, "Version not found: #{version_id}" unless version
+
+        evaluators = build_evaluators_from_version(version)
+        build_agent(evaluators)
+      end
+
       def build_agent(evaluators)
         Agent.new(
           evaluators: evaluators.empty? ? @base_evaluators : evaluators,

data/lib/decision_agent/agent.rb

@@ -6,10 +6,12 @@ module DecisionAgent
   class Agent
     attr_reader :evaluators, :scoring_strategy, :audit_adapter
 
-    def initialize(evaluators:, scoring_strategy: nil, audit_adapter: nil)
+    def initialize(evaluators:, scoring_strategy: nil, audit_adapter: nil, validate_evaluations: nil)
       @evaluators = Array(evaluators)
       @scoring_strategy = scoring_strategy || Scoring::WeightedAverage.new
       @audit_adapter = audit_adapter || Audit::NullAdapter.new
+      # Default to validating in development, skip in production for performance
+      @validate_evaluations = validate_evaluations.nil? ? (ENV["RAILS_ENV"] != "production") : validate_evaluations
 
       validate_configuration!
 
@@ -24,8 +26,8 @@ module DecisionAgent
 
       raise NoEvaluationsError if evaluations.empty?
 
-      # Validate all evaluations for correctness and thread-safety
-      EvaluationValidator.validate_all!(evaluations)
+      # Validate all evaluations for correctness and thread-safety (optional for performance)
+      EvaluationValidator.validate_all!(evaluations) if @validate_evaluations
 
       scored_result = @scoring_strategy.score(evaluations)
 

data/lib/decision_agent/auth/access_audit_logger.rb

@@ -0,0 +1,122 @@
+require "json"
+require_relative "../audit/adapter"
+
+module DecisionAgent
+  module Auth
+    class AccessAuditLogger
+      attr_reader :adapter
+
+      def initialize(adapter: nil)
+        @adapter = adapter || Audit::InMemoryAccessAdapter.new
+      end
+
+      def log_authentication(event_type, user_id:, email: nil, success: true, reason: nil)
+        log_entry = {
+          event_type: event_type.to_s,
+          user_id: user_id,
+          email: email,
+          success: success,
+          reason: reason,
+          timestamp: Time.now.utc.iso8601,
+          ip_address: nil # Can be set by middleware
+        }
+
+        @adapter.record_access(log_entry)
+      end
+
+      def log_permission_check(user_id:, permission:, resource_type: nil, resource_id: nil, granted: true)
+        log_entry = {
+          event_type: "permission_check",
+          user_id: user_id,
+          permission: permission.to_s,
+          resource_type: resource_type,
+          resource_id: resource_id,
+          granted: granted,
+          timestamp: Time.now.utc.iso8601
+        }
+
+        @adapter.record_access(log_entry)
+      end
+
+      def log_access(user_id:, action:, resource_type: nil, resource_id: nil, success: true)
+        log_entry = {
+          event_type: "access",
+          user_id: user_id,
+          action: action.to_s,
+          resource_type: resource_type,
+          resource_id: resource_id,
+          success: success,
+          timestamp: Time.now.utc.iso8601
+        }
+
+        @adapter.record_access(log_entry)
+      end
+
+      def query(filters = {})
+        @adapter.query_access_logs(filters)
+      end
+    end
+  end
+
+  module Audit
+    class AccessAdapter < Adapter
+      def record_access(log_entry)
+        raise NotImplementedError, "Subclasses must implement #record_access"
+      end
+
+      def query_access_logs(filters = {})
+        raise NotImplementedError, "Subclasses must implement #query_access_logs"
+      end
+    end
+
+    class InMemoryAccessAdapter < AccessAdapter
+      def initialize
+        super
+        @logs = []
+        @mutex = Mutex.new
+      end
+
+      def record_access(log_entry)
+        @mutex.synchronize do
+          @logs << log_entry.dup
+        end
+      end
+
+      def query_access_logs(filters = {})
+        @mutex.synchronize do
+          results = @logs.dup
+
+          results.select! { |log| log[:user_id] == filters[:user_id] } if filters[:user_id]
+
+          results.select! { |log| log[:event_type] == filters[:event_type].to_s } if filters[:event_type]
+
+          if filters[:start_time]
+            start_time = filters[:start_time].is_a?(String) ? Time.parse(filters[:start_time]) : filters[:start_time]
+            results.select! { |log| Time.parse(log[:timestamp]) >= start_time }
+          end
+
+          if filters[:end_time]
+            end_time = filters[:end_time].is_a?(String) ? Time.parse(filters[:end_time]) : filters[:end_time]
+            results.select! { |log| Time.parse(log[:timestamp]) <= end_time }
+          end
+
+          results = results.last(filters[:limit]) if filters[:limit]
+
+          results.reverse # Most recent first
+        end
+      end
+
+      def all_logs
+        @mutex.synchronize do
+          @logs.dup
+        end
+      end
+
+      def clear
+        @mutex.synchronize do
+          @logs.clear
+        end
+      end
+    end
+  end
+end