mathpix 0.1.0

data/lib/mathpix/mcp/elicitations/base_elicitation.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Mathpix
+  module MCP
+    module Elicitations
+      # Base class for all MCP elicitations
+      #
+      # Implements MCP elicitation protocol for interactive client prompts
+      # Uses seed 1069 for deterministic ID generation
+      #
+      # @example Text elicitation
+      #   elicitation = TextElicitation.new(
+      #     prompt: "Enter your API key",
+      #     field_name: "api_key"
+      #   )
+      #   response = elicitation.request
+      #
+      class BaseElicitation
+        # Seed 1069 for deterministic behavior
+        SEED_1069 = 1069
+
+        # Balanced ternary basis [1, 1, 0, -1, 1, 1, 1]
+        TERNARY_BASIS = [1, 1, 0, -1, 1, 1, 1].freeze
+
+        attr_reader :id, :type, :prompt, :field_name, :optional, :default_value
+
+        # Initialize elicitation
+        #
+        # @param type [String] elicitation type (text, password, select, etc)
+        # @param prompt [String] prompt text to display
+        # @param field_name [String] field name for response
+        # @param optional [Boolean] whether field is optional
+        # @param default_value [Object] default value if any
+        # @param seed [Integer] random seed for deterministic IDs (default 1069)
+        def initialize(type:, prompt:, field_name:, optional: false, default_value: nil, seed: SEED_1069)
+          @type = type
+          @prompt = prompt
+          @field_name = field_name
+          @optional = optional
+          @default_value = default_value
+          @seed = seed
+          @id = generate_id
+          @response = nil
+          @validated = false
+        end
+
+        # Generate elicitation request payload
+        #
+        # @return [Hash] MCP elicitation request
+        def to_request
+          {
+            id: @id,
+            type: @type,
+            prompt: @prompt,
+            field_name: @field_name,
+            optional: @optional
+          }.tap do |req|
+            req[:default] = @default_value if @default_value
+            req.merge!(type_specific_fields)
+          end
+        end
+
+        # Set response value
+        #
+        # @param value [Object] response value
+        # @return [Boolean] whether response is valid
+        def set_response(value)
+          @response = value
+          @validated = validate_response(value)
+        end
+
+        # Get response value
+        #
+        # @return [Object] response value
+        # @raise [RuntimeError] if no response set
+        def response
+          raise "No response set for elicitation #{@id}" unless @response
+          @response
+        end
+
+        # Check if elicitation has valid response
+        #
+        # @return [Boolean]
+        def responded?
+          !@response.nil? && @validated
+        end
+
+        # Validate response (override in subclasses)
+        #
+        # @param value [Object] response value
+        # @return [Boolean] whether response is valid
+        def validate_response(value)
+          # Base validation: optional fields can be nil
+          return true if @optional && value.nil?
+          # Non-optional fields must have value
+          !value.nil?
+        end
+
+        # Store in CoBlackboard context
+        #
+        # @param coblackboard [Object] CoBlackboard instance
+        def store_in_context(coblackboard)
+          coblackboard.record_elicitation(
+            id: @id,
+            type: @type,
+            prompt: @prompt,
+            response: @response,
+            timestamp: Time.now
+          )
+        end
+
+        protected
+
+        # Generate deterministic ID using seed 1069
+        #
+        # Uses balanced ternary basis for coordinate mapping
+        #
+        # @return [String] unique elicitation ID
+        def generate_id
+          # Use seed 1069 for deterministic generation
+          rng = Random.new(@seed + field_name.hash)
+
+          # Generate ID with ternary coordinate
+          ternary_coord = TERNARY_BASIS.sample(3, random: rng)
+          coord_str = ternary_coord.map { |t| t == -1 ? 'n' : t.to_s }.join
+
+          "elicit_#{@field_name}_#{coord_str}_#{rng.rand(1000..9999)}"
+        end
+
+        # Type-specific fields (override in subclasses)
+        #
+        # @return [Hash] additional fields for request
+        def type_specific_fields
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/elicitations/confidence_elicitation.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Elicitations
+      # Confidence elicitation for Mathpix OCR results
+      #
+      # Prompts user when OCR confidence falls below threshold
+      # Offers options: continue, adjust threshold, review ambiguous parts
+      #
+      # @example Low confidence handling
+      #   elicitation = ConfidenceElicitation.new(
+      #     confidence: 0.65,
+      #     threshold: 0.70,
+      #     latex: "\\int_{0}^{\\infty} e^{-x} dx",
+      #     image_path: "formula.png"
+      #   )
+      #   response = elicitation.request_user_decision
+      #
+      class ConfidenceElicitation
+        attr_reader :confidence, :threshold, :latex, :image_path, :decision
+
+        # Initialize confidence elicitation
+        #
+        # @param confidence [Float] OCR confidence (0.0-1.0)
+        # @param threshold [Float] minimum acceptable confidence
+        # @param latex [String] OCR result (LaTeX)
+        # @param image_path [String] path to source image
+        def initialize(confidence:, threshold:, latex:, image_path:)
+          @confidence = confidence
+          @threshold = threshold
+          @latex = latex
+          @image_path = image_path
+          @decision = nil
+        end
+
+        # Check if elicitation should be triggered
+        #
+        # @return [Boolean] true if confidence below threshold
+        def should_elicit?
+          @confidence < @threshold
+        end
+
+        # Generate elicitation prompt
+        #
+        # @return [String] user-facing prompt
+        def prompt
+          percentage = (@confidence * 100).round(1)
+          threshold_pct = (@threshold * 100).round(0)
+
+          <<~PROMPT
+            ⚠️  Low OCR Confidence Detected
+
+            Confidence: #{percentage}% (threshold: #{threshold_pct}%)
+            Image: #{File.basename(@image_path)}
+
+            OCR Result:
+            #{@latex}
+
+            What would you like to do?
+          PROMPT
+        end
+
+        # Generate options for user
+        #
+        # @return [Array<Hash>] option choices
+        def options
+          [
+            {
+              value: 'accept',
+              label: 'Accept result (use as-is)',
+              description: 'Continue with current OCR output despite low confidence'
+            },
+            {
+              value: 'adjust_threshold',
+              label: 'Adjust confidence threshold',
+              description: 'Lower threshold to accept similar confidence in future'
+            },
+            {
+              value: 'review_ambiguous',
+              label: 'Review ambiguous parts',
+              description: 'Show detailed breakdown of low-confidence regions'
+            },
+            {
+              value: 'retry',
+              label: 'Retry OCR',
+              description: 'Re-process image (may improve confidence)'
+            },
+            {
+              value: 'reject',
+              label: 'Reject result',
+              description: 'Discard this OCR result'
+            }
+          ]
+        end
+
+        # Set user decision
+        #
+        # @param decision [String] user's choice (accept, adjust_threshold, etc)
+        def set_decision(decision)
+          valid_options = options.map { |o| o[:value] }
+          unless valid_options.include?(decision)
+            raise ArgumentError, "Invalid decision: #{decision}. Must be one of: #{valid_options.join(', ')}"
+          end
+          @decision = decision
+        end
+
+        # Execute user's decision
+        #
+        # @return [Hash] action result
+        def execute_decision
+          case @decision
+          when 'accept'
+            { action: :accept, result: @latex }
+          when 'adjust_threshold'
+            { action: :adjust_threshold, new_threshold: @confidence - 0.05 }
+          when 'review_ambiguous'
+            { action: :review, data: identify_ambiguous_regions }
+          when 'retry'
+            { action: :retry, image_path: @image_path }
+          when 'reject'
+            { action: :reject, reason: 'Low confidence' }
+          else
+            raise "No decision set"
+          end
+        end
+
+        # Convert to MCP elicitation request
+        #
+        # @return [Hash] MCP-compatible request
+        def to_mcp_request
+          {
+            type: 'select',
+            prompt: prompt,
+            field_name: 'confidence_decision',
+            options: options.map { |o| { value: o[:value], label: o[:label] } },
+            metadata: {
+              confidence: @confidence,
+              threshold: @threshold,
+              image_path: @image_path,
+              result_preview: @latex[0..100]
+            }
+          }
+        end
+
+        private
+
+        # Identify regions with low confidence (placeholder)
+        #
+        # In real implementation, would use word_data/line_data from Mathpix API
+        #
+        # @return [Array<Hash>] ambiguous regions
+        def identify_ambiguous_regions
+          # Placeholder: In reality would analyze word_data from Mathpix response
+          [
+            { text: @latex, confidence: @confidence, note: 'Full result has low confidence' }
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/elicitations.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Load Mathpix-specific elicitations
+require_relative 'elicitations/confidence_elicitation'
+require_relative 'elicitations/ambiguity_elicitation'
+
+module Mathpix
+  module MCP
+    # Mathpix MCP Elicitations
+    #
+    # Interactive prompts for OCR quality assurance:
+    # - ConfidenceElicitation: prompt when OCR confidence < threshold
+    # - AmbiguityElicitation: clarify ambiguous mathematical symbols
+    #
+    # @example Confidence checking
+    #   if result.confidence < 0.70
+    #     elicitation = Elicitations::ConfidenceElicitation.new(
+    #       confidence: result.confidence,
+    #       threshold: 0.70,
+    #       latex: result.latex,
+    #       image_path: image_path
+    #     )
+    #
+    #     if elicitation.should_elicit?
+    #       mcp_request = elicitation.to_mcp_request
+    #       # Send to MCP client for user decision
+    #     end
+    #   end
+    #
+    module Elicitations
+      # Check if result requires confidence elicitation
+      #
+      # @param result [Mathpix::Result] OCR result
+      # @param threshold [Float] minimum confidence (default 0.70)
+      # @param image_path [String] source image path
+      # @return [ConfidenceElicitation, nil] elicitation if needed
+      def self.check_confidence(result, threshold: 0.70, image_path:)
+        return nil if result.confidence >= threshold
+
+        ConfidenceElicitation.new(
+          confidence: result.confidence,
+          threshold: threshold,
+          latex: result.latex || result.text,
+          image_path: image_path
+        )
+      end
+
+      # Detect ambiguous notation in result
+      #
+      # @param result [Mathpix::Result] OCR result
+      # @return [Array<AmbiguityElicitation>] ambiguities found
+      def self.detect_ambiguities(result)
+        latex = result.latex || result.text
+        ambiguities = []
+
+        # Check for O/0 ambiguity
+        if latex =~ /[O0]/ && result.confidence < 0.90
+          ambiguities << AmbiguityElicitation.new(
+            ambiguous_text: latex[/[O0]/],
+            context: latex,
+            alternatives: ['0 (zero)', 'O (letter O)']
+          )
+        end
+
+        # Check for 1/l/I ambiguity
+        if latex =~ /[1lI]/ && result.confidence < 0.90
+          ambiguities << AmbiguityElicitation.new(
+            ambiguous_text: latex[/[1lI]/],
+            context: latex,
+            alternatives: ['1 (one)', 'l (lowercase L)', 'I (uppercase i)']
+          )
+        end
+
+        ambiguities
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/middleware/cors_middleware.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Middleware
+      # Rack middleware for handling CORS (Cross-Origin Resource Sharing)
+      class CorsMiddleware
+        def initialize(app, options = {})
+          @app = app
+          @allowed_origins = options[:allowed_origins] || ['*']
+          @allowed_methods = options[:allowed_methods] || %w[GET POST PUT DELETE OPTIONS]
+          @allowed_headers = options[:allowed_headers] || %w[Authorization Content-Type Accept]
+          @expose_headers = options[:expose_headers] || []
+          @max_age = options[:max_age] || 3600
+          @expose_credentials = options[:expose_credentials] || false
+        end
+
+        def call(env)
+          origin = env['HTTP_ORIGIN']
+
+          # Handle preflight OPTIONS request
+          if env['REQUEST_METHOD'] == 'OPTIONS'
+            return preflight_response(origin)
+          end
+
+          # Call app and add CORS headers
+          status, headers, body = @app.call(env)
+
+          # For wildcard '*', always add CORS headers even without Origin
+          # For specific origins, only add when Origin header is present and allowed
+          if @allowed_origins.include?('*') || (origin && origin_allowed?(origin))
+            add_cors_headers(headers, origin)
+          end
+
+          [status, headers, body]
+        end
+
+        private
+
+        def preflight_response(origin)
+          headers = {}
+
+          # Always add CORS headers for OPTIONS (preflight) requests
+          # This allows browsers to discover CORS policy even without Origin header
+          if @allowed_origins.include?('*')
+            headers['Access-Control-Allow-Origin'] = '*'
+          elsif origin && origin_allowed?(origin)
+            headers['Access-Control-Allow-Origin'] = origin
+            headers['Access-Control-Allow-Credentials'] = 'true' if @expose_credentials
+          end
+
+          # Always add these headers for preflight
+          headers['Access-Control-Allow-Methods'] = @allowed_methods.join(', ')
+          headers['Access-Control-Allow-Headers'] = @allowed_headers.join(', ')
+          headers['Access-Control-Max-Age'] = @max_age.to_s
+
+          [200, headers, []]
+        end
+
+        def add_cors_headers(headers, origin)
+          if @allowed_origins.include?('*')
+            headers['Access-Control-Allow-Origin'] = '*'
+            # Cannot use credentials with wildcard origin
+          else
+            headers['Access-Control-Allow-Origin'] = origin
+            headers['Access-Control-Allow-Credentials'] = 'true' if @expose_credentials
+          end
+
+          headers['Access-Control-Expose-Headers'] = @expose_headers.join(', ') unless @expose_headers.empty?
+
+          # Add Vary header for caching
+          vary = headers['Vary']
+          headers['Vary'] = vary ? "#{vary}, Origin" : 'Origin'
+        end
+
+        def origin_allowed?(origin)
+          return false if origin.nil?
+
+          @allowed_origins.include?('*') ||
+            @allowed_origins.include?(origin) ||
+            @allowed_origins.any? { |pattern| wildcard_match?(pattern, origin) }
+        end
+
+        def wildcard_match?(pattern, origin)
+          return false unless pattern.include?('*')
+
+          regex_pattern = Regexp.escape(pattern).gsub('\*', '.*')
+          regex = Regexp.new("^#{regex_pattern}$")
+          regex.match?(origin)
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/middleware/oauth_middleware.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Middleware
+      # Rack middleware for OAuth 2.0 authentication
+      class OAuthMiddleware
+        def initialize(app, options = {})
+          @app = app
+          @oauth_provider = options[:oauth_provider]
+        end
+
+        def call(env)
+          # Skip auth for OAuth endpoints and health checks
+          path = env['PATH_INFO']
+          return @app.call(env) if public_path?(path)
+
+          # Extract and validate token
+          token = extract_token(env)
+
+          if token.nil?
+            return unauthorized_response('missing_token')
+          end
+
+          begin
+            payload = @oauth_provider.validate_token(token)
+            env['oauth.user_id'] = payload['user_id']
+            env['oauth.client_id'] = payload['client_id']
+            env['oauth.scope'] = payload['scope']
+
+            @app.call(env)
+          rescue Mathpix::MCP::Auth::InvalidTokenError => e
+            unauthorized_response('invalid_token', e.message)
+          end
+        end
+
+        private
+
+        def extract_token(env)
+          # Try Bearer token
+          auth_header = env['HTTP_AUTHORIZATION']
+          if auth_header&.start_with?('Bearer ')
+            return auth_header.sub('Bearer ', '')
+          end
+
+          # Try X-API-Key header
+          env['HTTP_X_API_KEY']
+        end
+
+        def public_path?(path)
+          path.start_with?('/oauth/') ||
+            path == '/health' ||
+            path == '/mcp/info'
+        end
+
+        def unauthorized_response(error, description = nil)
+          headers = {
+            'Content-Type' => 'application/json',
+            'WWW-Authenticate' => 'Bearer realm="MCP Server"'
+          }
+
+          body = {
+            error: error,
+            error_description: description
+          }.compact
+
+          [401, headers, [JSON.generate(body)]]
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/middleware/rate_limiting_middleware.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Mathpix
+  module MCP
+    module Middleware
+      # Rate limiting middleware using token bucket algorithm
+      class RateLimitingMiddleware
+        DEFAULT_LIMIT = 60  # requests per minute
+        DEFAULT_WINDOW = 60 # seconds
+
+        # Class-level storage shared across all instances (Rack may create many instances)
+        @@buckets = {}
+        @@buckets_mutex = Mutex.new
+
+        # Reset class-level state for testing (prevents test interference)
+        def self.reset_for_testing!
+          @@buckets_mutex.synchronize do
+            @@buckets.clear
+          end
+        end
+
+        def initialize(app, limit: DEFAULT_LIMIT, window: DEFAULT_WINDOW)
+          @app = app
+          @limit = limit
+          @window = window
+          @cleanup_thread = start_cleanup_thread unless ENV['RACK_ENV'] == 'test'
+
+          $stderr.puts "[RATE LIMIT] Middleware initialized: object_id=#{object_id}" if ENV['RACK_ENV'] == 'test'
+        end
+
+        def call(env)
+          # Exempt /health endpoint from rate limiting (monitoring endpoint)
+          request_path = env['PATH_INFO'] || env['REQUEST_PATH']
+          if request_path == '/health'
+            return @app.call(env)
+          end
+
+          client_id = extract_client_id(env)
+
+          # Check if rate limited FIRST (before incrementing)
+          if rate_limited?(client_id)
+            retry_after = time_until_reset(client_id)
+            bucket = @@buckets[client_id]
+            $stderr.puts "[RATE LIMIT] LIMITING client #{client_id}, Count: #{bucket[:count]}/#{@limit}" if ENV['RACK_ENV'] == 'test'
+            return rate_limit_response(retry_after)
+          end
+
+          # Record request (atomically increments counter)
+          record_request(client_id)
+
+          # Debug: show count AFTER incrementing
+          if ENV['RACK_ENV'] == 'test'
+            bucket = @@buckets[client_id]
+            $stderr.puts "[RATE LIMIT] Client: #{client_id}, Count: #{bucket[:count]}/#{@limit}"
+          end
+
+          @app.call(env)
+        end
+
+        private
+
+        def extract_client_id(env)
+          # Try multiple sources for client identification
+          env['HTTP_X_FORWARDED_FOR']&.split(',')&.first&.strip ||
+            env['REMOTE_ADDR'] ||
+            'unknown'
+        end
+
+        def rate_limited?(client_id)
+          bucket = @@buckets[client_id]
+          return false unless bucket  # Not rate limited if no bucket yet
+          bucket[:count] >= @limit
+        end
+
+        def record_request(client_id)
+          @@buckets_mutex.synchronize do
+            # Initialize bucket if it doesn't exist
+            @@buckets[client_id] ||= { count: 0, reset_at: Time.now + @window }
+
+            # Get current bucket and increment
+            bucket = @@buckets[client_id]
+            old_count = bucket[:count]
+            bucket[:count] += 1
+            $stderr.puts "[RATE LIMIT] record_request: #{old_count} -> #{bucket[:count]}" if ENV['RACK_ENV'] == 'test'
+          end
+        end
+
+        def time_until_reset(client_id)
+          bucket = @@buckets[client_id]
+          return @window unless bucket
+
+          (bucket[:reset_at] - Time.now).ceil.clamp(0, @window)
+        end
+
+        def rate_limit_response(retry_after)
+          [
+            429,
+            {
+              'Content-Type' => 'application/json',
+              'Retry-After' => retry_after.to_s,
+              'X-RateLimit-Limit' => @limit.to_s,
+              'X-RateLimit-Reset' => (Time.now + retry_after).to_i.to_s
+            },
+            [JSON.generate({
+              error: 'rate_limit_exceeded',
+              message: 'Too many requests',
+              retry_after: retry_after
+            })]
+          ]
+        end
+
+        def start_cleanup_thread
+          Thread.new do
+            loop do
+              sleep @window
+              cleanup_expired_buckets
+            end
+          rescue StandardError => e
+            # Log error but don't crash
+            warn "Rate limit cleanup error: #{e.message}"
+            retry
+          end
+        end
+
+        def cleanup_expired_buckets
+          now = Time.now
+          @buckets.each_pair do |client_id, bucket|
+            if bucket[:reset_at] <= now
+              # Reset the bucket instead of deleting
+              bucket[:count] = 0
+              bucket[:reset_at] = now + @window
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/middleware.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Middleware
+      # Middleware will be autoloaded
+    end
+  end
+end
+
+require_relative 'middleware/cors_middleware'
+require_relative 'middleware/oauth_middleware'
+require_relative 'middleware/rate_limiting_middleware'