mathpix 0.1.0

data/lib/mathpix/capture_builder.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Fluent API builder for OCR captures
+  # The geodesic path: chainable, intuitive, discoverable
+  class CaptureBuilder
+    def initialize(client, image_path)
+      @client = client
+      @image_path = image_path
+      @options = {}
+    end
+
+    # Set output formats
+    #
+    # @param formats [Array<Symbol>] format names
+    # @return [self]
+    # @example
+    #   builder.with_formats(:latex, :mathml, :asciimath)
+    def with_formats(*formats)
+      @options[:formats] = formats.flatten
+      self
+    end
+
+    # Set confidence threshold
+    #
+    # @param threshold [Float] minimum confidence (0.0-1.0)
+    # @return [self]
+    def with_confidence(threshold)
+      @options[:confidence_threshold] = threshold
+      self
+    end
+
+    # Add metadata
+    #
+    # @param metadata [Hash] metadata key-value pairs
+    # @return [self]
+    def with_metadata(**metadata)
+      @options[:metadata] = metadata
+      self
+    end
+
+    # Add tags
+    #
+    # @param tags [Array<String>] tag strings
+    # @return [self]
+    def with_tags(*tags)
+      @options[:tags] = tags.flatten
+      self
+    end
+
+    # Enable space removal
+    #
+    # @return [self]
+    def remove_spaces
+      @options[:rm_spaces] = true
+      self
+    end
+
+    # Set recognition options
+    #
+    # @param options [Hash] recognition settings
+    # @return [self]
+    def with_recognition(**options)
+      @options.merge!(options)
+      self
+    end
+
+    # Set preprocessing options
+    #
+    # @param options [Hash] preprocessing settings
+    # @return [self]
+    # @example
+    #   builder.with_preprocessing(denoise: true, enhance_contrast: true)
+    def with_preprocessing(**options)
+      @options[:preprocessing] = options
+      self
+    end
+
+    # Set data options
+    #
+    # @param options [Hash] data output options
+    # @return [self]
+    def with_data_options(**options)
+      @options[:data_options] = options
+      self
+    end
+
+    # Set alphabet support
+    #
+    # @param alphabets [Hash] alphabet flags
+    # @return [self]
+    # @example
+    #   builder.with_alphabets(en: true, es: true, de: true)
+    def with_alphabets(**alphabets)
+      @options[:alphabets] = alphabets
+      self
+    end
+
+    # Enable chemistry mode
+    #
+    # @return [self]
+    def chemistry_mode
+      @options[:chemistry] = true
+      @options[:include_smiles] = true
+      self
+    end
+
+    # Enable line-by-line data output (feature parity with mpxpy)
+    #
+    # Returns structured data with bounding boxes for each line
+    # Enables result.lines() and result.lines_json() methods
+    #
+    # @return [self]
+    # @example
+    #   result = Mathpix.from('multiline.png')
+    #     .with_line_data
+    #     .capture
+    #   result.lines.each { |line| puts "#{line.text} @ #{line.bbox}" }
+    def with_line_data
+      @options[:include_line_data] = true
+      self
+    end
+
+    # Alias for with_line_data (alternative name)
+    alias include_line_data with_line_data
+
+    # Execute capture
+    #
+    # @return [Result]
+    def capture
+      @client.snap(@image_path, **@options)
+    end
+
+    # Alias for #capture with .convert terminator (matches BDD examples)
+    alias convert capture
+
+    # Alias for #capture
+    alias call capture
+    alias run capture
+    alias execute capture
+  end
+end

data/lib/mathpix/chemistry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Chemistry capture builder
+  # The geodesic path: domain-specific, fluent, intuitive
+  class Chemistry
+    def initialize(client, image_path)
+      @client = client
+      @image_path = image_path
+      @options = {
+        chemistry: true,
+        include_smiles: true
+      }
+    end
+
+    # Enable SMILES output
+    # @return [self]
+    def with_smiles
+      @options[:include_smiles] = true
+      self
+    end
+
+    # Enable InChI output
+    # @return [self]
+    def with_inchi
+      @options[:include_inchi] = true
+      self
+    end
+
+    # Enable molecular formula
+    # @return [self]
+    def with_molecular_formula
+      @options[:include_molecular_formula] = true
+      self
+    end
+
+    # Enable stereochemistry detection
+    # @return [self]
+    def with_stereochemistry
+      @options[:detect_stereochemistry] = true
+      self
+    end
+
+    # Set confidence threshold
+    # @param threshold [Float] minimum confidence
+    # @return [self]
+    def with_confidence(threshold)
+      @options[:confidence_threshold] = threshold
+      self
+    end
+
+    # Add metadata
+    # @param metadata [Hash] metadata
+    # @return [self]
+    def with_metadata(**metadata)
+      @options[:metadata] = metadata
+      self
+    end
+
+    # Execute capture
+    # @return [Result]
+    def capture
+      @client.snap(@image_path, **@options)
+    end
+
+    alias call capture
+    alias run capture
+  end
+end

data/lib/mathpix/client.rb

@@ -0,0 +1,439 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Core HTTP client for Mathpix API
+  # The geodesic path: clean, testable, resilient
+  class Client
+    attr_reader :config
+
+    def initialize(config = Mathpix.configuration)
+      @config = config
+      config.validate!
+    end
+
+    # Snap image to equation (core method)
+    #
+    # Supports both local file paths and remote URLs (feature parity with mpxpy)
+    #
+    # @param image_path_or_url [String, Hash] path to image, URL, or hash with :path/:url key
+    # @param options [Hash] request options
+    # @return [Result]
+    # @example Local file
+    #   client.snap('equation.png')
+    # @example Remote URL
+    #   client.snap('https://example.com/equation.png')
+    #   client.snap(url: 'https://example.com/equation.png')
+    # @example With options
+    #   client.snap('equation.png', formats: [:latex, :mathml])
+    def snap(image_path_or_url, **options)
+      src, source_ref = prepare_image_source(image_path_or_url, options)
+
+      response = post('/text', {
+        src: src,
+        formats: (options[:formats] || config.default_formats).map(&:to_s),
+        include_line_data: options[:include_line_data] || false,
+        **build_request_options(options)
+      })
+
+      Result.new(response, source_ref)
+    end
+
+    # Get recent captures
+    #
+    # @param limit [Integer] number of results
+    # @return [Array<Result>]
+    def recent(limit: 10)
+      response = get('/ocr-results', params: { limit: limit })
+      response['data'].map { |data| Result.new(data) }
+    end
+
+    # Search captures
+    #
+    # @yield [SearchQuery] query builder (future)
+    # @return [Array<Result>]
+    def search
+      # TODO: Implement search query DSL
+      []
+    end
+
+    # Convert Mathpix Markdown to multiple formats
+    #
+    # Feature parity with Python mpxpy conversion_new() method
+    # Async operation - returns Conversion object to poll for completion
+    #
+    # @param mmd [String] Mathpix Markdown content
+    # @param formats [Array<Symbol, String>] output formats
+    # @param options [Hash] conversion options
+    # @return [Conversion] conversion object (async)
+    # @example
+    #   conversion = client.convert_mmd(
+    #     mmd: "\\frac{1}{2} + \\sqrt{3}",
+    #     formats: [:pdf, :docx, :html]
+    #   )
+    #   conversion.wait_until_complete
+    #   conversion.to_pdf_file('output.pdf')
+    def convert_mmd(mmd:, formats:, **options)
+      # Build formats hash for API
+      formats_hash = Array(formats).each_with_object({}) do |format, hash|
+        hash[format.to_s] = true
+      end
+
+      response = post('/converter', {
+        mmd: mmd,
+        formats: formats_hash,
+        conversion_options: options[:conversion_options] || {}
+      })
+
+      conversion_id = response['conversion_id']
+      Conversion.new(self, conversion_id: conversion_id, mmd: mmd, formats: formats)
+    end
+
+    # Get conversion status
+    #
+    # @param conversion_id [String] conversion ID
+    # @return [Hash] status data
+    def get_conversion_status(conversion_id)
+      get("/converter/#{conversion_id}")
+    end
+
+    # Download file from URL
+    #
+    # @param url [String] download URL
+    # @return [String] file content as bytes
+    def download(url)
+      uri = URI(url)
+      request = Net::HTTP::Get.new(uri)
+      request['app_id'] = config.app_id
+      request['app_key'] = config.app_key
+      request['User-Agent'] = config.user_agent
+
+      response = make_request(uri, request)
+
+      case response
+      when Net::HTTPSuccess
+        response.body
+      else
+        raise APIError.new(
+          "Download failed: #{response.code}",
+          status: response.code.to_i
+        )
+      end
+    end
+
+    # Convert document (PDF, DOCX, PPTX) asynchronously
+    #
+    # Feature parity with Python mpxpy document processing
+    #
+    # @param document_path [String] path to document file
+    # @param document_type [Symbol] :pdf, :docx, :pptx
+    # @param options [Hash] conversion options
+    # @return [String] conversion_id for polling
+    # @example
+    #   conversion_id = client.convert_document(
+    #     document_path: 'paper.pdf',
+    #     document_type: :pdf,
+    #     formats: [:markdown, :latex]
+    #   )
+    def convert_document(document_path:, document_type:, **options)
+      # Encode document as base64 data URI or use URL
+      src = if url?(document_path)
+        document_path
+      else
+        encode_image(document_path)  # Reuse existing encoding
+      end
+
+      # Build conversion request
+      request_body = {
+        src: src,
+        formats: (options[:formats] || [:markdown]).map(&:to_s),
+        conversion_formats: build_conversion_formats(options),
+        **build_document_options(options)
+      }
+
+      response = post('/pdf', request_body)
+      response['pdf_id']  # Returns conversion ID for polling
+    end
+
+    # Get document conversion status
+    #
+    # @param conversion_id [String] document conversion ID
+    # @return [Hash] status data
+    def get_document_status(conversion_id)
+      get("/pdf/#{conversion_id}")
+    end
+
+    private
+
+    # Build conversion formats hash
+    #
+    # @param options [Hash] user options
+    # @return [Hash] formats configuration
+    def build_conversion_formats(options)
+      formats = {}
+      if options[:formats]
+        Array(options[:formats]).each do |fmt|
+          formats[fmt.to_s] = true
+        end
+      end
+      formats
+    end
+
+    # Build document-specific options
+    #
+    # @param options [Hash] user options
+    # @return [Hash] document options
+    def build_document_options(options)
+      {}.tap do |opts|
+        opts[:include_table_html] = true if options[:include_table_html]
+        opts[:include_diagram_svg] = true if options[:include_diagram_svg]
+        opts[:include_line_data] = true if options[:include_line_data]
+        opts[:include_word_data] = true if options[:include_word_data]
+        opts[:quality] = options[:quality] if options[:quality]
+        opts[:page_ranges] = options[:page_ranges] if options[:page_ranges]
+      end
+    end
+
+    # Prepare image source (URL or local file)
+    #
+    # Feature parity with Python mpxpy which supports both url= and file_path= parameters
+    # Automatically upgrades HTTP to HTTPS (mpxpy behavior)
+    #
+    # @param input [String, Hash] path, URL, or hash with :path/:url key
+    # @param options [Hash] additional options
+    # @return [Array<String, String>] src value and source reference
+    # @raise [InvalidRequestError] if input looks like malformed URL
+    def prepare_image_source(input, options = {})
+      # Handle hash input: { url: '...' } or { path: '...' }
+      if input.is_a?(Hash)
+        if input[:url] || input['url']
+          url = input[:url] || input['url']
+          url = config.upgrade_to_https(url)  # Auto-upgrade HTTP→HTTPS
+          validate_url!(url)  # Raise InvalidRequestError if malformed
+          return [url, url]
+        elsif input[:path] || input['path']
+          path = input[:path] || input['path']
+          return [encode_image(path), path]
+        end
+      end
+
+      # Auto-upgrade HTTP to HTTPS BEFORE validation
+      # This ensures HTTP URLs pass validation after upgrade
+      upgraded_input = config.upgrade_to_https(input)
+
+      # Detect if input is URL or local path
+      if url?(upgraded_input)
+        [upgraded_input, upgraded_input]  # Use URL directly as src
+      elsif looks_like_url?(input)
+        # String contains URL-like patterns but isn't valid
+        raise InvalidRequestError, "Invalid URL format: #{input}"
+      else
+        # Try to encode as local file
+        begin
+          [encode_image(input), input]  # Encode local file (use original path)
+        rescue SecurityError, Errno::ENOENT => e
+          # If file encoding fails and input doesn't look like a file path,
+          # it's likely a malformed URL
+          if !looks_like_file_path?(input)
+            raise InvalidRequestError, "Invalid URL format: #{input}"
+          else
+            raise  # Re-raise original error for actual file path issues
+          end
+        end
+      end
+    end
+
+    # Check if string is a URL (using secure configuration validation)
+    #
+    # @param str [String] string to check
+    # @return [Boolean]
+    def url?(str)
+      return false unless str.is_a?(String)
+      config.valid_url?(str)
+    end
+
+    # Check if string looks like a URL but may not be valid
+    #
+    # Detects patterns that suggest URL intent: protocol prefixes, www prefix
+    # Used to provide better error messages for malformed URLs
+    #
+    # @param str [String] string to check
+    # @return [Boolean]
+    def looks_like_url?(str)
+      return false unless str.is_a?(String)
+      # URL-like patterns: contains protocol or www prefix
+      str.match?(%r{^(https?://|www\.)|://})
+    end
+
+    # Validate URL and raise InvalidRequestError if malformed
+    #
+    # @param url [String] URL to validate
+    # @raise [InvalidRequestError] if URL is not valid
+    def validate_url!(url)
+      return if config.valid_url?(url)
+      raise InvalidRequestError, "Invalid URL format: #{url}"
+    end
+
+    # Check if string looks like a file path
+    #
+    # Detects patterns that suggest file path intent: directory separators,
+    # file extensions, relative/absolute path markers
+    #
+    # @param str [String] string to check
+    # @return [Boolean]
+    def looks_like_file_path?(str)
+      return false unless str.is_a?(String)
+      # File path patterns: contains slashes, starts with ~, has file extension, or starts with .
+      str.match?(%r{^[~/\.]|/|\\|\.(?:png|jpe?g|gif|webp|pdf|docx|pptx)$}i)
+    end
+
+    # Encode image to base64 data URI (with path sanitization)
+    #
+    # @param path [String] path to image file
+    # @return [String] data URI
+    # @raise [SecurityError] if path is invalid or dangerous
+    def encode_image(path)
+      # Sanitize path to prevent directory traversal
+      sanitized_path = config.sanitize_path(path)
+      raise SecurityError, "Invalid or dangerous file path: #{path}" if sanitized_path.nil?
+
+      content = File.binread(sanitized_path)
+      mime_type = detect_mime_type(sanitized_path)
+      "data:#{mime_type};base64,#{Base64.strict_encode64(content)}"
+    end
+
+    # Detect MIME type from file extension
+    #
+    # @param path [String] file path
+    # @return [String] MIME type
+    def detect_mime_type(path)
+      case File.extname(path).downcase
+      when '.png' then 'image/png'
+      when '.jpg', '.jpeg' then 'image/jpeg'
+      when '.gif' then 'image/gif'
+      when '.webp' then 'image/webp'
+      when '.pdf' then 'application/pdf'
+      when '.docx' then 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+      when '.pptx' then 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+      else 'application/octet-stream'
+      end
+    end
+
+    # Build request options from user input + defaults
+    #
+    # @param options [Hash] user options
+    # @return [Hash] complete request options
+    def build_request_options(options)
+      {}.tap do |opts|
+        # Data options
+        if options[:include_latex]
+          opts[:data_options] ||= {}
+          opts[:data_options][:include_latex] = true
+        end
+
+        # Metadata
+        opts[:metadata] = options[:metadata] if options[:metadata]
+        opts[:tags] = Array(options[:tags]) if options[:tags]
+
+        # Recognition options
+        opts[:rm_spaces] = options[:rm_spaces] if options.key?(:rm_spaces)
+        opts[:idiomatic_eqn_arrays] = options[:idiomatic_eqn_arrays] if options.key?(:idiomatic_eqn_arrays)
+
+        # Confidence threshold
+        opts[:confidence_threshold] = options[:confidence_threshold] if options[:confidence_threshold]
+
+        # Chemistry
+        opts[:include_smiles] = true if options[:chemistry] || options[:include_smiles]
+
+        # Alphabets
+        opts[:alphabets_allowed] = options[:alphabets] if options[:alphabets]
+      end
+    end
+
+    # Make POST request
+    #
+    # @param path [String] API endpoint path
+    # @param body [Hash] request body
+    # @return [Hash] parsed response
+    def post(path, body)
+      uri = URI("#{config.endpoint}#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      request['app_id'] = config.app_id
+      request['app_key'] = config.app_key
+      request['User-Agent'] = config.user_agent
+      request.body = JSON.generate(body)
+
+      response = make_request(uri, request)
+      handle_response(response)
+    end
+
+    # Make GET request
+    #
+    # @param path [String] API endpoint path
+    # @param params [Hash] query parameters
+    # @return [Hash] parsed response
+    def get(path, params: {})
+      uri = URI("#{config.endpoint}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+
+      request = Net::HTTP::Get.new(uri)
+      request['app_id'] = config.app_id
+      request['app_key'] = config.app_key
+      request['User-Agent'] = config.user_agent
+
+      response = make_request(uri, request)
+      handle_response(response)
+    end
+
+    # Execute HTTP request with error handling
+    #
+    # @param uri [URI] request URI
+    # @param request [Net::HTTPRequest] HTTP request object
+    # @return [Net::HTTPResponse]
+    def make_request(uri, request)
+      Net::HTTP.start(uri.hostname, uri.port,
+                      use_ssl: uri.scheme == 'https',
+                      read_timeout: config.timeout) do |http|
+        http.request(request)
+      end
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise TimeoutError, "Request timed out after #{config.timeout}s: #{e.message}"
+    rescue StandardError => e
+      raise NetworkError, "Network error: #{e.message}"
+    end
+
+    # Handle API response
+    #
+    # @param response [Net::HTTPResponse]
+    # @return [Hash] parsed response body
+    # @raise [APIError] on error response
+    def handle_response(response)
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      when Net::HTTPTooManyRequests
+        raise RateLimitError.new(
+          'Rate limit exceeded',
+          retry_after: response['Retry-After']&.to_i
+        )
+      when Net::HTTPClientError
+        error_data = JSON.parse(response.body) rescue {}
+        raise APIError.new(
+          error_data['error'] || 'Client error',
+          status: response.code.to_i,
+          details: error_data
+        )
+      when Net::HTTPServerError
+        raise ServerError.new(
+          'Server error',
+          status: response.code.to_i
+        )
+      else
+        raise APIError.new(
+          "Unexpected response: #{response.code}",
+          status: response.code.to_i
+        )
+      end
+    end
+  end
+end