README.md

---
title: Proportio – Precision Proportion Calculator
emoji: 🧮
colorFrom: red
colorTo: gray
sdk: gradio
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - mcp-server
  - proportion-calculator
  - gradio
  - python
  - mathematics
  - llm-tools
---

<div align="center">
  <img src="logo_1024.png" alt="Proportio Logo" width="200" height="200">
</div>

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](Dockerfile)
[![Tests](https://img.shields.io/badge/tests-58%20passing-green.svg)](tests/)
[![MCP Server](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)

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

---

## 🎯 Overview

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.

### 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

---


https://github.com/user-attachments/assets/96d30b20-1bf0-4b2b-a1ea-d0a5776f547c

---
## ✨ 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


---

## 📋 Table of Contents

- [🎯 Overview](#-overview)
- [✨ Features](#-features)
- [🚀 Quick Start](#-quick-start)
- [🔧 Core Functions](#-core-functions)
- [🏗️ Architecture](#️-architecture)
- [📦 Installation](#-installation)
- [🐳 Docker Deployment](#-docker-deployment)
- [🧪 Testing](#-testing)
- [🔌 MCP Integration](#-mcp-integration)
- [📖 API Reference](#-api-reference)
- [🛠️ Development](#️-development)
- [📝 License](#-license)

---

## 🚀 Quick Start

### Using Docker (Recommended)

```bash
# Clone the repository
git clone https://github.com/leksval/proportio.git
cd proportio

# Build and run with Docker
docker build -t proportio-server .
docker run -p 7860:7860 proportio-server

# Access the web interface
open http://localhost:7860
```

### Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Run the server
python proportion_server.py

# Access the web interface
open http://localhost:7860
```

### Quick Function Examples

```python
from proportion_server import percent_of, solve_proportion, resize_dimensions

# Calculate percentage
result = percent_of(25, 100)  # Returns: 25.0

# Solve proportion: 3/4 = 6/?
result = solve_proportion(3, 4, 6, None)  # Returns: 8.0

# Resize dimensions by 2x
width, height = resize_dimensions(100, 50, 2.0)  # Returns: (200.0, 100.0)
```

---

## 🔧 Core Functions

### 1. **`percent_of(part, whole)`**
Calculate what percentage the part is of the whole.

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

**Mathematical Preconditions:**
- `whole != 0` (division by zero protection)

**Real-world Examples:**
- Sales conversion rates
- Test score percentages  
- Growth rate calculations

### 2. **`solve_proportion(a, b, c, d)`**
Solve missing term in proportion a/b = c/d (exactly one parameter must be None).

```python
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)
```

**Mathematical Preconditions:**
- Exactly one value must be None (missing)
- Division denominators != 0 (varies by missing value)

**Real-world Examples:**
- Recipe scaling (4 servings : 2 cups = 6 servings : ? cups)
- Currency exchange rates
- Map scale calculations

### 3. **`scale_by_ratio(value, ratio)`**
Scale a value by a given ratio.

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

**Use Cases:**
- Applying discount percentages
- Scaling measurements
- Financial calculations

### 4. **`direct_k(x, y)`**
Find proportionality constant k in direct variation y = kx.

```python
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)
```

**Mathematical Preconditions:**
- `x != 0` (division by zero protection)

**Applications:**
- Physics calculations (force = k × displacement)
- Economics (cost = k × quantity)
- Engineering (stress = k × strain)

### 5. **`resize_dimensions(width, height, scale)`**
Resize dimensions with uniform scale factor.

```python
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)
```

**Mathematical Preconditions:**
- `width >= 0` (dimensions must be non-negative)
- `height >= 0` (dimensions must be non-negative)  
- `scale > 0` (scale factor must be positive)

**Applications:**
- Image resizing
- Screen resolution scaling
- Architectural drawings

---

## 🏗️ Architecture

### Assertion-Based Validation

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

```python
def percent_of(part: float, whole: float) -> float:
    # Mathematical preconditions
    assert whole != 0, "Division by zero: whole cannot be zero"
    
    # Direct calculation
    percentage = (part / whole) * 100
    return percentage
```

**Benefits:**
- **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

### Project Structure

```
proportio/
├── proportion_server.py    # Core mathematical functions + Gradio server
├── models.py              # Pydantic data models (simplified)
├── config.py              # Configuration and logging setup
├── styles.css             # Custom branding and responsive design
├── tests/
│   └── test_tools.py      # Comprehensive test suite (58 tests)
├── requirements.txt       # Minimal dependencies (3 packages)
├── Dockerfile            # Single-stage containerization
└── README.md             # This documentation
```

### Dependency Architecture

**Streamlined Dependencies** (only 3 required):
- **`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

### Error Handling Philosophy

**No Try-Catch Blocks** - All validation done through assertions:

```python
# ❌ Old approach (complex exception handling)
try:
    if whole == 0:
        raise ValueError("Division by zero")
    result = part / whole
except ValueError as e:
    # Handle error...

# ✅ New approach (assertion-based)
assert whole != 0, "Division by zero: whole cannot be zero"
result = part / whole
```

---

## 📦 Installation

### System Requirements

- **Python 3.11+**
- **pip** package manager
- **Docker** (optional, for containerized deployment)

### Local Installation

```bash
# Clone repository
git clone https://github.com/leksval/proportio.git
cd proportio

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Verify installation
python -c "from proportion_server import percent_of; print(percent_of(25, 100))"
```

### Development Installation

```bash
# Install with development dependencies
pip install -r requirements.txt

# Run tests to verify setup
python -m pytest tests/test_tools.py -v

# Start development server
python proportion_server.py
```

---

## 🐳 Docker Deployment

### Building the Container

```bash
# Build image
docker build -t proportio-server .

# Run container
docker run -p 7860:7860 proportio-server

# Run with custom configuration
docker run -p 8080:7860 -e PORT=7860 proportio-server
```

### Container Features

- **Security**: Non-root user execution
- **Optimization**: Single-stage build for minimal image size
- **Flexibility**: Configurable port and environment settings
- **Health**: Automatic process management

### Production Deployment

```bash
# Run detached with restart policy
docker run -d \
  --name proportio \
  --restart unless-stopped \
  -p 7860:7860 \
  proportio-server

# View logs
docker logs proportio

# Stop container
docker stop proportio
```

---

## 🧪 Testing

### Test Suite Coverage

**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

### Running Tests

```bash
# Run all tests
python -m pytest tests/test_tools.py -v

# Run specific test class
python -m pytest tests/test_tools.py::TestPercentOf -v

# Run with coverage (if pytest-cov installed)
python -m pytest tests/test_tools.py --cov=proportion_server

# Run tests in Docker
docker run --rm proportio-server python -m pytest tests/test_tools.py -v
```

### Test Categories

#### **Unit Tests**
- Individual function validation
- Mathematical accuracy verification
- Error condition testing

#### **Integration Tests**
- Chained calculation workflows
- Real-world scenario testing
- Cross-function compatibility

#### **Edge Case Tests**
- Floating-point precision limits
- Very large and very small numbers
- Boundary condition validation

### Sample Test Output

```
==================== test session starts ====================
collected 58 items

tests/test_tools.py::TestPercentOf::test_basic_percentage PASSED
tests/test_tools.py::TestPercentOf::test_zero_part PASSED
tests/test_tools.py::TestPercentOf::test_negative_values PASSED
...
tests/test_tools.py::TestIntegration::test_real_world_recipe_scaling PASSED
tests/test_tools.py::TestIntegration::test_financial_calculation_workflow PASSED

==================== 58 passed in 0.45s ====================
```

---

## 🔌 MCP Integration

### Model Context Protocol Support

Proportio provides native **MCP server capabilities** for seamless LLM integration:

```python
# Launch with MCP support
demo.launch(
    server_name="0.0.0.0",
    server_port=7860,
    mcp_server=True,  # Enable MCP functionality
    show_error=True
)
```

### Using with LLM Agents

The MCP server exposes all mathematical functions as tools that LLMs can call directly:

**Available MCP Tools:**
- `percent_of` - Calculate percentage relationships
- `solve_proportion` - Solve missing proportion terms
- `scale_by_ratio` - Apply scaling ratios
- `direct_k` - Find proportionality constants
- `resize_dimensions` - Scale dimensional pairs

### MCP Connection Example

```json
{
  "name": "proportio",
  "type": "sse",
  "url": "http://localhost:7860/mcp"
}
```

### Integration Benefits

- **Reliable Math**: LLMs can delegate complex calculations
- **Error Handling**: Clear error messages for invalid inputs
- **Type Safety**: Automatic input validation and conversion
- **Performance**: Fast, direct mathematical operations

---

## 📖 API Reference

### Function Signatures

```python
def percent_of(part: float, whole: float) -> float:
    """Calculate percentage that part is of whole."""

def solve_proportion(
    a: Optional[float] = None,
    b: Optional[float] = None, 
    c: Optional[float] = None,
    d: Optional[float] = None
) -> float:
    """Solve missing term in proportion a/b = c/d."""

def scale_by_ratio(value: float, ratio: float) -> float:
    """Scale value by given ratio."""

def direct_k(x: float, y: float) -> float:
    """Find proportionality constant k where y = kx."""

def resize_dimensions(width: float, height: float, scale: float) -> Tuple[float, float]:
    """Resize dimensions with uniform scale factor."""
```

### Error Messages

All functions provide clear, actionable error messages:

```python
# Division by zero errors
"Division by zero: whole cannot be zero"
"Division by zero: x cannot be zero"
"Division by zero: denominator"

# Validation errors  
"Exactly one value must be None"
"Width must be non-negative"
"Height must be non-negative"
"Scale factor must be positive"
```

### Return Types

- **Single Values**: `float` for mathematical results
- **Dimension Pairs**: `Tuple[float, float]` for width/height
- **Errors**: `AssertionError` with descriptive messages

---

## 🛠️ Development

### Project Philosophy

1. **Assertion-Based Validation** - No try-catch complexity
2. **Mathematical Precision** - Accurate calculations with clear preconditions
3. **Minimal Dependencies** - Only essential packages
4. **Comprehensive Testing** - High test coverage with edge cases
5. **Professional Design** - Clean, branded user interface

### Code Style

```python
# Clear function signatures with type hints
def function_name(param: Type) -> ReturnType:
    """
    Brief description.
    
    Args:
        param: Parameter description
        
    Returns:
        Return value description
        
    Mathematical preconditions:
        - Explicit constraint documentation
    """
    # Assertion-based validation
    assert condition, "Clear error message"
    
    # Direct calculation
    result = calculation
    
    # Optional logging
    logger.debug(f"Operation completed: {result}")
    
    return result
```

### Adding New Functions

1. **Implement Core Logic** - Add function to `proportion_server.py`
2. **Add Mathematical Preconditions** - Document constraints explicitly
3. **Create Demo Function** - Add Gradio interface wrapper
4. **Write Comprehensive Tests** - Cover all edge cases
5. **Update Documentation** - Add examples and use cases

### Contributing Guidelines

1. **Fork the Repository** - Create your feature branch
2. **Follow Code Style** - Use assertion-based validation
3. **Add Tests** - Ensure comprehensive test coverage
4. **Update Documentation** - Keep README current
5. **Submit Pull Request** - Include description of changes

---

## 📝 License

This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details.

### Key License Points

- ✅ **Commercial Use** - Use in commercial applications
- ✅ **Modification** - Modify and distribute changes
- ✅ **Distribution** - Distribute original or modified versions
- ✅ **Patent Use** - Grant of patent rights from contributors
- ⚠️ **Attribution** - Must include license and copyright notice
- ⚠️ **State Changes** - Must document modifications

---

## 🤝 Support

### Getting Help

- **Issues**: [GitHub Issues](https://github.com/leksval/proportio/issues)
- **Documentation**: This README and inline code documentation
- **Examples**: See `tests/test_tools.py` for usage examples

### Contributing

We welcome contributions! Please see the [Development](#️-development) section for guidelines.

### Reporting Bugs

When reporting bugs, please include:
1. **Environment Details** (Python version, OS, Docker version)
2. **Reproduction Steps** (minimal code example)
3. **Expected vs Actual Behavior**
4. **Error Messages** (full stack trace if applicable)

---

**Built with ❤️ for mathematical precision and LLM integration**

*Proportio - Where Mathematics Meets Reliability*