Proportio - Precision Proportion Calculator

Proportio – Precision Proportion Calculator

Professional mathematical calculations for proportions, percentages, and scaling operations with assertion-based validation and MCP server integration.

Proportio is a specialized mathematical calculation server designed for LLM agents and applications requiring precise proportion calculations. Built with assertion-based validation and zero-tolerance error handling, it provides reliable mathematical operations through both a web interface and Model Context Protocol (MCP) integration.

Live Demo

HF Space Demo

Key Use Cases

  • Recipe Scaling: Scale ingredient quantities for different serving sizes
  • Financial Calculations: Calculate percentages, ratios, and proportional growth
  • Engineering: Resize dimensions, scale measurements, and maintain proportional relationships
  • Data Analysis: Compute percentages, ratios, and proportional transformations
  • LLM Integration: Provide reliable mathematical operations through MCP protocol

Features

🔢 Mathematical Functions

  • Percentage Calculations - Convert parts to percentages with precision
  • Proportion Solving - Solve missing terms in a/b = c/d relationships
  • Ratio Scaling - Scale values by precise ratios
  • Proportionality Constants - Find k in y = kx relationships
  • Dimension Resizing - Uniform scaling of width/height pairs

🛡️ Validation Architecture

  • Assertion-Based Validation - Explicit mathematical preconditions
  • Zero Exception Handling - No try-catch blocks, fast failure detection
  • Precise Error Messages - Clear, actionable error descriptions
  • Type Safety - Robust input validation and type checking

🌐 Integration Options

  • Web Interface - Professional Gradio-based UI with custom branding
  • MCP Server - Native Model Context Protocol support for LLM agents
  • Docker Ready - Containerized deployment with security best practices
  • API Access - Direct function calls with comprehensive documentation

🎨 Professional Design

  • Custom Branding - Red-black-white theme with geometric logo
  • Responsive Layout - Optimized for desktop and mobile devices
  • Split Results - Clear separation of input/output sections
  • Error Handling - User-friendly error messages and validation

Core Functions

1. percent_of(part, whole)

Calculate what percentage the part is of the whole.

percent_of(25, 100)     # → 25.0%
percent_of(3, 4)        # → 75.0%
percent_of(150, 100)    # → 150.0%

2. solve_proportion(a, b, c, d)

Solve missing term in proportion a/b = c/d (exactly one parameter must be None).

solve_proportion(3, 4, 6, None)      # → 8.0  (3/4 = 6/8)
solve_proportion(None, 4, 6, 8)      # → 3.0  (?/4 = 6/8)
solve_proportion(2, None, 6, 9)      # → 3.0  (2/? = 6/9)

3. scale_by_ratio(value, ratio)

Scale a value by a given ratio.

scale_by_ratio(100, 1.5)    # → 150.0
scale_by_ratio(200, 0.5)    # → 100.0
scale_by_ratio(50, 2.0)     # → 100.0

4. direct_k(x, y)

Find proportionality constant k in direct variation y = kx.

direct_k(5, 15)     # → 3.0  (15 = 3 × 5)
direct_k(4, 12)     # → 3.0  (12 = 3 × 4)
direct_k(2, 7)      # → 3.5  (7 = 3.5 × 2)

5. resize_dimensions(width, height, scale)

Resize dimensions with uniform scale factor.

resize_dimensions(100, 50, 2.0)    # → (200.0, 100.0)
resize_dimensions(200, 100, 0.5)   # → (100.0, 50.0)
resize_dimensions(150, 75, 1.5)    # → (225.0, 112.5)

Architecture

Assertion-Based Validation

Proportio uses assertion-based validation throughout, providing several key advantages:

  • Fast Failure: Immediate error detection with precise messages
  • No Exception Overhead: Zero try-catch complexity
  • Clear Preconditions: Mathematical requirements explicitly documented
  • Predictable Behavior: Consistent error handling across all functions

Streamlined Dependencies

  • gradio[mcp]>=5.0.0 - Web framework with MCP server capabilities
  • pydantic>=2.8.0 - Data validation and parsing
  • pytest>=8.0.0 - Testing framework

Testing

58 comprehensive tests covering:

  • ✅ Basic functionality for all 5 core functions
  • ✅ Edge cases and boundary conditions
  • ✅ Error handling and assertion validation
  • ✅ Integration workflows and chained calculations
  • ✅ Floating-point precision and mathematical accuracy
  • ✅ Type validation and input sanitization

MCP Integration

Proportio provides native MCP server capabilities for seamless LLM integration, exposing all mathematical functions as tools that LLMs can call directly for reliable mathematical operations.

Proportio - Where Mathematics Meets Reliability