aidp 0.17.1 → 0.18.0

data/lib/aidp/harness/ai_decision_engine.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "provider_factory"
+require_relative "thinking_depth_manager"
+
+module Aidp
+  module Harness
+    # Zero Framework Cognition (ZFC) Decision Engine
+    #
+    # Delegates semantic analysis and decision-making to AI models instead of
+    # using brittle pattern matching, scoring formulas, or heuristic thresholds.
+    #
+    # @example Basic usage
+    #   engine = AIDecisionEngine.new(config, provider_manager)
+    #   result = engine.decide(:condition_detection,
+    #     context: { error: "Rate limit exceeded" },
+    #     schema: ConditionSchema,
+    #     tier: "mini"
+    #   )
+    #   # => { condition: "rate_limit", confidence: 0.95, reasoning: "..." }
+    #
+    # @see docs/ZFC_COMPLIANCE_ASSESSMENT.md
+    # @see docs/ZFC_IMPLEMENTATION_PLAN.md
+    class AIDecisionEngine
+      # Decision templates define prompts, schemas, and defaults for each decision type
+      DECISION_TEMPLATES = {
+        condition_detection: {
+          prompt_template: <<~PROMPT,
+            Analyze the following API response or error message and classify the condition.
+
+            Response/Error:
+            {{response}}
+
+            Classify this into one of the following conditions:
+            - rate_limit: API rate limiting or quota exceeded
+            - auth_error: Authentication or authorization failure
+            - timeout: Request timeout or network timeout
+            - completion_marker: Work is complete or done
+            - user_feedback_needed: AI is asking for user input/clarification
+            - api_error: General API error (not rate limit/auth)
+            - success: Successful response
+            - other: None of the above
+
+            Provide your classification with a confidence score (0.0 to 1.0) and brief reasoning.
+          PROMPT
+          schema: {
+            type: "object",
+            properties: {
+              condition: {
+                type: "string",
+                enum: [
+                  "rate_limit",
+                  "auth_error",
+                  "timeout",
+                  "completion_marker",
+                  "user_feedback_needed",
+                  "api_error",
+                  "success",
+                  "other"
+                ]
+              },
+              confidence: {
+                type: "number",
+                minimum: 0.0,
+                maximum: 1.0
+              },
+              reasoning: {
+                type: "string"
+              }
+            },
+            required: ["condition", "confidence"]
+          },
+          default_tier: "mini",
+          cache_ttl: nil  # Each response is unique
+        },
+
+        error_classification: {
+          prompt_template: <<~PROMPT,
+            Classify the following error and determine if it's retryable.
+
+            Error:
+            {{error_message}}
+
+            Context:
+            {{context}}
+
+            Determine:
+            1. Error type (rate_limit, auth, timeout, network, api_bug, other)
+            2. Whether it's retryable (transient vs permanent)
+            3. Recommended action (retry, switch_provider, escalate, fail)
+
+            Provide classification with confidence and reasoning.
+          PROMPT
+          schema: {
+            type: "object",
+            properties: {
+              error_type: {
+                type: "string",
+                enum: ["rate_limit", "auth", "timeout", "network", "api_bug", "other"]
+              },
+              retryable: {
+                type: "boolean"
+              },
+              recommended_action: {
+                type: "string",
+                enum: ["retry", "switch_provider", "escalate", "fail"]
+              },
+              confidence: {
+                type: "number",
+                minimum: 0.0,
+                maximum: 1.0
+              },
+              reasoning: {
+                type: "string"
+              }
+            },
+            required: ["error_type", "retryable", "recommended_action", "confidence"]
+          },
+          default_tier: "mini",
+          cache_ttl: nil
+        },
+
+        completion_detection: {
+          prompt_template: <<~PROMPT,
+            Determine if the work described is complete based on the AI response.
+
+            Task:
+            {{task_description}}
+
+            AI Response:
+            {{response}}
+
+            Is the work complete? Consider:
+            - Explicit completion markers ("done", "finished", etc.)
+            - Implicit indicators (results provided, no follow-up questions)
+            - Requests for more information (incomplete)
+
+            Provide boolean completion status with confidence and reasoning.
+          PROMPT
+          schema: {
+            type: "object",
+            properties: {
+              complete: {
+                type: "boolean"
+              },
+              confidence: {
+                type: "number",
+                minimum: 0.0,
+                maximum: 1.0
+              },
+              reasoning: {
+                type: "string"
+              }
+            },
+            required: ["complete", "confidence"]
+          },
+          default_tier: "mini",
+          cache_ttl: nil
+        }
+      }.freeze
+
+      attr_reader :config, :provider_factory, :cache
+
+      # Initialize the AI Decision Engine
+      #
+      # @param config [Configuration] AIDP configuration object
+      # @param provider_factory [ProviderFactory] Factory for creating provider instances
+      def initialize(config, provider_factory: nil)
+        @config = config
+        @provider_factory = provider_factory || ProviderFactory.new(config)
+        @cache = {}
+        @cache_timestamps = {}
+      end
+
+      # Make an AI-powered decision
+      #
+      # @param decision_type [Symbol] Type of decision (:condition_detection, :error_classification, etc.)
+      # @param context [Hash] Context data for the decision
+      # @param schema [Hash, nil] JSON schema for response validation (overrides default)
+      # @param tier [String, nil] Thinking depth tier (overrides default)
+      # @param cache_ttl [Integer, nil] Cache TTL in seconds (overrides default)
+      # @return [Hash] Validated decision result
+      # @raise [ArgumentError] If decision_type is unknown
+      # @raise [ValidationError] If response doesn't match schema
+      def decide(decision_type, context:, schema: nil, tier: nil, cache_ttl: nil)
+        template = DECISION_TEMPLATES[decision_type]
+        raise ArgumentError, "Unknown decision type: #{decision_type}" unless template
+
+        # Check cache if TTL specified
+        cache_key = build_cache_key(decision_type, context)
+        ttl = cache_ttl || template[:cache_ttl]
+        if ttl && (cached_result = get_cached(cache_key, ttl))
+          Aidp.log_debug("ai_decision_engine", "Cache hit for #{decision_type}", {
+            cache_key: cache_key,
+            ttl: ttl
+          })
+          return cached_result
+        end
+
+        # Build prompt from template
+        prompt = build_prompt(template[:prompt_template], context)
+
+        # Select tier
+        selected_tier = tier || template[:default_tier]
+
+        # Get model for tier
+        thinking_manager = ThinkingDepthManager.new(config)
+        provider_name, model_name, _model_data = thinking_manager.select_model_for_tier(selected_tier)
+
+        Aidp.log_debug("ai_decision_engine", "Making AI decision", {
+          decision_type: decision_type,
+          tier: selected_tier,
+          provider: provider_name,
+          model: model_name,
+          cache_ttl: ttl
+        })
+
+        # Call AI with schema validation
+        response_schema = schema || template[:schema]
+        result = call_ai_with_schema(provider_name, model_name, prompt, response_schema)
+
+        # Validate result
+        validate_schema(result, response_schema)
+
+        # Cache if TTL specified
+        if ttl
+          set_cached(cache_key, result)
+        end
+
+        result
+      end
+
+      private
+
+      # Build cache key from decision type and context
+      def build_cache_key(decision_type, context)
+        # Simple hash-based key
+        "#{decision_type}:#{context.hash}"
+      end
+
+      # Get cached result if still valid
+      def get_cached(key, ttl)
+        return nil unless @cache.key?(key)
+        return nil if Time.now - @cache_timestamps[key] > ttl
+        @cache[key]
+      end
+
+      # Store result in cache
+      def set_cached(key, value)
+        @cache[key] = value
+        @cache_timestamps[key] = Time.now
+      end
+
+      # Build prompt from template with context substitution
+      def build_prompt(template, context)
+        prompt = template.dup
+        context.each do |key, value|
+          prompt.gsub!("{{#{key}}}", value.to_s)
+        end
+        prompt
+      end
+
+      # Call AI with schema validation using structured output
+      def call_ai_with_schema(provider_name, model_name, prompt, schema)
+        # Create provider instance
+        provider_options = {
+          model: model_name,
+          output: nil,  # No output for background decisions
+          prompt: nil   # No TTY prompt needed
+        }
+
+        provider = @provider_factory.create_provider(provider_name, provider_options)
+
+        # Build enhanced prompt requesting JSON output
+        enhanced_prompt = <<~PROMPT
+          #{prompt}
+
+          IMPORTANT: Respond with ONLY valid JSON. No additional text or explanation.
+          The JSON must match this structure: #{JSON.generate(schema[:properties].keys)}
+        PROMPT
+
+        # Call provider
+        response = provider.send_message(prompt: enhanced_prompt, session: nil)
+
+        # Parse JSON response
+        begin
+          # Response might be a string or already structured
+          response_text = response.is_a?(String) ? response : response.to_s
+
+          # Try to extract JSON if there's extra text
+          # Use non-greedy match and handle nested braces
+          json_match = response_text.match(/\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/m) || response_text.match(/\{.*\}/m)
+          json_text = json_match ? json_match[0] : response_text
+
+          result = JSON.parse(json_text, symbolize_names: true)
+
+          Aidp.log_debug("ai_decision_engine", "Parsed JSON successfully", {
+            response_length: response_text.length,
+            json_length: json_text.length,
+            result_keys: result.keys,
+            provider: provider_name
+          })
+
+          result
+        rescue JSON::ParserError => e
+          Aidp.log_error("ai_decision_engine", "Failed to parse AI response as JSON", {
+            error: e.message,
+            response: response_text&.slice(0, 200),
+            provider: provider_name,
+            model: model_name
+          })
+          raise ValidationError, "AI response is not valid JSON: #{e.message}"
+        end
+      rescue => e
+        Aidp.log_error("ai_decision_engine", "Error calling AI provider", {
+          error: e.message,
+          provider: provider_name,
+          model: model_name,
+          error_class: e.class.name
+        })
+        raise
+      end
+
+      # Validate response against JSON schema
+      def validate_schema(result, schema)
+        # Basic validation of required fields and types
+        # Schema uses string keys, but our result uses symbol keys from JSON parsing
+        schema[:required]&.each do |field|
+          field_sym = field.to_sym
+          unless result.key?(field_sym)
+            raise ValidationError, "Missing required field: #{field}"
+          end
+        end
+
+        schema[:properties]&.each do |field, constraints|
+          field_sym = field.to_sym
+          next unless result.key?(field_sym)
+          value = result[field_sym]
+
+          # Type validation
+          case constraints[:type]
+          when "string"
+            unless value.is_a?(String)
+              raise ValidationError, "Field #{field} must be string, got #{value.class}"
+            end
+            # Enum validation
+            if constraints[:enum] && !constraints[:enum].include?(value)
+              raise ValidationError, "Field #{field} must be one of #{constraints[:enum]}, got #{value}"
+            end
+          when "number"
+            unless value.is_a?(Numeric)
+              raise ValidationError, "Field #{field} must be number, got #{value.class}"
+            end
+            # Range validation
+            if constraints[:minimum] && value < constraints[:minimum]
+              raise ValidationError, "Field #{field} must be >= #{constraints[:minimum]}"
+            end
+            if constraints[:maximum] && value > constraints[:maximum]
+              raise ValidationError, "Field #{field} must be <= #{constraints[:maximum]}"
+            end
+          when "boolean"
+            unless [true, false].include?(value)
+              raise ValidationError, "Field #{field} must be boolean, got #{value.class}"
+            end
+          end
+        end
+
+        true
+      end
+    end
+
+    # Validation error for schema violations
+    class ValidationError < StandardError; end
+  end
+end

data/lib/aidp/harness/capability_registry.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Aidp
+  module Harness
+    # Stores and queries model capability metadata from the catalog
+    # Provides information about model tiers, features, costs, and context windows
+    class CapabilityRegistry
+      # Valid thinking depth tiers
+      VALID_TIERS = %w[mini standard thinking pro max].freeze
+
+      # Tier priority for escalation (lower index = lower tier)
+      TIER_PRIORITY = {
+        "mini" => 0,
+        "standard" => 1,
+        "thinking" => 2,
+        "pro" => 3,
+        "max" => 4
+      }.freeze
+
+      attr_reader :catalog_path
+
+      def initialize(catalog_path: nil, root_dir: nil)
+        @root_dir = root_dir || Dir.pwd
+        @catalog_path = catalog_path || default_catalog_path
+        @catalog_data = nil
+        @loaded_at = nil
+      end
+
+      # Load catalog from YAML file
+      def load_catalog
+        return false unless File.exist?(@catalog_path)
+
+        @catalog_data = YAML.safe_load_file(
+          @catalog_path,
+          permitted_classes: [Symbol],
+          symbolize_names: false
+        )
+        @loaded_at = Time.now
+
+        validate_catalog(@catalog_data)
+        Aidp.log_debug("capability_registry", "Loaded catalog", path: @catalog_path, providers: provider_names.size)
+        true
+      rescue => e
+        Aidp.log_error("capability_registry", "Failed to load catalog", error: e.message, path: @catalog_path)
+        @catalog_data = nil
+        false
+      end
+
+      # Get catalog data (lazy load if needed)
+      def catalog
+        load_catalog if @catalog_data.nil?
+        @catalog_data || default_empty_catalog
+      end
+
+      # Get all provider names in catalog
+      def provider_names
+        catalog.dig("providers")&.keys || []
+      end
+
+      # Get all models for a provider
+      def models_for_provider(provider_name)
+        provider_data = catalog.dig("providers", provider_name)
+        return {} unless provider_data
+
+        provider_data["models"] || {}
+      end
+
+      # Get tier for a specific model
+      def tier_for_model(provider_name, model_name)
+        model_data = model_info(provider_name, model_name)
+        return nil unless model_data
+
+        model_data["tier"]
+      end
+
+      # Get all models matching a specific tier
+      # Returns hash: { provider_name => [model_name, ...] }
+      def models_by_tier(tier, provider: nil)
+        validate_tier!(tier)
+
+        results = {}
+        providers_to_search = provider ? [provider] : provider_names
+
+        providers_to_search.each do |provider_name|
+          matching_models = []
+          models_for_provider(provider_name).each do |model_name, model_data|
+            matching_models << model_name if model_data["tier"] == tier
+          end
+          results[provider_name] = matching_models unless matching_models.empty?
+        end
+
+        results
+      end
+
+      # Get complete info for a specific model
+      def model_info(provider_name, model_name)
+        catalog.dig("providers", provider_name, "models", model_name)
+      end
+
+      # Get display name for a provider
+      def provider_display_name(provider_name)
+        catalog.dig("providers", provider_name, "display_name") || provider_name
+      end
+
+      # Get all tiers supported by a provider
+      def supported_tiers(provider_name)
+        models = models_for_provider(provider_name)
+        tiers = models.values.map { |m| m["tier"] }.compact.uniq
+        tiers.sort_by { |t| TIER_PRIORITY[t] || 999 }
+      end
+
+      # Check if a tier is valid
+      def valid_tier?(tier)
+        VALID_TIERS.include?(tier)
+      end
+
+      # Get tier priority (0 = lowest, 4 = highest)
+      def tier_priority(tier)
+        TIER_PRIORITY[tier]
+      end
+
+      # Compare two tiers (returns -1, 0, 1 like <=>)
+      def compare_tiers(tier1, tier2)
+        priority1 = tier_priority(tier1) || -1
+        priority2 = tier_priority(tier2) || -1
+        priority1 <=> priority2
+      end
+
+      # Get next higher tier (or nil if already at max)
+      def next_tier(tier)
+        validate_tier!(tier)
+        current_priority = tier_priority(tier)
+        return nil if current_priority >= TIER_PRIORITY["max"]
+
+        TIER_PRIORITY.key(current_priority + 1)
+      end
+
+      # Get next lower tier (or nil if already at mini)
+      def previous_tier(tier)
+        validate_tier!(tier)
+        current_priority = tier_priority(tier)
+        return nil if current_priority <= TIER_PRIORITY["mini"]
+
+        TIER_PRIORITY.key(current_priority - 1)
+      end
+
+      # Find best model for a tier and provider
+      # Returns [model_name, model_data] or nil
+      def best_model_for_tier(tier, provider_name)
+        validate_tier!(tier)
+        models = models_for_provider(provider_name)
+
+        # Find all models matching tier
+        tier_models = models.select { |_name, data| data["tier"] == tier }
+        return nil if tier_models.empty?
+
+        # Prefer newer models (higher in the list)
+        # Sort by cost (cheaper first) as tiebreaker
+        tier_models.min_by do |_name, data|
+          cost = data["cost_per_mtok_input"] || 0
+          [cost]
+        end
+      end
+
+      # Get tier recommendations from catalog
+      def tier_recommendations
+        catalog["tier_recommendations"] || {}
+      end
+
+      # Recommend tier based on complexity score (0.0-1.0)
+      def recommend_tier_for_complexity(complexity_score)
+        return "mini" if complexity_score <= 0.0
+
+        recommendations = tier_recommendations.sort_by do |_name, data|
+          data["complexity_threshold"] || 0.0
+        end
+
+        # Find first recommendation where complexity exceeds threshold
+        recommendation = recommendations.find do |_name, data|
+          complexity_score <= (data["complexity_threshold"] || 0.0)
+        end
+
+        recommendation ? recommendation[1]["recommended_tier"] : "max"
+      end
+
+      # Reload catalog from disk
+      def reload
+        @catalog_data = nil
+        @loaded_at = nil
+        load_catalog
+      end
+
+      # Check if catalog needs reload (based on file modification time)
+      def stale?(max_age_seconds = 3600)
+        return true unless @loaded_at
+        return true unless File.exist?(@catalog_path)
+
+        file_mtime = File.mtime(@catalog_path)
+        file_mtime > @loaded_at || (Time.now - @loaded_at) > max_age_seconds
+      end
+
+      # Export catalog as structured data for display
+      def export_for_display
+        {
+          schema_version: catalog["schema_version"],
+          providers: provider_names.map do |provider_name|
+            {
+              name: provider_name,
+              display_name: provider_display_name(provider_name),
+              tiers: supported_tiers(provider_name),
+              models: models_for_provider(provider_name)
+            }
+          end,
+          tier_order: VALID_TIERS
+        }
+      end
+
+      private
+
+      def default_catalog_path
+        File.join(@root_dir, ".aidp", "models_catalog.yml")
+      end
+
+      def default_empty_catalog
+        {
+          "schema_version" => "1.0",
+          "providers" => {},
+          "tier_order" => VALID_TIERS,
+          "tier_recommendations" => {}
+        }
+      end
+
+      def validate_catalog(data)
+        unless data.is_a?(Hash)
+          raise ArgumentError, "Catalog must be a hash"
+        end
+
+        unless data["providers"].is_a?(Hash)
+          raise ArgumentError, "Catalog must have 'providers' hash"
+        end
+
+        # Validate each provider has models
+        data["providers"].each do |provider_name, provider_data|
+          unless provider_data.is_a?(Hash) && provider_data["models"].is_a?(Hash)
+            raise ArgumentError, "Provider #{provider_name} must have 'models' hash"
+          end
+
+          # Validate each model has required fields
+          provider_data["models"].each do |model_name, model_data|
+            unless model_data["tier"]
+              raise ArgumentError, "Model #{provider_name}/#{model_name} missing 'tier'"
+            end
+
+            unless valid_tier?(model_data["tier"])
+              raise ArgumentError, "Model #{provider_name}/#{model_name} has invalid tier: #{model_data["tier"]}"
+            end
+          end
+        end
+
+        Aidp.log_debug("capability_registry", "Catalog validation passed", providers: data["providers"].size)
+      end
+
+      def validate_tier!(tier)
+        unless valid_tier?(tier)
+          raise ArgumentError, "Invalid tier: #{tier}. Must be one of: #{VALID_TIERS.join(", ")}"
+        end
+      end
+    end
+  end
+end