mathpix-gem

Mathpix Ruby Client

Transform mathematical images to LaTeX, chemistry structures to SMILES, and documents to markdown with security-first design. The geodesic path to mathematical OCR in Ruby.

Features

• 🔒 Security First: HTTPS enforcement, path traversal protection, file size limits
• 🎯 Fluent API: Builder pattern for elegant, chainable operations
• ⚡ Batch Processing: Parallel execution with callback hooks
• 📄 Smart PDF Batching: Automatic batching for large PDFs (>1.2MB) with adaptive sizing
• 📊 Multiple Formats: LaTeX, MathML, AsciiMath, Markdown, SMILES
• 🧪 BDD Tested: 15+ Cucumber feature files with comprehensive coverage
• 🔌 MCP Integration: Full Model Context Protocol server for any MCP-compatible client
• 🎲 Balanced Ternary: Seed 1069 encoding utilities

Installation

As a Ruby Gem

Add to your Gemfile:

gem 'mathpix'

Or install directly:

gem install mathpix

As an MCP Server

The gem includes a standalone MCP (Model Context Protocol) server that works with any MCP-compatible client:

gem install mathpix

The server executable will be installed at ~/.gem/ruby/X.X.X/bin/mathpix-mcp.

Supported MCP Clients:

• Claude Desktop/Code
• Any MCP registry-supporting client
• Custom MCP implementations

See MCP_SETUP.md for complete MCP server setup and configuration.

Quick Start

Configuration

require 'mathpix'

Mathpix.configure do |config|
  config.app_id = ENV['MATHPIX_APP_ID']
  config.app_key = ENV['MATHPIX_APP_KEY']
end

Or use .env file:

MATHPIX_APP_ID=your_app_id
MATHPIX_APP_KEY=your_app_key

Basic Usage

Image to LaTeX

# Single image conversion
result = Mathpix.from('equation.png')
                .with_formats(:latex_styled, :text)
                .capture

puts result.latex         # => "3x^{2} + 5x - 7 = 0"
puts result.confidence    # => 0.99

URL to LaTeX

# Convert from URL
result = Mathpix.from_url('https://example.com/math.png')
                .with_formats(:latex_styled, :mathml)
                .capture

puts result.latex
puts result.mathml

Chemistry (SMILES)

# Chemistry structure recognition
result = Mathpix.from('molecule.png')
                .with_formats(:smiles)
                .capture

puts result.smiles  # => "CC(C)CCO"

PDF Conversion

# Async PDF to Markdown
pdf_job = Mathpix.pdf('research_paper.pdf')
                 .to_markdown
                 .async
                 .start

# Poll for completion
until pdf_job.complete?
  sleep 2
  pdf_job.refresh
end

puts pdf_job.markdown

Large PDF Batching (Automatic)

For PDFs larger than 1.2MB, the gem automatically uses intelligent batching to prevent "request too large" errors. This happens transparently - no configuration needed.

# Large PDF (e.g., 10MB, 200 pages) - automatic batching
conversion = Mathpix.document('large_thesis.pdf')
                    .with_formats(:markdown, :latex)
                    .convert

# Wait for all batches to complete
conversion.wait_until_complete

# Get merged result (all batches combined)
result = conversion.result
puts "Processed #{result.data['batch_count']} batches"
puts "Total pages: #{result.data['total_pages']}"
puts result.markdown

How it works:

1. Automatic Detection: Files > 1.2MB are automatically batched
2. Adaptive Sizing: Batch size adapts to page density
   • Dense pages (0.5MB/page) → 2 pages per batch
   • Normal pages (0.05MB/page) → 10 pages per batch
3. Sequential Processing: Batches processed in order with exponential backoff retry
4. Result Merging: Markdown, LaTeX, HTML, and metadata merged automatically
5. Seed 1069 Checkpoints: Balanced ternary pattern [+1, -1, -1, +1, +1, +1, +1] for progress tracking

Batch metadata:

result.data['batch_metadata'].each do |batch|
  puts "Batch #{batch[:batch_num]}: pages #{batch[:page_start]}-#{batch[:page_end]}"
  puts "  Size: #{batch[:size_mb].round(2)} MB"
  puts "  Time: #{batch[:conversion_time_seconds].round(1)}s"
  puts "  Checkpoint: #{batch[:checkpoint] ? '✓' : '✗'}"
end

Batch Processing

images = Dir['equations/*.png']

results = Mathpix.batch(images) do |batch|
  batch.formats :latex_styled, :text
  batch.confidence_threshold 0.85
  batch.max_threads 5

  batch.on_each do |result|
    puts "✓ #{result.latex}"
  end

  batch.on_error do |error, path|
    puts "✗ Failed: #{path} - #{error.message}"
  end
end.process

puts "Success rate: #{results.success_rate}"
puts "High confidence: #{results.confident(0.9).count}"

MCP Server Usage

The Mathpix MCP server provides AI assistants with OCR capabilities through the Model Context Protocol.

Available Tools (9)

1. convert_image - Convert math/chemistry images to LaTeX/SMILES
2. convert_document - Convert PDF documents to Markdown (async)
3. check_document_status - Check status of document conversion
4. batch_convert - Convert multiple images in parallel
5. get_account_info - Get account information
6. get_usage - Get API usage statistics
7. list_formats - List supported output formats
8. convert_strokes - Convert handwriting strokes to LaTeX
9. search_results - Search previous OCR results

Available Resources (4)

1. formats_list - List of supported formats
2. latest_snip - Most recent OCR result
3. recent_snips - Recent OCR results
4. snip_stats - Statistics about OCR results

Example MCP Configuration

For any MCP client that supports JSON configuration:

{
  "mcpServers": {
    "mathpix": {
      "command": "/path/to/.gem/ruby/3.3.0/bin/mathpix-mcp",
      "env": {
        "MATHPIX_APP_ID": "your_app_id",
        "MATHPIX_APP_KEY": "your_app_key",
        "MATHPIX_MAX_FILE_SIZE_MB": "10",
        "MATHPIX_HTTPS_ONLY": "true"
      }
    }
  }
}

Environment Variables:

• MATHPIX_APP_ID - Your Mathpix application ID (required)
• MATHPIX_APP_KEY - Your Mathpix application key (required)
• MATHPIX_MAX_FILE_SIZE_MB - Maximum file size (default: 10)
• MATHPIX_HTTPS_ONLY - Force HTTPS (default: true)
• MATHPIX_LOG_LEVEL - Logging level: DEBUG, INFO, WARN, ERROR

See MCP_SETUP.md for detailed setup instructions, troubleshooting, and client-specific configurations.

Error Handling

begin
  result = Mathpix.from('image.png').capture
rescue Mathpix::AuthenticationError => e
  puts "Invalid credentials: #{e.message}"
rescue Mathpix::ValidationError => e
  puts "Invalid input: #{e.message}"
rescue Mathpix::RateLimitError => e
  puts "Rate limit exceeded. Retry after: #{e.retry_after}"
rescue Mathpix::SecurityError => e
  puts "Security violation: #{e.message}"
rescue Mathpix::APIError => e
  puts "API error: #{e.message}"
end

Documentation

• API Reference
• Changelog
• Security Policy

License

MIT License - see LICENSE for details.

Credits

• Developed by TegLon Labs
• Mathpix API by Mathpix
• Balanced ternary seed: 1069

Support

• GitHub Issues: https://github.com/TeglonLabs/mathpix-gem/issues
• Email: ies@prototypesf.org

---

The geodesic path to mathematical OCR in Ruby ∎