mathpix 0.1.0

data/lib/mathpix/document.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Document processing builder (PDF, DOCX, PPTX)
+  # The geodesic path: document-oriented, format-agnostic
+  #
+  # Feature parity with Python mpxpy: PDF + Office documents
+  class Document
+    attr_reader :client, :document_path, :options
+
+    def initialize(client, document_path)
+      @client = client
+      @document_path = document_path
+      @options = {}
+    end
+
+    # Set output formats
+    # @param formats [Array<Symbol>] format names
+    # @return [self]
+    # @example
+    #   doc.with_formats(:markdown, :latex, :docx)
+    def with_formats(*formats)
+      @options[:formats] = formats.flatten
+      self
+    end
+
+    # Enable table extraction
+    # @param options [Hash] table options
+    # @return [self]
+    def with_tables(**options)
+      @options[:include_table_html] = true
+      @options.merge!(options)
+      self
+    end
+
+    # Enable diagram extraction
+    # @return [self]
+    def with_diagrams
+      @options[:include_diagram_svg] = true
+      self
+    end
+
+    # Set quality level
+    # @param level [Symbol] :low, :medium, :high
+    # @return [self]
+    def quality(level)
+      @options[:quality] = level
+      self
+    end
+
+    # Enable line-level data (bounding boxes)
+    # @return [self]
+    def with_line_data
+      @options[:include_line_data] = true
+      self
+    end
+
+    # Enable word-level data (bounding boxes)
+    # @return [self]
+    def with_word_data
+      @options[:include_word_data] = true
+      self
+    end
+
+    # Set page range for processing
+    # @param start_page [Integer] first page (1-indexed)
+    # @param end_page [Integer, nil] last page (nil = all)
+    # @return [self]
+    def pages(start_page, end_page = nil)
+      @options[:page_ranges] = { start: start_page, end: end_page }
+      self
+    end
+
+    # Execute document conversion (async operation)
+    #
+    # @return [DocumentConversion] conversion object (async)
+    # @example
+    #   conversion = Mathpix.document('paper.pdf')
+    #     .with_formats(:markdown, :latex)
+    #     .convert
+    #   conversion.wait_until_complete
+    #   conversion.save_markdown('output.md')
+    def convert
+      # Detect document type from extension
+      doc_type = detect_document_type
+
+      # Build conversion request
+      conversion_id = client.convert_document(
+        document_path: document_path,
+        document_type: doc_type,
+        **options
+      )
+
+      DocumentConversion.new(client, conversion_id, document_path, doc_type)
+    end
+
+    alias call convert
+    alias run convert
+
+    private
+
+    # Detect document type from file extension
+    # @return [Symbol] :pdf, :docx, :pptx
+    def detect_document_type
+      ext = File.extname(document_path).downcase
+      case ext
+      when '.pdf' then :pdf
+      when '.docx' then :docx
+      when '.pptx' then :pptx
+      else
+        raise InvalidImageError.new(
+          "Unsupported document format: #{ext}",
+          recommended_format: 'pdf, docx, pptx'
+        )
+      end
+    end
+  end
+
+  # Document Conversion Result (async operation)
+  #
+  # Polls Mathpix API until conversion completes
+  # Feature parity with Python mpxpy document processing
+  class DocumentConversion
+    attr_reader :client, :conversion_id, :document_path, :document_type
+
+    def initialize(client, conversion_id, document_path, document_type)
+      @client = client
+      @conversion_id = conversion_id
+      @document_path = document_path
+      @document_type = document_type
+    end
+
+    # Wait for conversion to complete
+    #
+    # @param max_wait [Integer] maximum wait time in seconds
+    # @param poll_interval [Float] seconds between polls
+    # @return [self]
+    def wait_until_complete(max_wait: 600, poll_interval: 3.0)
+      start_time = Time.now
+
+      loop do
+        status_data = client.get_document_status(conversion_id)
+        status = status_data['status']
+
+        case status
+        when 'completed'
+          @result = DocumentResult.new(status_data, document_path, document_type)
+          return self
+        when 'error', 'failed'
+          raise ConversionError.new(
+            "Document conversion failed: #{status_data['error']}",
+            conversion_id: conversion_id,
+            conversion_status: status
+          )
+        when 'processing', 'pending'
+          elapsed = Time.now - start_time
+          if elapsed > max_wait
+            raise TimeoutError, "Document conversion timed out after #{max_wait}s"
+          end
+          sleep poll_interval
+        else
+          raise ConversionError.new(
+            "Unknown conversion status: #{status}",
+            conversion_id: conversion_id,
+            conversion_status: status
+          )
+        end
+      end
+    end
+
+    # Get result (must wait_until_complete first)
+    # @return [DocumentResult]
+    def result
+      @result || raise(ConversionError, 'Conversion not yet complete. Call wait_until_complete first.')
+    end
+
+    # Convenience method: wait and get result
+    # @return [DocumentResult]
+    def complete!
+      wait_until_complete
+      result
+    end
+
+    # Save markdown output
+    # @param path [String] output file path
+    def save_markdown(path)
+      complete! unless @result
+      @result.save_markdown(path)
+    end
+
+    # Save LaTeX output
+    # @param path [String] output file path
+    def save_latex(path)
+      complete! unless @result
+      @result.save_latex(path)
+    end
+
+    # Save HTML output
+    # @param path [String] output file path
+    def save_html(path)
+      complete! unless @result
+      @result.save_html(path)
+    end
+
+    # Save DOCX output
+    # @param path [String] output file path
+    def save_docx(path)
+      complete! unless @result
+      @result.save_docx(path)
+    end
+  end
+
+  # Document Result object
+  #
+  # Represents processed document with extracted content
+  class DocumentResult < Result
+    attr_reader :document_path, :document_type
+
+    def initialize(data, document_path = nil, document_type = nil)
+      super(data)
+      @document_path = document_path
+      @document_type = document_type
+    end
+
+    # Get all pages
+    # @return [Array<Hash>] page data
+    def pages
+      data['pages'] || []
+    end
+
+    # Get page count
+    # @return [Integer]
+    def page_count
+      pages.length
+    end
+
+    # Get all equations across all pages
+    # @return [Array<String>]
+    def equations
+      pages.flat_map { |p| p['equations'] || [] }
+    end
+
+    # Get all tables across all pages
+    # @return [Array<Hash>]
+    def tables
+      pages.flat_map { |p| p['tables'] || [] }
+    end
+
+    # Get all diagrams across all pages
+    # @return [Array<Hash>]
+    def diagrams
+      pages.flat_map { |p| p['diagrams'] || [] }
+    end
+
+    # Get markdown output
+    # @return [String, nil]
+    def markdown
+      data['markdown'] || data['mmd']
+    end
+
+    # Get LaTeX output
+    # @return [String, nil]
+    def latex
+      data['latex']
+    end
+
+    # Get HTML output
+    # @return [String, nil]
+    def html
+      data['html']
+    end
+
+    # Save markdown to file
+    # @param path [String] output file path
+    def save_markdown(path)
+      File.write(path, markdown) if markdown
+    end
+
+    # Save LaTeX to file
+    # @param path [String] output file path
+    def save_latex(path)
+      File.write(path, latex) if latex
+    end
+
+    # Save HTML to file
+    # @param path [String] output file path
+    def save_html(path)
+      File.write(path, html) if html
+    end
+
+    # Save DOCX output to file
+    # @param path [String] output file path
+    def save_docx(path)
+      if data['docx_url']
+        docx_data = client.download(data['docx_url'])
+        File.binwrite(path, docx_data)
+      elsif data['docx_data']
+        File.binwrite(path, data['docx_data'])
+      end
+    end
+
+    # Check if document is a specific type
+    # @return [Boolean]
+    def pdf?
+      document_type == :pdf
+    end
+
+    def docx?
+      document_type == :docx
+    end
+
+    def pptx?
+      document_type == :pptx
+    end
+  end
+
+  # Alias PDF class to Document for backward compatibility
+  PDF = Document
+  PDFResult = DocumentResult
+end

data/lib/mathpix/errors.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Base error class
+  class Error < StandardError
+    attr_reader :details
+
+    def initialize(message, details: {})
+      super(message)
+      @details = details
+    end
+  end
+
+  # Configuration error
+  class ConfigurationError < Error; end
+
+  # API error
+  class APIError < Error
+    attr_reader :status
+
+    def initialize(message, status: nil, details: {})
+      super(message, details: details)
+      @status = status
+    end
+  end
+
+  # Rate limit error
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **options)
+      super(message, **options)
+      @retry_after = retry_after
+    end
+  end
+
+  # Server error (5xx)
+  class ServerError < APIError; end
+
+  # Network/timeout error
+  class NetworkError < Error; end
+  class TimeoutError < NetworkError; end
+
+  # Low confidence error
+  class LowConfidenceError < Error
+    attr_reader :confidence, :suggestions
+
+    def initialize(message, confidence: nil, suggestions: [])
+      super(message)
+      @confidence = confidence
+      @suggestions = suggestions
+    end
+  end
+
+  # Invalid request error (malformed input)
+  class InvalidRequestError < Error; end
+
+  # Invalid image error
+  class InvalidImageError < Error
+    attr_reader :recommended_format
+
+    def initialize(message, recommended_format: nil)
+      super(message)
+      @recommended_format = recommended_format
+    end
+  end
+
+  # Conversion error
+  class ConversionError < Error
+    attr_reader :conversion_id, :conversion_status
+
+    def initialize(message, conversion_id: nil, conversion_status: nil)
+      super(message)
+      @conversion_id = conversion_id
+      @conversion_status = conversion_status
+    end
+  end
+end