decision_agent 0.3.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '095f5b6604126a4288548c648efbfb3f88cc94bf2a51ba84b21f422286c9c0f3'
-  data.tar.gz: 0f5475b14f32d3f7524ba63d21152bda4d088312dc1b154a6c15dd73f8e038e0
+  metadata.gz: a016bb964d8daeb5676d84ba597f07af9e7b4816a8f075d3ca9feb6f1ddd2f44
+  data.tar.gz: ccc960d23a5c863b8e9be429b08188f32abe630d83e2008a3e70534401779d92
 SHA512:
-  metadata.gz: 60f10c33779fac9cf26ed698a704b91e4ff65ca200d76870fa593a9074506b10a7791a471ab5cbb0fcdc9603145dc965131508619f0f1356f163cdaf069f49c9
-  data.tar.gz: d60e5eaf6d7350a55047594481c00360fa188e66db11e84cf863c7c734d1210c777e7fb358a689470d84256dd225b22376deb50648443dd0257a5041816086c1
+  metadata.gz: 4f84301ecb298b3fdc3d39b2ca02e850345d2df13eb0c8834555f1b3f08241f243dee54fd044dfd0a37bd2fa32e690dca7583c69049af68d0e951572ca222ad0
+  data.tar.gz: a52598d8c6358ea03ed16a3fd23d68fbea1ef9619f1c4dec613359427a11e9290cd6f4b9f8816fb6673d436b59bdd23b986f816a23ecac185eae1e27b86e6dee

data/README.md

@@ -14,8 +14,8 @@ A production-grade, deterministic, explainable, and auditable decision engine fo
 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
+- ✅ **Explainable** - Every decision includes human-readable reasoning and machine-readable condition traces
+- ✅ **Auditable** - Reproduce any historical decision exactly with complete explainability
 - ✅ **Framework-agnostic** - Pure Ruby, works anywhere
 - ✅ **Production-ready** - Comprehensive testing ([Coverage Report](coverage.md)), error handling, and versioning
 
@@ -55,9 +55,12 @@ agent = DecisionAgent::Agent.new(evaluators: [evaluator])
 # Make decision
 result = agent.decide(context: { amount: 1500 })
 
-puts result.decision      # => "approve"
-puts result.confidence    # => 0.9
-puts result.explanations  # => ["High value transaction"]
+puts result.decision           # => "approve"
+puts result.confidence         # => 0.9
+puts result.explanations       # => ["High value transaction"]
+puts result.because            # => ["amount > 1000"]
+puts result.failed_conditions  # => []
+puts result.explainability     # => { decision: "approve", because: [...], failed_conditions: [] }
 ```
 
 See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
@@ -69,26 +72,52 @@ See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
 - **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
+- **REST API Data Enrichment** - Fetch external data during decision-making with caching and circuit breaker
 
 ### Auditability & Compliance
 - **Complete Audit Trails** - Every decision fully logged
+- **Explainability Layer** - Machine-readable condition traces for every decision
+  - `result.because` - Conditions that led to the decision
+  - `result.failed_conditions` - Conditions that failed
+  - `result.explainability` - Complete machine-readable explainability data
 - **Deterministic Replay** - Reproduce historical decisions exactly
 - **RFC 8785 Canonical JSON** - Industry-standard deterministic hashing
 - **Compliance Ready** - HIPAA, SOX, regulatory compliance support
 
+### Testing & Simulation
+- **Simulation & What-If Analysis** - Test rule changes before deployment
+  - **Historical Replay / Backtesting** - Replay past decisions with new rules (CSV, JSON, database import)
+  - **What-If Analysis** - Simulate scenarios and sensitivity analysis with decision boundary visualization
+  - **Impact Analysis** - Quantify rule change effects (decision distribution, confidence shifts, performance impact)
+  - **Shadow Testing** - Compare new rules against production without affecting outcomes
+  - **Monte Carlo Simulation** - Model probabilistic inputs and understand decision outcome probabilities
+- **Batch Testing** - Test rules against large datasets with CSV/Excel import, coverage analysis, and resume capability
+- **A/B Testing** - Champion/Challenger testing with statistical significance analysis
+
+### Security & Access Control
+- **Role-Based Access Control (RBAC)** - Enterprise-grade authentication and authorization
+  - Built-in user/role system with bcrypt password hashing
+  - Configurable adapters for Devise, CanCanCan, Pundit, or custom auth systems
+  - 5 default roles (Admin, Editor, Viewer, Auditor, Approver) with 7 permissions
+  - Password reset functionality with secure token management
+  - Comprehensive access audit logging for compliance
+  - Web UI integration with login and user management pages
+
 ### 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
 - **DMN 1.3 Support** - Industry-standard Decision Model and Notation with full FEEL expression language
 - **Visual Rule Builder** - Web UI for rule management and DMN modeler
+- **CLI Tools** - Command-line interface for DMN import/export and web server
 
 ### Production Features
 - **Real-time Monitoring** - Live dashboard with WebSocket updates
+- **Persistent Monitoring** - Database storage for long-term analytics (PostgreSQL, MySQL, SQLite)
 - **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
+- **Version Control** - Full rule version control, rollback, and history ([Versioning Guide](docs/VERSIONING.md))
 - **Thread-Safe** - Safe for multi-threaded servers and background jobs
 - **High Performance** - 10,000+ decisions/second, ~0.1ms latency
 
@@ -156,6 +185,57 @@ result = agent.decide(context: { amount: 50000, credit_score: 750 })
 
 See [DMN Guide](docs/DMN_GUIDE.md) for complete documentation and [DMN Examples](examples/dmn/README.md) for working examples.
 
+## REST API Data Enrichment
+
+DecisionAgent supports fetching external data during decision-making without manual context assembly:
+
+```ruby
+require 'decision_agent'
+
+# Configure data enrichment endpoints
+DecisionAgent.configure_data_enrichment do |config|
+  config.add_endpoint(:credit_bureau,
+    url: "https://api.creditbureau.com/v1/score",
+    method: :post,
+    auth: { type: :api_key, header: "X-API-Key" },
+    cache: { ttl: 3600, adapter: :memory }
+  )
+end
+
+# Use in rules with fetch_from_api operator
+rules = {
+  version: "1.0",
+  ruleset: "loan_approval",
+  rules: [{
+    id: "check_credit",
+    if: {
+      field: "credit_score",
+      op: "fetch_from_api",
+      value: {
+        endpoint: "credit_bureau",
+        params: { ssn: "{{customer.ssn}}" },
+        mapping: { score: "credit_score" }
+      }
+    },
+    then: { decision: "approve", weight: 0.8 }
+  }]
+}
+
+evaluator = DecisionAgent::Evaluators::JsonRuleEvaluator.new(rules_json: rules)
+agent = DecisionAgent::Agent.new(evaluators: [evaluator])
+result = agent.decide(context: { customer: { ssn: "123-45-6789" } })
+```
+
+**Features:**
+- **HTTP Client** - Support for GET, POST, PUT, DELETE methods
+- **Response Caching** - Configurable TTL per endpoint with memory adapter
+- **Circuit Breaker** - Fail-fast after N failures to prevent cascading failures
+- **Authentication** - API key, Basic Auth, and Bearer token support
+- **Template Parameters** - Use `{{path}}` syntax to reference context values
+- **Error Handling** - Graceful degradation with cached data fallback
+
+See [Data Enrichment Guide](docs/DATA_ENRICHMENT.md) for complete documentation and [Data Enrichment Example](examples/data_enrichment_example.rb) for working examples.
+
 ## Monitoring & Analytics
 
 Real-time monitoring, metrics, and alerting for production environments.
@@ -175,11 +255,155 @@ Open [http://localhost:4568](http://localhost:4568) for the monitoring dashboard
 
 **Features:**
 - Real-time dashboard with WebSocket updates
+- **Persistent Storage** - Database storage for long-term analytics (PostgreSQL, MySQL, SQLite)
 - Prometheus metrics export
 - Intelligent alerting with anomaly detection
 - Grafana integration with pre-built dashboards
 
-See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complete documentation.
+See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) and [Persistent Monitoring Guide](docs/PERSISTENT_MONITORING.md) for complete documentation.
+
+## Simulation & What-If Analysis
+
+DecisionAgent provides comprehensive simulation capabilities to test rule changes before deployment:
+
+```ruby
+require 'decision_agent/simulation/replay_engine'
+
+# Replay historical decisions with new rules
+replay_engine = DecisionAgent::Simulation::ReplayEngine.new(
+  agent: agent,
+  version_manager: version_manager
+)
+
+results = replay_engine.replay(historical_data: "decisions.csv")
+
+# What-if analysis
+whatif = DecisionAgent::Simulation::WhatIfAnalyzer.new(agent: agent)
+analysis = whatif.analyze(
+  base_context: { credit_score: 700, amount: 50000 },
+  scenarios: [
+    { credit_score: 750 },
+    { credit_score: 650 }
+  ]
+)
+
+# Impact analysis
+impact = DecisionAgent::Simulation::ImpactAnalyzer.new
+comparison = impact.compare(
+  baseline: baseline_evaluator,
+  proposed: proposed_evaluator,
+  contexts: test_contexts
+)
+```
+
+**Features:**
+- **Historical Replay** - Replay past decisions with CSV/JSON/database import
+- **What-If Analysis** - Scenario simulation with decision boundary visualization
+- **Impact Analysis** - Quantify rule change effects (decisions, confidence, performance)
+- **Shadow Testing** - Test new rules in production without affecting outcomes
+- **Monte Carlo Simulation** - Probabilistic decision modeling
+- **Web UI** - Complete simulation dashboard at `/simulation`
+
+See [Simulation Guide](docs/SIMULATION.md) for complete documentation and [Simulation Example](examples/simulation_example.rb) for working examples.
+
+## Role-Based Access Control (RBAC)
+
+Enterprise-grade authentication and authorization system:
+
+```ruby
+require 'decision_agent'
+
+# Configure RBAC (works with any auth system)
+DecisionAgent.configure_rbac(:devise_cancan, ability_class: Ability)
+
+# Or use built-in RBAC
+authenticator = DecisionAgent::Auth::Authenticator.new
+admin = authenticator.create_user(
+  email: "admin@example.com",
+  password: "secure_password",
+  roles: [:admin]
+)
+
+session = authenticator.login("admin@example.com", "secure_password")
+
+# Permission checks
+checker = DecisionAgent.permission_checker
+checker.can?(admin, :write)  # => true
+checker.can?(admin, :approve)  # => true
+```
+
+**Features:**
+- **Built-in User System** - User management with bcrypt password hashing
+- **5 Default Roles** - Admin, Editor, Viewer, Auditor, Approver
+- **Configurable Adapters** - Devise, CanCanCan, Pundit, or custom
+- **Password Reset** - Secure token-based password reset
+- **Access Audit Logging** - Comprehensive audit trail for compliance
+- **Web UI Integration** - Login page and user management interface
+
+See [RBAC Configuration Guide](docs/RBAC_CONFIGURATION.md) for complete documentation and [RBAC Examples](examples/rbac_configuration_examples.rb) for integration examples.
+
+## Batch Testing
+
+Test rules against large datasets with comprehensive analysis:
+
+```ruby
+require 'decision_agent/testing/batch_test_runner'
+
+runner = DecisionAgent::Testing::BatchTestRunner.new(agent: agent)
+
+# Import from CSV or Excel
+importer = DecisionAgent::Testing::BatchTestImporter.new
+scenarios = importer.import_csv("test_data.csv", {
+  context_fields: ["credit_score", "amount"],
+  expected_fields: ["expected_decision"]
+})
+
+# Run batch test
+results = runner.run(scenarios: scenarios)
+
+puts "Total: #{results[:total]}"
+puts "Passed: #{results[:passed]}"
+puts "Failed: #{results[:failed]}"
+puts "Coverage: #{results[:coverage]}"
+```
+
+**Features:**
+- **CSV/Excel Import** - Import test scenarios from files
+- **Database Import** - Load test data from databases
+- **Coverage Analysis** - Identify untested rule combinations
+- **Resume Capability** - Continue interrupted tests from checkpoint
+- **Progress Tracking** - Real-time progress updates for large imports
+- **Web UI** - Complete batch testing interface with file upload
+
+See [Batch Testing Guide](docs/BATCH_TESTING.md) for complete documentation.
+
+## A/B Testing
+
+Compare rule versions with statistical analysis:
+
+```ruby
+require 'decision_agent/testing/ab_test_manager'
+
+ab_manager = DecisionAgent::Testing::AbTestManager.new(version_manager: version_manager)
+
+test = ab_manager.create_test(
+  name: "loan_approval_v2",
+  champion_version: champion_version_id,
+  challenger_version: challenger_version_id,
+  traffic_split: 0.5
+)
+
+results = ab_manager.run_test(test_id: test.id, contexts: test_contexts)
+ab_manager.analyze_results(test_id: test.id)
+```
+
+**Features:**
+- **Champion/Challenger Testing** - Compare baseline vs proposed rules
+- **Statistical Significance** - P-value calculation and confidence intervals
+- **Traffic Splitting** - Configurable split ratios
+- **Decision Distribution Comparison** - Visualize differences in outcomes
+
+See [A/B Testing Guide](docs/AB_TESTING.md) for complete documentation.
 
 ## When to Use DecisionAgent
 
@@ -204,23 +428,31 @@ See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complet
 - [Examples Directory](examples/README.md) - Working examples with explanations
 
 ### Core Features
+- [Explainability Layer](docs/EXPLAINABILITY.md) - Machine-readable decision explanations with condition-level tracing
 - [Advanced Operators](docs/ADVANCED_OPERATORS.md) - String, numeric, date/time, collection, and geospatial operators
+- [Data Enrichment](docs/DATA_ENRICHMENT.md) - REST API data enrichment with caching and circuit breaker
 - [DMN Guide](docs/DMN_GUIDE.md) - Complete DMN 1.3 support guide
 - [DMN API Reference](docs/DMN_API.md) - DMN API documentation
 - [FEEL Reference](docs/FEEL_REFERENCE.md) - FEEL expression language reference
 - [DMN Migration Guide](docs/DMN_MIGRATION_GUIDE.md) - Migrating from JSON to DMN
 - [DMN Best Practices](docs/DMN_BEST_PRACTICES.md) - DMN modeling best practices
 - [Versioning System](docs/VERSIONING.md) - Version control for rules
+- [Simulation & What-If Analysis](docs/SIMULATION.md) - Historical replay, what-if analysis, impact analysis, and shadow testing
 - [A/B Testing](docs/AB_TESTING.md) - Compare rule versions with statistical analysis
+- [Batch Testing](docs/BATCH_TESTING.md) - Test rules against large datasets with CSV/Excel import
+- [RBAC Configuration](docs/RBAC_CONFIGURATION.md) - Role-based access control setup and integration
+- [RBAC Quick Reference](docs/RBAC_QUICK_REFERENCE.md) - Quick reference for RBAC configuration
 - [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
+- [Persistent Monitoring](docs/PERSISTENT_MONITORING.md) - Database storage for long-term analytics
 
 ### 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
+- [Benchmarks](benchmarks/README.md) - Comprehensive benchmark suite and performance testing
 
 ### Reference
 - [API Contract](docs/API_CONTRACT.md) - Full API reference
@@ -244,6 +476,39 @@ All data structures are deeply frozen to prevent mutation, ensuring safe concurr
 
 See [Thread-Safety Guide](docs/THREAD_SAFETY.md) and [Performance Analysis](docs/PERFORMANCE_AND_THREAD_SAFETY.md) for details.
 
+**Run Benchmarks:**
+```bash
+# Run all benchmarks
+rake benchmark:all
+
+# Run specific benchmarks
+rake benchmark:basic      # Basic decision performance
+rake benchmark:threads    # Thread-safety and scalability
+rake benchmark:regression # Compare against baseline
+
+# See [Benchmarks Guide](benchmarks/README.md) for complete documentation
+```
+
+### Latest Benchmark Results
+
+**Last Updated:** 2026-01-06T04:03:29Z
+
+#### Performance Comparison
+
+| Metric | Latest (2026-01-06) | Previous (2026-01-06) | Change |
+|--------|--------------------------------------------------|------------------------------------------------------|--------|
+| Basic Throughput | 8966.04 decisions/sec | 9751.42 decisions/sec | ↓ 8.05% (degraded) |
+| Basic Latency | 0.1115 ms | 0.1025 ms | ↑ 8.78% (degraded) |
+| Multi-threaded (50 threads) Throughput | 8560.69 decisions/sec | 8849.86 decisions/sec | ↓ 3.27% (degraded) |
+| Multi-threaded (50 threads) Latency | 0.1168 ms | 0.113 ms | ↑ 3.36% (degraded) |
+
+**Environment:**
+- Ruby Version: 3.3.5
+- Hardware: x86_64
+- OS: Darwin
+- Git Commit: `aba46af5`
+
+> 💡 **Note:** Run `rake benchmark:regression` to generate new benchmark results. This section is automatically updated with the last 2 benchmark runs.
 ## Contributing
 
 1. Fork the repository

data/lib/decision_agent/agent.rb

@@ -6,6 +6,17 @@ module DecisionAgent
   class Agent
     attr_reader :evaluators, :scoring_strategy, :audit_adapter
 
+    # Thread-safe cache for deterministic hash computation
+    # This significantly improves performance when the same context/evaluations
+    # are processed multiple times (common in benchmarks and high-throughput scenarios)
+    @hash_cache = {}
+    @hash_cache_mutex = Mutex.new
+    @hash_cache_max_size = 1000 # Limit cache size to prevent memory bloat
+
+    class << self
+      attr_reader :hash_cache, :hash_cache_mutex, :hash_cache_max_size
+    end
+
     def initialize(evaluators:, scoring_strategy: nil, audit_adapter: nil, validate_evaluations: nil)
       @evaluators = Array(evaluators)
       @scoring_strategy = scoring_strategy || Scoring::WeightedAverage.new
@@ -129,8 +140,68 @@ module DecisionAgent
 
     def compute_deterministic_hash(payload)
       hashable = payload.slice(:context, :evaluations, :decision, :confidence, :scoring_strategy)
+
+      # Use fast hash (MD5) as cache key to avoid expensive canonicalization on cache hits
+      # Optimized: Use direct JSON.to_json instead of recursive sorting for speed
+      # The cache key doesn't need perfect determinism, just good enough to catch duplicates
+      # This avoids the expensive sort_hash_keys recursion on every call
+      json_str = hashable.to_json
+      fast_key = Digest::MD5.hexdigest(json_str)
+
+      # Fast path: check cache without lock first (unsafe read, but acceptable for cache)
+      # This allows concurrent reads without mutex overhead
+      cache = self.class.hash_cache
+      cached_hash = cache[fast_key]
+      return cached_hash if cached_hash
+
+      # Cache miss - compute canonical JSON (required for deterministic hashing)
+      # This is expensive, but only happens on cache misses
       canonical = canonical_json(hashable)
-      Digest::SHA256.hexdigest(canonical)
+
+      # Compute SHA256 hash (also expensive, but only on cache misses)
+      computed_hash = Digest::SHA256.hexdigest(canonical)
+
+      # Store in cache (thread-safe, with size limit)
+      # Only lock when we need to write
+      self.class.hash_cache_mutex.synchronize do
+        # Double-check after acquiring lock (another thread may have added it)
+        return self.class.hash_cache[fast_key] if self.class.hash_cache[fast_key]
+
+        # Clear cache if it gets too large (simple FIFO eviction)
+        if self.class.hash_cache.size >= self.class.hash_cache_max_size
+          # Remove oldest 10% of entries (simple approximation)
+          keys_to_remove = self.class.hash_cache.keys.first(self.class.hash_cache_max_size / 10)
+          keys_to_remove.each { |key| self.class.hash_cache.delete(key) }
+        end
+        self.class.hash_cache[fast_key] = computed_hash
+      end
+
+      computed_hash
+    end
+
+    # Fast hash key generation using MD5 (much faster than canonical JSON + SHA256)
+    # Used as cache key to avoid expensive canonicalization on cache hits
+    # MD5 is sufficient for cache keys (collision resistance not critical, speed is)
+    def fast_hash_key(hashable)
+      # Create a deterministic string representation for hashing
+      # Use sorted JSON to ensure determinism (though not RFC 8785 canonical)
+      json_str = sort_hash_keys(hashable).to_json
+      Digest::MD5.hexdigest(json_str)
+    end
+
+    # Recursively sort hash keys for deterministic hashing
+    # This is faster than canonical JSON but still deterministic
+    # Note: This is still used by canonical_json indirectly, but fast_hash_key avoids it
+    def sort_hash_keys(obj)
+      case obj
+      when Hash
+        sorted = obj.sort.to_h
+        sorted.transform_values { |v| sort_hash_keys(v) }
+      when Array
+        obj.map { |v| sort_hash_keys(v) }
+      else
+        obj
+      end
     end
 
     # Uses RFC 8785 (JSON Canonicalization Scheme) for deterministic JSON serialization

data/lib/decision_agent/context.rb

@@ -4,6 +4,7 @@ module DecisionAgent
 
     def initialize(data)
       # Create a deep copy before freezing to avoid mutating the original
+      # This is necessary for thread-safety even if it adds some overhead
       data_hash = data.is_a?(Hash) ? data : {}
       @data = deep_freeze(deep_dup(data_hash))
     end

data/lib/decision_agent/data_enrichment/cache/memory_adapter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../cache_adapter"
+require "monitor"
+
+module DecisionAgent
+  module DataEnrichment
+    module Cache
+      # In-memory cache adapter (default, no dependencies)
+      class MemoryAdapter < CacheAdapter
+        include MonitorMixin
+
+        def initialize
+          super
+          @cache = {}
+        end
+
+        # Get cached value
+        #
+        # @param key [String] Cache key
+        # @return [Hash, nil] Cached data or nil if not found/expired
+        def get(key)
+          synchronize do
+            entry = @cache[key]
+            return nil unless entry
+
+            # Check if expired
+            if entry[:expires_at] < Time.now
+              @cache.delete(key)
+              return nil
+            end
+
+            entry[:value]
+          end
+        end
+
+        # Set cached value
+        #
+        # @param key [String] Cache key
+        # @param value [Hash] Data to cache
+        # @param ttl [Integer] Time to live in seconds
+        def set(key, value, ttl)
+          synchronize do
+            @cache[key] = {
+              value: value,
+              expires_at: Time.now + ttl
+            }
+          end
+        end
+
+        # Delete cached value
+        #
+        # @param key [String] Cache key
+        def delete(key)
+          synchronize do
+            @cache.delete(key)
+          end
+        end
+
+        # Clear all cached values
+        def clear
+          synchronize do
+            @cache.clear
+          end
+        end
+
+        # Get cache statistics
+        #
+        # @return [Hash] Cache statistics
+        def stats
+          synchronize do
+            now = Time.now
+            valid_entries = @cache.count { |_k, v| v[:expires_at] >= now }
+            expired_entries = @cache.size - valid_entries
+
+            {
+              size: @cache.size,
+              valid: valid_entries,
+              expired: expired_entries
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decision_agent/data_enrichment/cache_adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module DecisionAgent
+  module DataEnrichment
+    # Base class for cache adapters
+    class CacheAdapter
+      # Get cached value
+      #
+      # @param key [String] Cache key
+      # @return [Hash, nil] Cached data or nil if not found/expired
+      def get(key)
+        raise NotImplementedError, "#{self.class} must implement #get"
+      end
+
+      # Set cached value
+      #
+      # @param key [String] Cache key
+      # @param value [Hash] Data to cache
+      # @param ttl [Integer] Time to live in seconds
+      def set(key, value, ttl)
+        raise NotImplementedError, "#{self.class} must implement #set"
+      end
+
+      # Delete cached value
+      #
+      # @param key [String] Cache key
+      def delete(key)
+        raise NotImplementedError, "#{self.class} must implement #delete"
+      end
+
+      # Clear all cached values
+      def clear
+        raise NotImplementedError, "#{self.class} must implement #clear"
+      end
+
+      # Generate cache key from request parameters
+      #
+      # @param endpoint_name [Symbol] Endpoint identifier
+      # @param params [Hash] Request parameters
+      # @return [String] Cache key
+      def cache_key(endpoint_name, params)
+        # Sort params for consistent key generation
+        sorted_params = params.sort.to_h
+        param_string = sorted_params.map { |k, v| "#{k}=#{v}" }.join("&")
+        "#{endpoint_name}:#{Digest::SHA256.hexdigest(param_string)}"
+      end
+    end
+  end
+end