mathpix 0.1.0

data/lib/mathpix.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'base64'
+
+require_relative 'mathpix/version'
+require_relative 'mathpix/configuration'
+require_relative 'mathpix/client'
+require_relative 'mathpix/capture_builder'
+require_relative 'mathpix/result'
+require_relative 'mathpix/conversion'
+require_relative 'mathpix/chemistry'
+require_relative 'mathpix/document'
+require_relative 'mathpix/batch'
+require_relative 'mathpix/errors'
+require_relative 'mathpix/balanced_ternary'
+
+# Mathpix OCR Ruby Client
+# The geodesic path to mathematical OCR
+module Mathpix
+  class << self
+    # Configure Mathpix client
+    #
+    # @yield [Configuration] config object
+    # @example
+    #   Mathpix.configure do |config|
+    #     config.app_id = ENV['MATHPIX_APP_ID']
+    #     config.app_key = ENV['MATHPIX_APP_KEY']
+    #     config.seed = 1069
+    #   end
+    def configure
+      yield configuration
+    end
+
+    # Load configuration from file (feature parity with mpxpy)
+    #
+    # @param path [String] config file path (default: ~/.mathpix/config)
+    # @return [Configuration]
+    # @example
+    #   Mathpix.load_config('~/.mathpix/config')
+    #   Mathpix.load_config  # Uses default path
+    def load_config(path = nil)
+      configuration.load_from_file(path || Configuration::DEFAULT_CONFIG_PATH)
+      configuration
+    end
+
+    # Get current configuration
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      @configuration = Configuration.new
+      @client = nil
+    end
+
+    # Get or create client instance
+    # @return [Client]
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    # Snap an image to equation (the poet's way)
+    #
+    # Supports both local file paths and remote URLs (feature parity with Python mpxpy)
+    # HTTP URLs are automatically upgraded to HTTPS for security
+    #
+    # @param image_path_or_url [String, Hash] path to image file, URL, or {url: '...'} / {path: '...'}
+    # @param options [Hash] capture options
+    # @return [Result]
+    # @example Local file
+    #   equation = Mathpix.snap('equation.png')
+    #   puts equation.latex
+    # @example Remote URL (HTTPS)
+    #   result = Mathpix.snap('https://example.com/equation.png')
+    #   puts result.source_url  # => 'https://example.com/equation.png'
+    # @example Remote URL (HTTP - auto-upgraded)
+    #   result = Mathpix.snap('http://example.com/equation.png')
+    #   puts result.source_url  # => 'https://example.com/equation.png' (auto-upgraded)
+    # @example Hash with URL
+    #   result = Mathpix.snap(url: 'https://example.com/equation.png')
+    def snap(image_path_or_url, **options)
+      client.snap(image_path_or_url, **options)
+    end
+
+    # Start fluent capture builder (the artisan's way)
+    #
+    # @param image_path [String] path to image file
+    # @return [CaptureBuilder]
+    # @example
+    #   result = Mathpix
+    #     .from('integral.png')
+    #     .with_formats(:latex, :mathml)
+    #     .with_confidence(0.90)
+    #     .capture
+    def from(image_path)
+      CaptureBuilder.new(client, image_path)
+    end
+
+    # Process image with block (the _why way)
+    #
+    # @param image_path [String] path to image file
+    # @yield [Result] result object
+    # @example
+    #   Mathpix.process('page.png') do |result|
+    #     puts result.latex
+    #     puts result.confidence
+    #   end
+    def process(image_path, **options)
+      result = snap(image_path, **options)
+      yield result if block_given?
+      result
+    end
+
+    # Chemistry capture builder (the chemist's way)
+    #
+    # @param image_path [String] path to structure diagram
+    # @return [Chemistry]
+    # @example
+    #   molecule = Mathpix
+    #     .chemistry('benzene.png')
+    #     .with_smiles
+    #     .capture
+    def chemistry(image_path)
+      Chemistry.new(client, image_path)
+    end
+
+    # Document processing builder (PDF, DOCX, PPTX)
+    #
+    # Feature parity with Python mpxpy: supports PDF + Office documents
+    #
+    # @param document_path [String] path to document file
+    # @return [Document]
+    # @example PDF
+    #   doc = Mathpix
+    #     .document('paper.pdf')
+    #     .with_formats(:markdown, :latex)
+    #     .convert
+    # @example DOCX
+    #   doc = Mathpix
+    #     .document('thesis.docx')
+    #     .with_formats(:markdown)
+    #     .convert
+    # @example PPTX
+    #   doc = Mathpix
+    #     .document('slides.pptx')
+    #     .with_formats(:markdown)
+    #     .convert
+    def document(document_path)
+      Document.new(client, document_path)
+    end
+
+    # PDF processing builder (backward compatibility alias)
+    #
+    # @param pdf_path [String] path to PDF file
+    # @return [Document]
+    # @example
+    #   pdf = Mathpix
+    #     .pdf('paper.pdf')
+    #     .with_formats(:markdown, :latex)
+    #     .convert
+    def pdf(pdf_path)
+      document(pdf_path)
+    end
+
+    # Batch processing (the efficient way)
+    #
+    # @param image_paths [Array<String>] paths to images
+    # @yield [Batch] batch configuration
+    # @return [Array<Result>]
+    # @example
+    #   results = Mathpix.batch(images) do |batch|
+    #     batch.formats :latex, :text
+    #     batch.confidence_threshold 0.85
+    #   end
+    def batch(image_paths, &block)
+      Batch.new(client, image_paths).tap do |batch|
+        block.call(batch) if block
+      end.process
+    end
+
+    # Search recent captures (the detective's way)
+    #
+    # @param options [Hash] search options
+    # @return [Array<Result>]
+    # @example
+    #   recent = Mathpix.recent(limit: 10)
+    def recent(limit: 10)
+      client.recent(limit: limit)
+    end
+
+    # Search with query builder
+    #
+    # @yield [SearchQuery] query builder
+    # @return [Array<Result>]
+    # @example
+    #   results = Mathpix.search do |q|
+    #     q.text_contains("Pythagorean")
+    #     q.confidence_above(0.90)
+    #   end
+    def search(&block)
+      # TODO: Implement search query builder
+      client.search(&block)
+    end
+
+    # Convert Mathpix Markdown to multiple formats (feature parity with mpxpy)
+    #
+    # Async operation - returns Conversion object to poll for completion
+    #
+    # @param mmd [String] Mathpix Markdown content
+    # @param formats [Array<Symbol, String>] output formats (pdf, docx, html, etc.)
+    # @param options [Hash] conversion options
+    # @return [Conversion] conversion object (async)
+    # @example
+    #   conversion = Mathpix.convert_mmd(
+    #     mmd: "E = mc^2",
+    #     formats: [:pdf, :docx, :html]
+    #   )
+    #   conversion.wait_until_complete
+    #   conversion.to_pdf_file('output.pdf')
+    #   conversion.to_docx_file('output.docx')
+    def convert_mmd(mmd:, formats:, **options)
+      client.convert_mmd(mmd: mmd, formats: formats, **options)
+    end
+  end
+end

metadata

@@ -0,0 +1,283 @@
+--- !ruby/object:Gem::Specification
+name: mathpix
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Barton Rhodes
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: brakeman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: |
+  Transform mathematical images to LaTeX, chemistry structures to SMILES, and documents to
+  markdown with security-first design. Features HTTPS enforcement, path traversal protection,
+  structured logging, and complete MCP (Model Context Protocol) server integration.
+  The geodesic path to mathematical OCR in Ruby.
+email:
+- ies@prototypesf.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- SECURITY.md
+- lib/mathpix.rb
+- lib/mathpix/balanced_ternary.rb
+- lib/mathpix/batch.rb
+- lib/mathpix/capture_builder.rb
+- lib/mathpix/chemistry.rb
+- lib/mathpix/client.rb
+- lib/mathpix/configuration.rb
+- lib/mathpix/configuration.rb.backup
+- lib/mathpix/conversion.rb
+- lib/mathpix/document.rb
+- lib/mathpix/errors.rb
+- lib/mathpix/mcp.rb
+- lib/mathpix/mcp/auth.rb
+- lib/mathpix/mcp/auth/oauth_provider.rb
+- lib/mathpix/mcp/auth/token_manager.rb
+- lib/mathpix/mcp/base_tool.rb
+- lib/mathpix/mcp/elicitations.rb
+- lib/mathpix/mcp/elicitations/ambiguity_elicitation.rb
+- lib/mathpix/mcp/elicitations/base_elicitation.rb
+- lib/mathpix/mcp/elicitations/confidence_elicitation.rb
+- lib/mathpix/mcp/middleware.rb
+- lib/mathpix/mcp/middleware/cors_middleware.rb
+- lib/mathpix/mcp/middleware/oauth_middleware.rb
+- lib/mathpix/mcp/middleware/rate_limiting_middleware.rb
+- lib/mathpix/mcp/resources.rb
+- lib/mathpix/mcp/resources/formats_list_resource.rb
+- lib/mathpix/mcp/resources/hierarchical_router.rb
+- lib/mathpix/mcp/resources/latest_snip_resource.rb
+- lib/mathpix/mcp/resources/recent_snips_resource.rb
+- lib/mathpix/mcp/resources/snip_stats_resource.rb
+- lib/mathpix/mcp/server.rb
+- lib/mathpix/mcp/tools/batch_convert_tool.rb
+- lib/mathpix/mcp/tools/check_document_status_tool.rb
+- lib/mathpix/mcp/tools/convert_document_tool.rb
+- lib/mathpix/mcp/tools/convert_image_tool.rb
+- lib/mathpix/mcp/tools/convert_strokes_tool.rb
+- lib/mathpix/mcp/tools/get_account_info_tool.rb
+- lib/mathpix/mcp/tools/get_usage_tool.rb
+- lib/mathpix/mcp/tools/list_formats_tool.rb
+- lib/mathpix/mcp/tools/search_results_tool.rb
+- lib/mathpix/mcp/transports.rb
+- lib/mathpix/mcp/transports/http_streaming_transport.rb
+- lib/mathpix/mcp/transports/sse_stream_handler.rb
+- lib/mathpix/result.rb
+- lib/mathpix/version.rb
+homepage: https://github.com/teglonlabs/mathpix-mcp-server
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/teglonlabs/mathpix-mcp-server
+  source_code_uri: https://github.com/teglonlabs/mathpix-mcp-server
+  changelog_uri: https://github.com/teglonlabs/mathpix-mcp-server/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.mathpix.com
+  bug_tracker_uri: https://github.com/teglonlabs/mathpix-mcp-server/issues
+  wiki_uri: https://github.com/teglonlabs/mathpix-mcp-server/wiki
+  rubygems_mfa_required: 'true'
+  security_policy_uri: https://github.com/teglonlabs/mathpix-mcp-server/blob/main/SECURITY.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Secure Ruby client for Mathpix OCR API with MCP integration
+test_files: []