mathpix 0.1.0

data/lib/mathpix/mcp/transports/sse_stream_handler.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'json'
+require 'thread'  # For Queue
+
+module Mathpix
+  module MCP
+    module Transports
+      # Handles Server-Sent Events (SSE) streaming for MCP protocol
+      class SSEStreamHandler
+        attr_reader :mcp_server, :session_id
+        attr_accessor :stop_flag
+
+        HEARTBEAT_INTERVAL = 10 # seconds
+        TEST_HEARTBEAT_INTERVAL = 0.1 # 100ms for tests (fast disconnect detection)
+        TIMEOUT = 300 # 5 minutes
+        TEST_TIMEOUT = 30 # 30 seconds for tests
+        EVENT_LOOP_CHECK_INTERVAL = 0.05 # 50ms for production
+        TEST_EVENT_LOOP_CHECK_INTERVAL = 0.005 # 5ms for tests (fast stop flag response)
+
+        def initialize(mcp_server, env, test_mode: false, transport: nil)
+          @mcp_server = mcp_server
+          @transport = transport  # Transport for connection tracking
+          @session_id = extract_session_id(env)
+          @event_id = 0
+          @last_activity = Time.now
+          @heartbeat_thread = nil
+          @test_mode = test_mode
+          @stop_flag = false
+          @event_queue = Queue.new  # Thread-safe event queue
+        end
+
+        def handle
+          headers = {
+            'Content-Type' => 'text/event-stream',
+            'Cache-Control' => 'no-cache',
+            'Connection' => 'keep-alive',
+            'X-Accel-Buffering' => 'no' # Disable nginx buffering
+          }
+
+          stream = proc do |out|
+            @stream = out  # Store stream for external access
+            @closed = false
+            register_connection
+
+            begin
+              # Send connection event
+              send_connection_event(out)
+
+              # Start heartbeat
+              start_heartbeat(out)
+
+              # Event loop: process queued events until timeout or close
+              timeout = @test_mode ? TEST_TIMEOUT : TIMEOUT
+              check_interval = @test_mode ? TEST_EVENT_LOOP_CHECK_INTERVAL : EVENT_LOOP_CHECK_INTERVAL
+              start_time = Time.now
+              $stderr.puts "[SSE] Event loop started (timeout: #{timeout}s, check_interval: #{check_interval * 1000}ms)"
+
+              loop do
+                # Check for timeout
+                if Time.now - start_time > timeout
+                  $stderr.puts "[SSE] Timeout reached, sending timeout event"
+                  send_event(out, 'timeout', {
+                    message: 'Connection timed out due to inactivity'
+                  })
+                  break
+                end
+
+                # Check for stop signal
+                if @stop_flag
+                  $stderr.puts "[SSE] Stop flag set, exiting loop"
+                  break
+                end
+
+                # Process queued events (non-blocking with short timeout)
+                begin
+                  event = @event_queue.pop(true)  # non_block = true
+                  $stderr.puts "[SSE] Sending queued event: #{event[:type]}"
+                  send_event(out, event[:type], event[:data])
+                rescue ThreadError
+                  # Queue empty - that's ok, sleep briefly and check again
+                  sleep check_interval
+                end
+              end
+              $stderr.puts "[SSE] Event loop exited"
+            rescue IOError, Errno::EPIPE, Errno::ECONNRESET => e
+              # Connection closed by client - exit cleanly
+              @closed = true
+            rescue StandardError => e
+              # Unexpected error - log and exit
+              @closed = true
+            ensure
+              stop_heartbeat
+              unregister_connection
+              @stream = nil
+              @closed = true
+            end
+          end
+
+          [200, headers, stream]
+        end
+
+        # Public methods for sending events (used by transport layer)
+        # Events are queued and processed by the event loop
+        def send_tool_result_event(request_id, tool_response)
+          return if @closed
+
+          content = tool_response.content.first
+          result = JSON.parse(content[:text])
+
+          @event_queue << {
+            type: 'tool_result',
+            data: {
+              request_id: request_id,
+              success: !tool_response.is_error,
+              result: result
+            }
+          }
+        end
+
+        def send_tool_error_event(request_id, error)
+          return if @closed
+
+          @event_queue << {
+            type: 'tool_error',
+            data: {
+              request_id: request_id,
+              error: 'tool_execution_error',
+              error_description: error.message
+            }
+          }
+        end
+
+        def send_custom_event(event_type, data)
+          return if @closed
+
+          $stderr.puts "[SSE] Queueing event: #{event_type}"
+          @event_queue << {
+            type: event_type,
+            data: data
+          }
+          $stderr.puts "[SSE] Event queued, queue size: #{@event_queue.size}"
+        end
+
+        def close
+          @closed = true
+          @stop_flag = true
+          @stream&.close rescue nil
+        end
+
+        private
+
+        def extract_session_id(env)
+          env.dig('rack.session', :session_id) || SecureRandom.uuid
+        end
+
+        def send_event(stream, event_type, data)
+          return if @closed  # Don't send if already closed
+
+          @event_id += 1
+
+          stream.write("event: #{event_type}\n")
+          stream.write("id: #{@event_id}\n")
+          stream.write("data: #{JSON.generate(data)}\n")
+          stream.write("\n")
+
+          @last_activity = Time.now
+        rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+          # Connection closed by client
+          @closed = true
+          nil  # Return nil instead of raising
+        end
+
+        def send_connection_event(stream)
+          send_event(stream, 'connection', {
+            session_id: session_id,
+            transport: 'http_sse'
+          })
+        end
+
+        def send_heartbeat(stream)
+          send_event(stream, 'heartbeat', {
+            timestamp: Time.now.iso8601
+          })
+        end
+
+
+        def start_heartbeat(stream)
+          interval = @test_mode ? TEST_HEARTBEAT_INTERVAL : HEARTBEAT_INTERVAL
+          @heartbeat_thread = Thread.new do
+            loop do
+              sleep interval
+              send_heartbeat(stream)
+            end
+          rescue IOError, Errno::EPIPE, Errno::ECONNRESET => e
+            # Client disconnected - signal main event loop to exit
+            $stderr.puts "[HEARTBEAT] Client disconnect detected: #{e.class}"
+            @stop_flag = true
+          rescue StandardError => e
+            # Unexpected error - signal main loop to exit
+            $stderr.puts "[HEARTBEAT] Unexpected error: #{e.class}: #{e.message}"
+            @stop_flag = true
+          end
+        end
+
+        def stop_heartbeat
+          @heartbeat_thread&.kill
+          @heartbeat_thread = nil
+        end
+
+        def register_connection
+          # Connection registered in transport when handler is created
+        end
+
+        def unregister_connection
+          # Remove connection from transport's connection tracking
+          $stderr.puts "[SSE] Unregistering connection: #{@session_id}, transport present: #{!@transport.nil?}"
+          if @transport
+            $stderr.puts "[SSE] About to call transport.unregister_connection"
+            begin
+              @transport.unregister_connection(@session_id)
+              $stderr.puts "[SSE] Called transport.unregister_connection"
+            rescue => e
+              $stderr.puts "[SSE] ERROR calling unregister: #{e.class}: #{e.message}"
+              $stderr.puts "[SSE] Backtrace: #{e.backtrace.first(3).join('\n')}"
+            end
+          else
+            $stderr.puts "[SSE] WARNING: No transport to unregister from!"
+          end
+          $stderr.puts "[SSE] Unregistration complete"
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/transports.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Transports
+      # Transports will be autoloaded
+    end
+  end
+end
+
+require_relative 'transports/http_streaming_transport'
+require_relative 'transports/sse_stream_handler'

data/lib/mathpix/mcp.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# MCP (Model Context Protocol) integration for Mathpix
+#
+# This module provides MCP server functionality using the official Ruby MCP SDK.
+# All 9 tools are thin delegates to the core Mathpix::Client.
+#
+# Usage:
+#   require 'mathpix/mcp'
+#
+#   Mathpix.configure do |config|
+#     config.app_id = ENV['MATHPIX_APP_ID']
+#     config.app_key = ENV['MATHPIX_APP_KEY']
+#   end
+#
+#   Mathpix::MCP::Server.run
+
+# Load MCP components
+require_relative 'mcp/server'
+require_relative 'mcp/base_tool'
+
+# Load transports (HTTP/SSE)
+require_relative 'mcp/transports'
+
+# Load middleware (CORS, OAuth)
+require_relative 'mcp/middleware'
+
+# Load authentication
+require_relative 'mcp/auth'
+
+# Load elicitations (interactive prompts for low-confidence OCR)
+require_relative 'mcp/elicitations'
+
+# Load hierarchical resources
+require_relative 'mcp/resources'
+
+# Load all 9 tools
+require_relative 'mcp/tools/convert_image_tool'
+require_relative 'mcp/tools/convert_document_tool'
+require_relative 'mcp/tools/convert_strokes_tool'
+require_relative 'mcp/tools/batch_convert_tool'
+require_relative 'mcp/tools/check_document_status_tool'
+require_relative 'mcp/tools/search_results_tool'
+require_relative 'mcp/tools/get_usage_tool'
+require_relative 'mcp/tools/get_account_info_tool'
+require_relative 'mcp/tools/list_formats_tool'
+
+# Load all 4 resource handlers
+require_relative 'mcp/resources/latest_snip_resource'
+require_relative 'mcp/resources/recent_snips_resource'
+require_relative 'mcp/resources/snip_stats_resource'
+require_relative 'mcp/resources/formats_list_resource'

data/lib/mathpix/result.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # OCR Result object
+  # The geodesic path: rich, intuitive, method-based access
+  class Result
+    attr_reader :data, :source_path
+
+    def initialize(data, source_path = nil)
+      @data = data
+      @source_path = source_path
+    end
+
+    # Get source URL if image was processed from URL (feature parity with mpxpy)
+    #
+    # @return [String, nil] URL if source was remote, nil otherwise
+    def source_url
+      return nil unless @source_path.is_a?(String)
+      @source_path.start_with?('http://', 'https://') ? @source_path : nil
+    end
+
+    # Text result
+    # @return [String, nil]
+    def text
+      data['text']
+    end
+
+    # LaTeX styled output
+    # @return [String, nil]
+    def latex
+      data['latex_styled'] || data['latex']
+    end
+
+    alias latex_styled latex
+
+    # Simplified LaTeX
+    # @return [String, nil]
+    def latex_simplified
+      data['latex_simplified']
+    end
+
+    # MathML output
+    # @return [String, nil]
+    def mathml
+      data['mathml']
+    end
+
+    # AsciiMath output
+    # @return [String, nil]
+    def asciimath
+      data['asciimath']
+    end
+
+    # HTML output (may contain SVG)
+    # @return [String, nil]
+    def html
+      data['html']
+    end
+
+    # Confidence score
+    # @return [Float] 0.0-1.0
+    def confidence
+      data['confidence'] || 0.0
+    end
+
+    # Confidence rate (alternative)
+    # @return [Float] 0.0-1.0
+    def confidence_rate
+      data['confidence_rate'] || confidence
+    end
+
+    # Created timestamp
+    # @return [Time, nil]
+    def created_at
+      Time.parse(data['created']) if data['created']
+    rescue ArgumentError
+      nil
+    end
+
+    # Request ID
+    # @return [String, nil]
+    def request_id
+      data['request_id']
+    end
+
+    # Processing time in milliseconds
+    # @return [Integer, nil]
+    def processing_time_ms
+      data['processing_time_ms']
+    end
+
+    # Is content printed (vs handwritten)?
+    # @return [Boolean]
+    def printed?
+      data['is_printed'] == true
+    end
+
+    # Is content handwritten?
+    # @return [Boolean]
+    def handwritten?
+      data['is_handwritten'] == true
+    end
+
+    # Contains chart?
+    # @return [Boolean]
+    def chart?
+      data['contains_chart'] == true
+    end
+
+    # Contains diagram?
+    # @return [Boolean]
+    def diagram?
+      data['contains_diagram'] == true
+    end
+
+    # Contains table?
+    # @return [Boolean]
+    def table?
+      data['contains_table'] == true
+    end
+
+    # Get metadata
+    # @return [Hash]
+    def metadata
+      data['metadata'] || {}
+    end
+
+    # Get tags
+    # @return [Array<String>]
+    def tags
+      data['tags'] || []
+    end
+
+    # --- Line-by-line data (feature parity with mpxpy) ---
+
+    # Get line-by-line data with bounding boxes
+    #
+    # Requires snap(..., include_line_data: true)
+    # Feature parity with Python mpxpy's lines_json() method
+    #
+    # @return [Array<Line>] array of line objects
+    def lines
+      return [] unless data['line_data']
+
+      @lines ||= data['line_data'].map { |line_data| Line.new(line_data) }
+    end
+
+    # Get lines as JSON array (raw data)
+    # @return [Array<Hash>]
+    def lines_json
+      data['line_data'] || []
+    end
+
+    # Line data structure for bounding boxes and confidence
+    class Line
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      # Line text content
+      # @return [String]
+      def text
+        data['text'] || ''
+      end
+
+      # Line confidence
+      # @return [Float]
+      def confidence
+        data['confidence'] || 0.0
+      end
+
+      # Bounding box coordinates [x, y, width, height]
+      # @return [Array<Integer>, nil]
+      def bbox
+        data['bbox']
+      end
+
+      alias bounding_box bbox
+
+      # Is this line handwritten?
+      # @return [Boolean]
+      def handwritten?
+        data['type'] == 'handwriting'
+      end
+
+      # Is this line printed?
+      # @return [Boolean]
+      def printed?
+        data['type'] == 'printed' || data['type'] == 'print'
+      end
+
+      # LaTeX for this line
+      # @return [String, nil]
+      def latex
+        data['latex']
+      end
+
+      # MathML for this line
+      # @return [String, nil]
+      def mathml
+        data['mathml']
+      end
+
+      # Word-level data (if available)
+      # @return [Array<Word>]
+      def words
+        return [] unless data['words']
+
+        @words ||= data['words'].map { |word_data| Word.new(word_data) }
+      end
+
+      # Convert to hash
+      # @return [Hash]
+      def to_h
+        data
+      end
+
+      # Inspect
+      # @return [String]
+      def inspect
+        "#<Mathpix::Result::Line text=\"#{text&.[](0..30)}\" confidence=#{confidence}>"
+      end
+    end
+
+    # Word data structure for fine-grained bounding boxes
+    class Word
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      # Word text
+      # @return [String]
+      def text
+        data['text'] || ''
+      end
+
+      # Word confidence
+      # @return [Float]
+      def confidence
+        data['confidence'] || 0.0
+      end
+
+      # Word bounding box
+      # @return [Array<Integer>, nil]
+      def bbox
+        data['bbox']
+      end
+
+      # Convert to hash
+      # @return [Hash]
+      def to_h
+        data
+      end
+
+      # Inspect
+      # @return [String]
+      def inspect
+        "#<Mathpix::Result::Word text=\"#{text}\" confidence=#{confidence}>"
+      end
+    end
+
+    # Convert to hash
+    # @return [Hash]
+    def to_h
+      data
+    end
+
+    # Convert to JSON
+    # @return [String]
+    def to_json(*args)
+      data.to_json(*args)
+    end
+
+    # Inspect
+    # @return [String]
+    def inspect
+      "#<Mathpix::Result confidence=#{confidence} text=#{text&.[](0..50)}>"
+    end
+
+    # --- Chemistry-specific methods ---
+
+    # SMILES notation (chemistry)
+    # @return [String, nil]
+    def smiles
+      text if chemistry?
+    end
+
+    # InChI notation (chemistry)
+    # @return [String, nil]
+    def inchi
+      data['inchi']
+    end
+
+    # InChI Key (chemistry)
+    # @return [String, nil]
+    def inchikey
+      data['inchikey']
+    end
+
+    # Molecular formula
+    # @return [String, nil]
+    def molecular_formula
+      data['molecular_formula']
+    end
+
+    # Molecular name
+    # @return [String, nil]
+    def molecular_name
+      data['molecular_name']
+    end
+
+    # Molecular weight
+    # @return [Float, nil]
+    def molecular_weight
+      data['molecular_weight']
+    end
+
+    # Has stereochemistry?
+    # @return [Boolean]
+    def stereochemistry?
+      data['has_stereochemistry'] == true || smiles&.include?('@')
+    end
+
+    # Is this a chemistry result?
+    # @return [Boolean]
+    def chemistry?
+      molecular_formula || inchi || smiles&.match?(/^[A-Za-z0-9@\[\]\(\)=#\+\-\\\/\.]+$/)
+    end
+
+    # --- Success/Failure ---
+
+    # Was capture successful?
+    # @return [Boolean]
+    def success?
+      !text.nil? && confidence >= 0.5
+    end
+
+    # Was capture a failure?
+    # @return [Boolean]
+    def failure?
+      !success?
+    end
+
+    # Execute block if successful
+    # @yield [self]
+    # @return [self]
+    def on_success
+      yield self if success?
+      self
+    end
+
+    # Execute block if failed
+    # @yield [self]
+    # @return [self]
+    def on_failure
+      yield self if failure?
+      self
+    end
+  end
+end

data/lib/mathpix/version.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Gem version following semantic versioning
+  VERSION = '0.1.0'
+
+  # Seed for deterministic behavior
+  SEED = 1069
+
+  # Balanced ternary pattern
+  BALANCED_TERNARY = [+1, -1, -1, +1, +1, +1, +1].freeze
+
+  # Version info
+  def self.version_info
+    {
+      version: VERSION,
+      seed: SEED,
+      balanced_ternary: BALANCED_TERNARY,
+      ruby_version: RUBY_VERSION
+    }
+  end
+end