Upload 15 files

.dockerignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Documentation
+docs/_build/
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Project specific
+*.md
+.env.example

.env.example

@@ -0,0 +1,28 @@
+# Proportion MCP Server Configuration
+# Copy this file to .env and set your values
+
+# Server Configuration
+SERVER_NAME=0.0.0.0
+SERVER_PORT=7860
+
+# Security Configuration (REQUIRED for production)
+# Generate a secure token: python -c "import secrets; print(secrets.token_urlsafe(32))"
+MCP_TOKEN=your-secure-token-here
+
+# Request Limits
+MAX_REQUEST_SIZE=65536
+
+# Development Settings
+DEBUG=false
+RELOAD=false
+LOG_LEVEL=INFO
+
+# Example production configuration:
+# MCP_TOKEN=abc123xyz789secure_token_here
+# DEBUG=false
+# LOG_LEVEL=WARNING
+
+# Example development configuration:
+# DEBUG=true
+# RELOAD=true
+# LOG_LEVEL=DEBUG

Dockerfile

@@ -0,0 +1,39 @@
+# Simple Docker build for MCP server
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Create non-root user for security
+RUN groupadd -r appuser && useradd -r -g appuser appuser
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY --chown=appuser:appuser . .
+
+# Set environment variables
+ENV PYTHONPATH=/app
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Create pytest cache directory with proper permissions
+RUN mkdir -p /app/.pytest_cache && chown -R appuser:appuser /app/.pytest_cache
+
+# Security: run as non-root user
+USER appuser
+
+# Expose port
+EXPOSE 7860
+
+# Add healthcheck
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:7860')" || exit 1
+
+# Run the application with proper signal handling
+CMD ["python", "-u", "app.py"]

README.md

@@ -0,0 +1,636 @@
+---
+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*

app.py

@@ -0,0 +1,93 @@
+"""
+Main application entry point for Proportion MCP Server.
+Handles both local development and cloud deployment.
+"""
+
+import logging
+import os
+import signal
+import sys
+
+from proportion_server import create_gradio_app
+from config import get_settings, setup_logging, is_huggingface_space
+
+# Initialize logging and settings
+setup_logging()
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+def signal_handler(signum, frame):
+    """Handle shutdown signals gracefully."""
+    logger.info(f"📡 Received signal {signum}, shutting down gracefully...")
+    sys.exit(0)
+
+
+def main() -> None:
+    """Main application entry point."""
+    
+    # Set up signal handlers for graceful shutdown
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+    
+    logger.info("🚀 Starting Proportion MCP Server")
+    logger.info(f"Settings: {settings.model_dump_json(indent=2)}")
+    
+    # Create Gradio app
+    demo = create_gradio_app()
+    assert demo is not None, "Failed to create Gradio application"
+    logger.info("✅ Gradio application created successfully")
+    
+    # Launch configuration
+    launch_kwargs = {
+        "server_name": settings.server_name,
+        "server_port": settings.server_port,
+        "mcp_server": True,  # Enable MCP server functionality
+        "show_error": settings.debug,
+        "quiet": not settings.debug,
+        "prevent_thread_lock": False,  # Keep main thread alive
+    }
+    
+    # Development-specific settings
+    if not settings.is_production():
+        launch_kwargs.update({
+            "debug": settings.debug,
+        })
+    
+    # Hugging Face Spaces specific settings
+    if is_huggingface_space():
+        launch_kwargs.update({
+            "server_name": "0.0.0.0",  # Required for HF Spaces
+            "share": False,  # Don't create gradio.live links on HF
+            "quiet": True,  # Reduce logging noise
+        })
+        logger.info("🤗 Configured for Hugging Face Spaces deployment")
+    
+    # Log the MCP endpoint information
+    if is_huggingface_space():
+        space_url = os.environ.get("SPACE_URL", "https://your-space.hf.space")
+        logger.info(f"🔗 MCP Server will be available at: {space_url}")
+    else:
+        logger.info(f"🔗 MCP Server will be available at: http://{settings.server_name}:{settings.server_port}")
+    
+    logger.info("🔧 MCP Tools exposed: percent_of, solve_proportion, scale_by_ratio, direct_k, resize_dimensions")
+    logger.info("📖 Functions with proper type hints and docstrings are automatically exposed as MCP tools")
+    
+    # Launch the server
+    logger.info("🌐 Starting server...")
+    demo.launch(**launch_kwargs)
+    
+    # Keep the main thread alive
+    logger.info("✅ Server is running, press Ctrl+C to stop")
+    if hasattr(signal, 'pause'):
+        # Unix systems
+        signal.pause()
+    else:
+        # Windows systems
+        import time
+        while True:
+            time.sleep(1)
+
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,129 @@
+"""
+Configuration management using Pydantic Settings.
+Handles environment variables with validation and defaults.
+"""
+
+import os
+from typing import Optional
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings with environment variable support."""
+    
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore"
+    )
+    
+    # Server configuration
+    server_name: str = Field(
+        default="0.0.0.0",
+        description="Server bind address"
+    )
+    
+    server_port: int = Field(
+        default=7860,
+        ge=1024,
+        le=65535,
+        description="Server port (1024-65535)"
+    )
+    
+    # Security configuration
+    mcp_token: Optional[str] = Field(
+        default=None,
+        description="MCP authentication token (required for production)"
+    )
+    
+    # Request limits
+    max_request_size: int = Field(
+        default=65536,  # 64KB
+        ge=1024,
+        le=1048576,  # 1MB max
+        description="Maximum request body size in bytes"
+    )
+    
+    # Development settings
+    debug: bool = Field(
+        default=False,
+        description="Enable debug mode"
+    )
+    
+    reload: bool = Field(
+        default=False,
+        description="Enable hot reload in development"
+    )
+    
+    # Logging configuration
+    log_level: str = Field(
+        default="INFO",
+        description="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)"
+    )
+    
+    def is_production(self) -> bool:
+        """Check if running in production mode."""
+        return not self.debug and self.mcp_token is not None
+    
+    def validate_production_settings(self) -> None:
+        """Validate settings for production deployment."""
+        if self.is_production():
+            assert self.mcp_token, "MCP_TOKEN environment variable is required for production deployment"
+
+
+# Global settings instance
+settings = Settings()
+
+
+def get_settings() -> Settings:
+    """Get the current settings instance."""
+    return settings
+
+
+def setup_logging() -> None:
+    """Configure logging based on settings."""
+    import logging
+    
+    logging.basicConfig(
+        level=getattr(logging, settings.log_level.upper()),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+    
+    # Set Gradio logging level
+    if not settings.debug:
+        logging.getLogger("gradio").setLevel(logging.WARNING)
+        logging.getLogger("uvicorn").setLevel(logging.WARNING)
+
+
+# Environment detection helpers
+def is_huggingface_space() -> bool:
+    """Check if running on Hugging Face Spaces."""
+    return "SPACE_ID" in os.environ
+
+
+def is_docker() -> bool:
+    """Check if running in Docker container."""
+    return os.path.exists("/.dockerenv") or "DOCKER_CONTAINER" in os.environ
+
+
+def get_deployment_info() -> dict[str, str]:
+    """Get deployment environment information."""
+    info = {
+        "environment": "unknown",
+        "platform": "local"
+    }
+    
+    if is_huggingface_space():
+        info["platform"] = "huggingface_spaces"
+        info["environment"] = "production"
+    elif is_docker():
+        info["platform"] = "docker"
+        info["environment"] = "production" if settings.is_production() else "development"
+    else:
+        info["platform"] = "local"
+        info["environment"] = "development"
+    
+    return info

docs/client_examples.md

@@ -0,0 +1,597 @@
+# MCP Client Configuration Examples
+
+This document provides configuration examples for various MCP clients to connect to the Proportio server.
+
+## Cursor IDE
+
+### Method 1: Settings JSON
+
+Add to your Cursor settings (`Cmd/Ctrl + ,` → Open Settings JSON):
+
+```json
+{
+  "mcpServers": {
+    "proportio": {
+      "url": "http://localhost:7860/gradio_api/mcp/sse",
+      "headers": {
+        "X-Api-Key": "your-secure-token-here"
+      }
+    }
+  }
+}
+```
+
+### Method 2: Workspace Configuration
+
+Create `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "proportio": {
+    "url": "http://localhost:7860/gradio_api/mcp/sse",
+    "headers": {
+      "X-Api-Key": "your-secure-token-here"
+    }
+  }
+}
+```
+
+## Claude Desktop
+
+### Configuration File Location
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+
+### Local Server Configuration
+
+```json
+{
+  "mcpServers": {
+    "proportio": {
+      "command": "python",
+      "args": ["/path/to/proportio/app.py"],
+      "env": {
+        "MCP_TOKEN": "your-secure-token-here"
+      }
+    }
+  }
+}
+```
+
+### Remote Server Configuration
+
+```json
+{
+  "mcpServers": {
+    "proportio": {
+      "url": "https://your-server.com/gradio_api/mcp/sse",
+      "headers": {
+        "X-Api-Key": "your-secure-token-here"
+      }
+    }
+  }
+}
+```
+
+## CrewAI
+
+### Basic Setup
+
+```python
+from crewai import Agent, Task, Crew
+from crewai.tools import MCPTool
+
+# Configure the MCP tool
+proportio_tool = MCPTool(
+    name="proportio_calculator",
+    url="http://localhost:7860/gradio_api/mcp/sse",
+    headers={"X-Api-Key": "your-secure-token-here"}
+)
+
+# Create an agent with the tool
+math_agent = Agent(
+    role="Mathematical Calculator",
+    goal="Perform accurate proportion and percentage calculations",
+    backstory="You are an expert mathematician who uses reliable tools for calculations.",
+    tools=[proportio_tool],
+    verbose=True
+)
+
+# Example task
+calculation_task = Task(
+    description="Calculate what percentage 75 is of 300, then scale that result by 1.5",
+    agent=math_agent,
+    expected_output="The percentage and scaled result with explanations"
+)
+
+# Run the crew
+crew = Crew(
+    agents=[math_agent],
+    tasks=[calculation_task]
+)
+
+result = crew.kickoff()
+print(result)
+```
+
+### Advanced CrewAI Setup with Multiple Tools
+
+```python
+from crewai import Agent, Task, Crew
+from crewai.tools import MCPTool
+
+class ProportioTools:
+    def __init__(self, base_url="http://localhost:7860", api_key="your-token"):
+        self.base_url = f"{base_url}/gradio_api/mcp/sse"
+        self.headers = {"X-Api-Key": api_key}
+    
+    def get_tools(self):
+        return [
+            MCPTool(
+                name="percent_calculator",
+                url=self.base_url,
+                headers=self.headers,
+                description="Calculate percentages accurately"
+            ),
+            MCPTool(
+                name="proportion_solver",
+                url=self.base_url,
+                headers=self.headers,
+                description="Solve proportion equations"
+            ),
+            MCPTool(
+                name="dimension_resizer",
+                url=self.base_url,
+                headers=self.headers,
+                description="Resize dimensions with scaling"
+            )
+        ]
+
+# Usage
+proportio = ProportioTools(api_key="your-secure-token-here")
+tools = proportio.get_tools()
+
+agent = Agent(
+    role="Design Calculator",
+    goal="Help with design calculations and proportions",
+    tools=tools
+)
+```
+
+## OpenAI Agents SDK
+
+### Basic Configuration
+
+```python
+from openai_agents import Agent
+from openai_agents.mcp import MCPConnection
+
+# Setup MCP connection
+mcp_conn = MCPConnection(
+    url="http://localhost:7860/gradio_api/mcp/sse",
+    headers={"X-Api-Key": "your-secure-token-here"}
+)
+
+# Create agent with MCP tools
+agent = Agent(
+    name="Math Assistant",
+    model="gpt-4",
+    mcp_connections=[mcp_conn]
+)
+
+# Use the agent
+response = agent.run("What percentage is 45 out of 180?")
+print(response)
+```
+
+## Generic HTTP Client (for testing)
+
+### Using curl
+
+```bash
+# Test percent_of tool
+curl -X POST http://localhost:7860/gradio_api/mcp/sse \
+  -H "X-Api-Key: your-secure-token-here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "percent_of",
+      "arguments": {
+        "part": 25,
+        "whole": 100
+      }
+    }
+  }'
+```
+
+### Using Python requests
+
+```python
+import requests
+import json
+
+def call_proportio_tool(tool_name, arguments, api_key="your-token"):
+    url = "http://localhost:7860/gradio_api/mcp/sse"
+    headers = {
+        "X-Api-Key": api_key,
+        "Content-Type": "application/json"
+    }
+    
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": tool_name,
+            "arguments": arguments
+        }
+    }
+    
+    response = requests.post(url, headers=headers, json=payload)
+    return response.json()
+
+# Examples
+result1 = call_proportio_tool("percent_of", {"part": 75, "whole": 300})
+print(f"Percentage: {result1}")
+
+result2 = call_proportio_tool("solve_proportion", {"a": 3, "b": 4, "c": 6, "d": None})
+print(f"Missing value: {result2}")
+
+result3 = call_proportio_tool("resize_dimensions", {
+    "width": 1920, 
+    "height": 1080, 
+    "scale": 0.5
+})
+print(f"New dimensions: {result3}")
+```
+
+## Environment-Specific Configurations
+
+### Development Environment
+
+```bash
+# .env file
+MCP_TOKEN=dev-token-123
+DEBUG=true
+LOG_LEVEL=DEBUG
+RELOAD=true
+```
+
+### Production Environment
+
+```bash
+# .env file
+MCP_TOKEN=prod-secure-token-xyz789
+DEBUG=false
+LOG_LEVEL=WARNING
+MAX_REQUEST_SIZE=32768
+```
+
+### Hugging Face Spaces
+
+Set these as Space secrets:
+
+- `MCP_TOKEN`: Your secure authentication token
+- `LOG_LEVEL`: `INFO` or `WARNING`
+
+Access URL: `https://your-username-proportio.hf.space/gradio_api/mcp/sse`
+
+## Security Best Practices
+
+### Token Generation
+
+Generate secure tokens:
+
+```bash
+# Python
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+
+# OpenSSL
+openssl rand -base64 32
+
+# Node.js
+node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+```
+
+### Token Rotation
+
+1. Generate new token
+2. Update all client configurations
+3. Update server environment variable
+4. Restart server
+5. Verify all clients work with new token
+
+### Network Security
+
+- Use HTTPS in production
+- Implement rate limiting at reverse proxy level
+- Monitor for unusual usage patterns
+- Keep logs for security auditing
+
+## Troubleshooting
+
+### Common Connection Issues
+
+1. **"Connection refused"**
+   - Check if server is running: `curl http://localhost:7860`
+   - Verify port is not blocked by firewall
+
+2. **"Invalid API key"**
+   - Ensure `X-Api-Key` header is included
+   - Check token matches `MCP_TOKEN` environment variable
+   - Verify no extra spaces or characters in token
+
+3. **"Request timeout"**
+   - Check server logs for errors
+   - Verify network connectivity
+   - Increase client timeout settings
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+export DEBUG=true
+export LOG_LEVEL=DEBUG
+python app.py
+```
+
+This will show detailed logs of all MCP requests and responses.
+
+## Roo Code Assistant
+
+### Configuration
+
+Roo uses MCP servers automatically when they're running locally. Simply start the Proportio server:
+
+```bash
+python app.py
+```
+
+Roo will detect the running MCP server at `http://localhost:7860/gradio_api/mcp/sse` and make the tools available.
+
+### Usage Examples
+
+```
+Human: Calculate what percentage 45 is of 180
+
+Roo: I'll use the proportion calculator to find what percentage 45 is of 180.
+
+[Using percent_of tool with part=45, whole=180]
+
+45 is 25% of 180.
+```
+
+```
+Human: I need to resize an image from 1920x1080 to half the size
+
+Roo: I'll help you calculate the new dimensions using the resize tool.
+
+[Using resize_dimensions tool with width=1920, height=1080, scale=0.5]
+
+The new dimensions would be 960 × 540 pixels.
+```
+
+## OpenWebUI
+
+### Configuration File
+
+Add to your OpenWebUI configuration (`config.yaml` or environment):
+
+```yaml
+mcp:
+  servers:
+    proportio:
+      url: "http://localhost:7860/gradio_api/mcp/sse"
+      headers:
+        X-Api-Key: "your-secure-token-here"
+      tools:
+        - percent_of
+        - solve_proportion
+        - scale_by_ratio
+        - direct_k
+        - resize_dimensions
+```
+
+### Environment Variables
+
+```bash
+# OpenWebUI MCP configuration
+OPENWEBUI_MCP_SERVERS='[
+  {
+    "name": "proportio",
+    "url": "http://localhost:7860/gradio_api/mcp/sse",
+    "headers": {"X-Api-Key": "your-secure-token-here"}
+  }
+]'
+```
+
+### Docker Compose with OpenWebUI
+
+```yaml
+version: '3.8'
+services:
+  proportio:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - MCP_TOKEN=your-secure-token-here
+    networks:
+      - webui_network
+
+  openwebui:
+    image: ghcr.io/open-webui/open-webui:main
+    ports:
+      - "3000:8080"
+    environment:
+      - OPENWEBUI_MCP_SERVERS=[{"name":"proportio","url":"http://proportio:7860/gradio_api/mcp/sse","headers":{"X-Api-Key":"your-secure-token-here"}}]
+    depends_on:
+      - proportio
+    networks:
+      - webui_network
+
+networks:
+  webui_network:
+    driver: bridge
+```
+
+## Msty
+
+### Configuration
+
+In Msty's settings, add the MCP server:
+
+```json
+{
+  "mcp_servers": {
+    "proportio": {
+      "type": "sse",
+      "url": "http://localhost:7860/gradio_api/mcp/sse",
+      "auth": {
+        "type": "header",
+        "header_name": "X-Api-Key",
+        "header_value": "your-secure-token-here"
+      },
+      "description": "Mathematical proportion calculations"
+    }
+  }
+}
+```
+
+### Using with Msty
+
+1. Start the Proportio server: `python app.py`
+2. Open Msty and go to Settings → MCP Servers
+3. Add a new server with the configuration above
+4. The tools will be available in chat sessions
+
+### Example Msty Usage
+
+```
+You: I need to solve this proportion: 3/4 = x/12. What is x?
+
+Msty: I'll use the proportion solver to find the missing value.
+
+[Using solve_proportion tool]
+
+The missing value x is 9. So 3/4 = 9/12.
+```
+
+## Local Development Setup Script
+
+Create a setup script for easy local development:
+
+```bash
+#!/bin/bash
+# setup_local_mcp.sh
+
+# Generate secure token
+TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
+
+# Create .env file
+cat > .env << EOF
+MCP_TOKEN=$TOKEN
+DEBUG=true
+LOG_LEVEL=DEBUG
+RELOAD=true
+EOF
+
+echo "Generated secure token: $TOKEN"
+echo "Add this to your MCP clients' X-Api-Key header"
+
+# Start the server
+python app.py
+```
+
+Make it executable: `chmod +x setup_local_mcp.sh`
+
+## Testing Your MCP Connection
+
+### Quick Test Script
+
+```python
+#!/usr/bin/env python3
+"""Test script for Proportio MCP server connection"""
+
+import requests
+import json
+import sys
+
+def test_mcp_connection(base_url="http://localhost:7860", api_key="your-token"):
+    """Test MCP server connection and tools."""
+    
+    url = f"{base_url}/gradio_api/mcp/sse"
+    headers = {
+        "X-Api-Key": api_key,
+        "Content-Type": "application/json"
+    }
+    
+    # Test cases
+    tests = [
+        {
+            "name": "Percentage Calculation",
+            "tool": "percent_of",
+            "args": {"part": 25, "whole": 100},
+            "expected": 25.0
+        },
+        {
+            "name": "Proportion Solving",
+            "tool": "solve_proportion", 
+            "args": {"a": 3, "b": 4, "c": 6, "d": None},
+            "expected": 8.0
+        },
+        {
+            "name": "Dimension Resizing",
+            "tool": "resize_dimensions",
+            "args": {"width": 100, "height": 50, "scale": 2.0},
+            "expected": {"new_width": 200.0, "new_height": 100.0}
+        }
+    ]
+    
+    print(f"Testing MCP server at {url}")
+    print(f"Using API key: {api_key[:8]}...")
+    print("-" * 50)
+    
+    for test in tests:
+        try:
+            payload = {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "tools/call",
+                "params": {
+                    "name": test["tool"],
+                    "arguments": test["args"]
+                }
+            }
+            
+            response = requests.post(url, headers=headers, json=payload, timeout=10)
+            
+            if response.status_code == 200:
+                result = response.json()
+                print(f"✅ {test['name']}: PASSED")
+                print(f"   Result: {result}")
+            else:
+                print(f"❌ {test['name']}: FAILED (HTTP {response.status_code})")
+                print(f"   Response: {response.text}")
+                
+        except Exception as e:
+            print(f"❌ {test['name']}: ERROR - {str(e)}")
+        
+        print()
+
+if __name__ == "__main__":
+    api_key = input("Enter your API key (or press Enter for 'test-token'): ").strip()
+    if not api_key:
+        api_key = "test-token"
+    
+    test_mcp_connection(api_key=api_key)
+```
+
+Save as `test_mcp.py` and run: `python test_mcp.py`
+
+This comprehensive guide covers all major MCP clients including Roo, OpenWebUI, and Msty, providing practical examples for integrating the Proportio server into your development workflow.

models.py

@@ -0,0 +1,96 @@
+"""
+Pydantic models for proportion calculation inputs and outputs.
+Provides robust validation and clear error messages.
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field, model_validator
+
+
+class PercentOfInput(BaseModel):
+    """Input for calculating what percentage part is of whole."""
+    
+    part: float = Field(description="The part value")
+    whole: float = Field(description="The whole value (must not be zero)")
+    
+
+
+class PercentOfOutput(BaseModel):
+    """Output for percentage calculation."""
+    
+    percentage: float = Field(description="The calculated percentage")
+
+
+class ProportionInput(BaseModel):
+    """Input for solving proportion a/b = c/d with exactly one missing value."""
+    
+    a: Optional[float] = Field(None, description="First numerator")
+    b: Optional[float] = Field(None, description="First denominator")  
+    c: Optional[float] = Field(None, description="Second numerator")
+    d: Optional[float] = Field(None, description="Second denominator")
+    
+    @model_validator(mode='after')
+    def validate_exactly_one_none(self) -> 'ProportionInput':
+        """Ensure exactly one value is None (missing)."""
+        values = [self.a, self.b, self.c, self.d]
+        none_count = sum(1 for v in values if v is None)
+        
+        assert none_count == 1, "Exactly one value must be None (missing) to solve proportion"
+        
+        return self
+
+
+class ProportionOutput(BaseModel):
+    """Output for proportion calculation."""
+    
+    missing: float = Field(description="The calculated missing value")
+
+
+class ScaleByRatioInput(BaseModel):
+    """Input for scaling a value by a ratio."""
+    
+    value: float = Field(description="The value to scale")
+    ratio: float = Field(description="The scaling ratio")
+
+
+class ScaleByRatioOutput(BaseModel):
+    """Output for ratio scaling."""
+    
+    result: float = Field(description="The scaled result")
+
+
+class DirectKInput(BaseModel):
+    """Input for finding constant of proportionality k in y = kx."""
+    
+    x: float = Field(description="The x value (cannot be zero)")
+    y: float = Field(description="The y value")
+    
+
+
+class DirectKOutput(BaseModel):
+    """Output for proportionality constant calculation."""
+    
+    k: float = Field(description="The proportionality constant")
+
+
+class ResizeDimensionsInput(BaseModel):
+    """Input for resizing dimensions with uniform scale factor."""
+    
+    width: float = Field(description="Original width (must be non-negative)")
+    height: float = Field(description="Original height (must be non-negative)")
+    scale: float = Field(description="Scale factor (must be positive)")
+
+
+class ResizeDimensionsOutput(BaseModel):
+    """Output for dimension resizing."""
+    
+    new_width: float = Field(description="The new width after scaling")
+    new_height: float = Field(description="The new height after scaling")
+
+
+# Error response model for consistent error handling
+class ErrorResponse(BaseModel):
+    """Standard error response format."""
+    
+    error: str = Field(description="Error message")
+    detail: Optional[str] = Field(None, description="Additional error details")

proportion_server.py

@@ -0,0 +1,361 @@
+"""
+Core proportion calculation tools with Gradio MCP server capabilities.
+Provides reliable mathematical operations for LLM agents.
+"""
+
+import logging
+from typing import Optional, Tuple
+import gradio as gr
+
+from config import get_settings, setup_logging, get_deployment_info
+
+# Setup logging
+setup_logging()
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+def percent_of(part: float, whole: float) -> float:
+    """
+    Calculate what percentage 'part' is of 'whole'.
+    
+    Args:
+        part: The part value
+        whole: The whole value (must not be zero)
+        
+    Returns:
+        The percentage value
+    
+    Mathematical preconditions:
+        - whole != 0 (to avoid division by zero)
+    """
+    # Mathematical preconditions
+    assert whole != 0, "Division by zero: whole cannot be zero"
+    
+    # Calculate percentage
+    percentage = (part / whole) * 100
+    
+    logger.debug(f"Calculated {part} is {percentage:.2f}% of {whole}")
+    
+    return percentage
+
+
+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.
+    Exactly one parameter must be None (missing).
+    
+    Args:
+        a: First numerator (optional)
+        b: First denominator (optional, cannot be zero)
+        c: Second numerator (optional)
+        d: Second denominator (optional, cannot be zero)
+        
+    Returns:
+        The missing value
+    
+    Mathematical preconditions:
+        - Exactly one value must be None (missing)
+        - Division denominators != 0 (varies by missing value)
+    """
+    # Mathematical preconditions - exactly one value must be None
+    values = [a, b, c, d]
+    none_count = sum(1 for v in values if v is None)
+    assert none_count == 1, "Exactly one value must be None"
+    
+    # Solve for missing value using cross multiplication: a*d = b*c
+    if a is None:
+        assert d != 0, "Division by zero: denominator"
+        missing = (b * c) / d
+    elif b is None:
+        assert c != 0, "Division by zero: denominator"
+        missing = (a * d) / c
+    elif c is None:
+        assert b != 0, "Division by zero: denominator"
+        missing = (a * d) / b
+    else:  # d is None
+        assert a != 0, "Division by zero: denominator"
+        missing = (b * c) / a
+    
+    logger.debug(f"Solved proportion: missing value = {missing}")
+    
+    return missing
+
+
+def scale_by_ratio(value: float, ratio: float) -> float:
+    """
+    Scale a value by a given ratio.
+    
+    Args:
+        value: The value to scale
+        ratio: The scaling ratio
+        
+    Returns:
+        The scaled value
+    """
+    # Calculate scaled result
+    scaled_result = value * ratio
+    
+    logger.debug(f"Scaled {value} by ratio {ratio} = {scaled_result}")
+    
+    return scaled_result
+
+
+def direct_k(x: float, y: float) -> float:
+    """
+    Find constant of proportionality k in direct variation y = kx.
+    
+    Args:
+        x: The x value (cannot be zero)
+        y: The y value
+        
+    Returns:
+        The proportionality constant k
+    
+    Mathematical preconditions:
+        - x != 0 (to avoid division by zero)
+    """
+    # Mathematical preconditions
+    assert x != 0, "Division by zero: x cannot be zero"
+    
+    # Calculate proportionality constant
+    k = y / x
+    
+    logger.debug(f"Found proportionality constant k = {k} for y = {y}, x = {x}")
+    
+    return k
+
+
+def resize_dimensions(width: float, height: float, scale: float) -> Tuple[float, float]:
+    """
+    Resize dimensions with uniform scale factor.
+
+    Args:
+        width: Original width (must be non-negative)
+        height: Original height (must be non-negative)
+        scale: Scale factor (must be positive)
+
+    Returns:
+        Tuple of (new_width, new_height)
+
+    Mathematical preconditions:
+        - width >= 0 (dimensions must be non-negative)
+        - height >= 0 (dimensions must be non-negative)
+        - scale > 0 (scale factor must be positive)
+    """
+    # Mathematical preconditions
+    assert width >= 0, "Width must be non-negative"
+    assert height >= 0, "Height must be non-negative"
+    assert scale > 0, "Scale factor must be positive"
+    
+    # Calculate new dimensions
+    new_width = width * scale
+    new_height = height * scale
+    
+    logger.debug(f"Resized {width}x{height} by {scale} = {new_width}x{new_height}")
+    
+    return (new_width, new_height)
+
+
+# Demo functions for Gradio interface
+def demo_percent_of(part: float, whole: float) -> str:
+    """Demo function for percent_of calculation."""
+    result = percent_of(part, whole)
+    return f"{part} is {result:.2f}% of {whole}"
+
+
+def demo_solve_proportion(a: Optional[str], b: Optional[str], c: Optional[str], d: Optional[str]) -> str:
+    """Demo function for proportion solving."""
+    # Convert string inputs to float or None
+    a_val = None if a == "" or a is None else float(a)
+    b_val = None if b == "" or b is None else float(b)
+    c_val = None if c == "" or c is None else float(c)
+    d_val = None if d == "" or d is None else float(d)
+    
+    result = solve_proportion(a_val, b_val, c_val, d_val)
+    return f"Missing value: {result:.4f}"
+
+
+def demo_scale_by_ratio(value: float, ratio: float) -> str:
+    """Demo function for scaling by ratio."""
+    result = scale_by_ratio(value, ratio)
+    return f"{value} × {ratio} = {result:.4f}"
+
+
+def demo_direct_k(x: float, y: float) -> str:
+    """Demo function for finding proportionality constant."""
+    result = direct_k(x, y)
+    return f"k = {result:.4f} (where y = kx)"
+
+
+def demo_resize_dimensions(width: float, height: float, scale: float) -> str:
+    """Demo function for resizing dimensions."""
+    new_width, new_height = resize_dimensions(width, height, scale)
+    return f"New dimensions: {new_width:.2f} × {new_height:.2f}"
+
+
+def create_gradio_app():
+    """Create and return the Gradio interface."""
+    with gr.Blocks(
+        title="PROPORTIO",
+        css_paths=["styles.css"],
+        theme=gr.themes.Base(),
+        head='<link rel="icon" type="image/png" href="/file=logo.png"><link rel="shortcut icon" type="image/png" href="/file=logo.png">'
+    ) as demo:
+        with gr.Row():
+            with gr.Column(scale=1, min_width=72):
+                gr.Image("logo.png", height=72, width=72, show_label=False, show_download_button=False, show_fullscreen_button=False, container=False, interactive=False)
+            with gr.Column(scale=10):
+                gr.HTML("""
+                <div class="p-brand">
+                    <h1 class="p-title">PROPORTIO</h1>
+                    <div class="p-tagline">Mathematical Precision & Proportion Calculator</div>
+                </div>
+                """)
+        
+        with gr.Tabs():
+            with gr.TabItem("📊 Percentage Calculator"):
+                gr.HTML('<div class="tab-title">Calculate Percentage</div>')
+                gr.HTML('<div class="tab-desc">Find what percentage the part is of the whole</div>')
+                
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        part_input = gr.Number(label="Part", value=25, info="The part value")
+                        whole_input = gr.Number(label="Whole", value=100, info="The whole value (cannot be zero)")
+                        percent_btn = gr.Button("Calculate Percentage", variant="secondary", size="lg")
+                    
+                    with gr.Column(scale=1):
+                        percent_output = gr.Textbox(label="Result", interactive=False, show_label=True)
+                        gr.HTML('<div class="formula-box"><strong>Formula:</strong> (Part ÷ Whole) × 100</div>')
+            
+            with gr.TabItem("⚖️ Proportion Solver"):
+                gr.HTML('<div class="tab-title">Solve Proportion (a/b = c/d)</div>')
+                gr.HTML('<div class="tab-desc">Leave exactly one field empty to solve for the missing value</div>')
+                
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        with gr.Row():
+                            a_input = gr.Textbox(label="a", value="3", info="First numerator")
+                            b_input = gr.Textbox(label="b", value="4", info="First denominator")
+                        with gr.Row():
+                            c_input = gr.Textbox(label="c", value="6", info="Second numerator")
+                            d_input = gr.Textbox(label="d", value="", info="Second denominator")
+                        proportion_btn = gr.Button("Solve Proportion", variant="secondary", size="lg")
+                    
+                    with gr.Column(scale=1):
+                        proportion_output = gr.Textbox(label="Result", interactive=False, show_label=True)
+                        gr.HTML('<div class="formula-box"><strong>Formula:</strong> a × d = b × c</div>')
+            
+            with gr.TabItem("📏 Scale by Ratio"):
+                gr.HTML('<div class="tab-title">Scale Value by Ratio</div>')
+                gr.HTML('<div class="tab-desc">Multiply a value by a scaling ratio</div>')
+                
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        value_input = gr.Number(label="Value", value=10, info="The value to scale")
+                        ratio_input = gr.Number(label="Ratio", value=1.5, info="The scaling factor")
+                        scale_btn = gr.Button("Scale Value", variant="secondary", size="lg")
+                    
+                    with gr.Column(scale=1):
+                        scale_output = gr.Textbox(label="Result", interactive=False, show_label=True)
+                        gr.HTML('<div class="formula-box"><strong>Formula:</strong> Value × Ratio</div>')
+            
+            with gr.TabItem("🔢 Find Constant k"):
+                gr.HTML('<div class="tab-title">Find Proportionality Constant (y = kx)</div>')
+                gr.HTML('<div class="tab-desc">Calculate the constant k in direct variation</div>')
+                
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        x_input = gr.Number(label="x", value=5, info="The x value (cannot be zero)")
+                        y_input = gr.Number(label="y", value=15, info="The y value")
+                        direct_btn = gr.Button("Find k", variant="secondary", size="lg")
+                    
+                    with gr.Column(scale=1):
+                        direct_output = gr.Textbox(label="Result", interactive=False, show_label=True)
+                        gr.HTML('<div class="formula-box"><strong>Formula:</strong> k = y ÷ x</div>')
+            
+            with gr.TabItem("📐 Resize Dimensions"):
+                gr.HTML('<div class="tab-title">Resize Dimensions</div>')
+                gr.HTML('<div class="tab-desc">Scale width and height by a uniform factor</div>')
+                
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        width_input = gr.Number(label="Width", value=100, info="Original width (≥ 0)")
+                        height_input = gr.Number(label="Height", value=50, info="Original height (≥ 0)")
+                        scale_dim_input = gr.Number(label="Scale Factor", value=2.0, info="Scaling factor (> 0)")
+                        resize_btn = gr.Button("Resize", variant="secondary", size="lg")
+                    
+                    with gr.Column(scale=1):
+                        resize_output = gr.Textbox(label="Result", interactive=False, show_label=True)
+                        gr.HTML('<div class="formula-box"><strong>Formula:</strong> New = Original × Scale</div>')
+        
+        # Event handlers
+        percent_btn.click(
+            demo_percent_of,
+            inputs=[part_input, whole_input],
+            outputs=[percent_output]
+        )
+        
+        proportion_btn.click(
+            demo_solve_proportion,
+            inputs=[a_input, b_input, c_input, d_input],
+            outputs=[proportion_output]
+        )
+        
+        scale_btn.click(
+            demo_scale_by_ratio,
+            inputs=[value_input, ratio_input],
+            outputs=[scale_output]
+        )
+        
+        direct_btn.click(
+            demo_direct_k,
+            inputs=[x_input, y_input],
+            outputs=[direct_output]
+        )
+        
+        resize_btn.click(
+            demo_resize_dimensions,
+            inputs=[width_input, height_input, scale_dim_input],
+            outputs=[resize_output]
+        )
+        
+        gr.HTML("""
+        <div class="footer">
+            <div class="footer-content">
+                <div class="footer-section">
+                    <div class="footer-title">About</div>
+                    <div class="footer-text">Professional mathematical calculations for proportions, percentages, and scaling operations.</div>
+                </div>
+                <div class="footer-section">
+                    <div class="footer-title">Features</div>
+                    <div class="footer-text">• Assertion-based validation<br>• Precise error handling<br>• MCP server integration</div>
+                </div>
+            </div>
+        </div>
+        """)
+    
+    return demo
+
+
+if __name__ == "__main__":
+    # Get deployment info
+    deployment_info = get_deployment_info()
+    logger.info(f"Starting Proportio Calculator - {deployment_info}")
+    
+    # Create and launch the interface
+    demo = create_gradio_app()
+    
+    # Launch with MCP server capabilities
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=settings.PORT,
+        share=settings.SHARE,
+        mcp_server=True,  # Enable MCP server functionality
+        show_error=True
+    )

pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "proportio-mcp-server"
+version = "1.0.0"
+description = "Gradio-hosted MCP server for reliable proportion calculations"
+authors = [{name = "Proportio Team"}]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "gradio[mcp]>=5.0.0",
+    "pydantic>=2.8.0",
+    "pytest>=8.0.0",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py311']
+include = '\.pyi?$'
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = []
+
+[tool.ruff.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+]

requirements.txt

@@ -0,0 +1,9 @@
+# Core dependencies
+gradio[mcp]>=5.0.0
+pydantic>=2.8.0
+pydantic-settings>=2.0.0
+websockets>=13.0,<14.0
+requests>=2.31.0
+
+# Testing
+pytest>=8.0.0

styles.css

@@ -0,0 +1,148 @@
+/* ---------- Proportio Minimal Theme ---------- */
+:root{
+  --primary: #7c1212;
+  --secondary: #a10907;
+  --accent: #8f9190;
+}
+
+/* Logo visibility and alignment fix */
+.gradio-row {
+  display: flex !important;
+  align-items: center !important;
+  gap: 16px !important;
+}
+
+.gradio-column {
+  display: flex !important;
+  align-items: center !important;
+  height: auto !important;
+}
+
+/* Target the first column (logo) */
+.gradio-column:first-child {
+  justify-content: center !important;
+  align-items: center !important;
+}
+
+/* Target the second column (text) */
+.gradio-column:last-child {
+  justify-content: flex-start !important;
+  align-items: center !important;
+}
+
+.gradio-image {
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  margin: 0 !important;
+  padding: 0 !important;
+}
+
+.gradio-image img {
+  display: block !important;
+  opacity: 1 !important;
+  visibility: visible !important;
+}
+
+/* Ensure the brand section is vertically centered */
+.p-brand {
+  display: flex !important;
+  flex-direction: column !important;
+  justify-content: center !important;
+  margin: 0 !important;
+  padding: 0 !important;
+}
+
+.p-title {
+  margin: 0 !important;
+  line-height: 1.2 !important;
+}
+
+.p-tagline {
+  margin: 0 !important;
+  line-height: 1.2 !important;
+}
+
+/* Override blue colors with primary red */
+.gradio-tabs button {
+  background-color: var(--primary) !important;
+  border-color: var(--primary) !important;
+}
+
+.gradio-tabs button:hover {
+  background-color: var(--secondary) !important;
+  border-color: var(--secondary) !important;
+}
+
+.gradio-tabs button[aria-selected="true"] {
+  background-color: var(--primary) !important;
+  border-color: var(--primary) !important;
+  color: var(--accent) !important;
+}
+
+.gradio-tabs button[aria-selected="true"] span {
+  color: var(--accent) !important;
+}
+
+/* Override any blue accents */
+.tab-nav button {
+  background-color: var(--primary) !important;
+  border-color: var(--primary) !important;
+}
+
+/* Target selected tab text colors */
+button[role="tab"][aria-selected="true"] {
+  color: var(--accent) !important;
+}
+
+button[role="tab"][aria-selected="true"] span {
+  color: var(--accent) !important;
+}
+
+/* Override blue text in tabs */
+.gradio-tabs button span {
+  color: var(--accent) !important;
+}
+
+/* Override blue underlines/borders on selected tabs */
+.gradio-tabitem,
+.gradio-tabs .tab-nav button[aria-selected="true"]::after,
+.gradio-tabs button[aria-selected="true"]::after,
+button[role="tab"][aria-selected="true"]::after {
+  border-bottom-color: var(--secondary) !important;
+  background-color: var(--secondary) !important;
+}
+
+/* Target the tab indicator line - more specific selectors */
+.gradio-tabs .tab-nav .tab-indicator,
+.gradio-tabs .selected-tab-indicator,
+.gradio-tabs button[aria-selected="true"] + .tab-indicator,
+.gradio-tabs button[aria-selected="true"]::before,
+.gradio-tabs button[data-selected="true"]::before,
+div[role="tablist"] button[aria-selected="true"]::before,
+div[role="tablist"] button[aria-selected="true"]::after,
+.gradio-tabs .tab-nav button::before,
+.gradio-tabs .tab-nav button::after {
+  background-color: var(--secondary) !important;
+  border-color: var(--secondary) !important;
+  background: var(--secondary) !important;
+}
+
+/* Override any remaining blue accents - comprehensive approach */
+.gradio-tabs button[aria-selected="true"] {
+  border-bottom: 2px solid var(--secondary) !important;
+  box-shadow: inset 0 -2px 0 var(--secondary) !important;
+}
+
+/* Target Gradio's internal tab styling */
+.gradio-tabs button[data-selected="true"],
+button[role="tab"][data-selected="true"] {
+  border-bottom-color: var(--secondary) !important;
+  box-shadow: inset 0 -2px 0 var(--secondary) !important;
+}
+
+/* Override blue focus states */
+.gradio-tabs button:focus {
+  outline-color: var(--secondary) !important;
+  border-color: var(--secondary) !important;
+}

tests/test_tools.py

@@ -0,0 +1,428 @@
+"""
+Comprehensive test suite for proportion calculation tools.
+Tests all functions with various inputs, edge cases, and error conditions.
+"""
+
+import pytest
+from proportion_server import (
+    percent_of, solve_proportion, scale_by_ratio, 
+    direct_k, resize_dimensions
+)
+
+
+class TestPercentOf:
+    """Test the percent_of function."""
+    
+    def test_basic_percentage(self):
+        """Test basic percentage calculations."""
+        assert percent_of(25, 100) == 25.0
+        assert percent_of(1, 4) == 25.0
+        assert percent_of(3, 4) == 75.0
+        
+    def test_zero_part(self):
+        """Test with zero part."""
+        assert percent_of(0, 100) == 0.0
+        assert percent_of(0, 1) == 0.0
+        
+    def test_negative_values(self):
+        """Test with negative values."""
+        assert percent_of(-25, 100) == -25.0
+        assert percent_of(25, -100) == -25.0
+        assert percent_of(-25, -100) == 25.0
+        
+    def test_decimal_precision(self):
+        """Test decimal precision in calculations."""
+        result = percent_of(1, 3)
+        assert abs(result - 33.333333333333336) < 1e-10
+        
+    def test_large_numbers(self):
+        """Test with large numbers."""
+        assert percent_of(1000000, 4000000) == 25.0
+        
+    def test_very_small_numbers(self):
+        """Test with very small numbers."""
+        result = percent_of(1e-10, 1e-8)
+        assert abs(result - 1.0) < 1e-10
+        
+    def test_zero_whole_error(self):
+        """Test assertion error when whole is zero."""
+        with pytest.raises(AssertionError, match="Division by zero: whole cannot be zero"):
+            percent_of(10, 0)
+            
+    def test_negative_whole_edge_cases(self):
+        """Test edge cases with negative whole values."""
+        assert percent_of(10, -5) == -200.0
+        assert percent_of(-10, -5) == 200.0
+
+
+class TestSolveProportion:
+    """Test the solve_proportion function."""
+    
+    def test_solve_a(self):
+        """Test solving for 'a' in proportion a/b = c/d."""
+        result = solve_proportion(None, 4, 6, 8)
+        assert result == 3.0
+        
+    def test_solve_b(self):
+        """Test solving for 'b' in proportion a/b = c/d."""
+        result = solve_proportion(3, None, 6, 8)
+        assert result == 4.0
+        
+    def test_solve_c(self):
+        """Test solving for 'c' in proportion a/b = c/d."""
+        result = solve_proportion(3, 4, None, 8)
+        assert result == 6.0
+        
+    def test_solve_d(self):
+        """Test solving for 'd' in proportion a/b = c/d."""
+        result = solve_proportion(3, 4, 6, None)
+        assert result == 8.0
+        
+    def test_negative_values(self):
+        """Test with negative values."""
+        result = solve_proportion(-3, 4, 6, None)
+        assert result == -8.0
+        
+    def test_decimal_results(self):
+        """Test with decimal results."""
+        result = solve_proportion(1, 3, 2, None)
+        assert abs(result - 6.0) < 1e-10
+        
+    def test_multiple_none_error(self):
+        """Test assertion error when multiple values are None."""
+        with pytest.raises(AssertionError, match="Exactly one value must be None"):
+            solve_proportion(None, None, 6, 8)
+        
+        with pytest.raises(AssertionError, match="Exactly one value must be None"):
+            solve_proportion(None, 4, None, 8)
+        
+        with pytest.raises(AssertionError, match="Exactly one value must be None"):
+            solve_proportion(None, None, None, None)
+    
+    def test_no_none_error(self):
+        """Test assertion error when no values are None."""
+        with pytest.raises(AssertionError, match="Exactly one value must be None"):
+            solve_proportion(3, 4, 6, 8)
+    
+    def test_zero_denominator_error(self):
+        """Test assertion error when denominators are zero."""
+        with pytest.raises(AssertionError, match="Division by zero: denominator"):
+            solve_proportion(None, 2, 3, 0)  # Solving for a, divides by d=0
+        
+        with pytest.raises(AssertionError, match="Division by zero: denominator"):
+            solve_proportion(2, None, 0, 3)  # Solving for b, divides by c=0
+    
+    def test_division_by_zero_calculation(self):
+        """Test assertion error for division by zero during calculation."""
+        with pytest.raises(AssertionError, match="Division by zero: denominator"):
+            # This would require dividing by zero in calculation
+            solve_proportion(None, 4, 0, 0)
+    
+    def test_large_numbers(self):
+        """Test with large numbers."""
+        result = solve_proportion(1000000, 2000000, 500000, None)
+        assert result == 1000000.0
+        
+    def test_very_small_numbers(self):
+        """Test with very small numbers."""
+        result = solve_proportion(1e-10, 2e-10, 5e-11, None)
+        assert abs(result - 1e-10) < 1e-20
+
+
+class TestScaleByRatio:
+    """Test the scale_by_ratio function."""
+    
+    def test_positive_scaling(self):
+        """Test scaling with positive ratios."""
+        assert scale_by_ratio(10, 2.5) == 25.0
+        assert scale_by_ratio(100, 0.5) == 50.0
+        
+    def test_negative_values(self):
+        """Test scaling with negative values."""
+        assert scale_by_ratio(-10, 2.0) == -20.0
+        assert scale_by_ratio(10, -2.0) == -20.0
+        assert scale_by_ratio(-10, -2.0) == 20.0
+        
+    def test_zero_scaling(self):
+        """Test scaling with zero ratio."""
+        assert scale_by_ratio(100, 0) == 0.0
+        
+    def test_zero_value(self):
+        """Test scaling zero value."""
+        assert scale_by_ratio(0, 5.0) == 0.0
+        
+    def test_identity_scaling(self):
+        """Test scaling with ratio of 1."""
+        assert scale_by_ratio(42, 1.0) == 42.0
+        
+    def test_fractional_scaling(self):
+        """Test scaling with fractional ratios."""
+        assert scale_by_ratio(9, 1/3) == 3.0
+        
+    def test_large_numbers(self):
+        """Test scaling with large numbers."""
+        result = scale_by_ratio(1e6, 1e-3)
+        assert result == 1000.0
+        
+    def test_very_small_numbers(self):
+        """Test scaling with very small numbers."""
+        result = scale_by_ratio(1e-10, 1e10)
+        assert result == 1.0
+        
+    def test_precision_edge_cases(self):
+        """Test precision with edge cases."""
+        result = scale_by_ratio(1/3, 3)
+        assert abs(result - 1.0) < 1e-15
+
+
+class TestDirectK:
+    """Test the direct_k function."""
+    
+    def test_positive_values(self):
+        """Test with positive values."""
+        assert direct_k(5, 15) == 3.0
+        assert direct_k(2, 10) == 5.0
+        
+    def test_negative_values(self):
+        """Test with negative values."""
+        assert direct_k(-4, 12) == -3.0
+        assert direct_k(4, -12) == -3.0
+        assert direct_k(-4, -12) == 3.0
+        
+    def test_zero_y(self):
+        """Test with zero y value."""
+        assert direct_k(5, 0) == 0.0
+        
+    def test_zero_x_error(self):
+        """Test assertion error when x is zero."""
+        with pytest.raises(AssertionError, match="Division by zero: x cannot be zero"):
+            direct_k(0, 10)
+            
+    def test_decimal_precision(self):
+        """Test decimal precision."""
+        result = direct_k(3, 1)
+        assert abs(result - 0.3333333333333333) < 1e-15
+        
+    def test_large_numbers(self):
+        """Test with large numbers."""
+        assert direct_k(1e6, 2e6) == 2.0
+        
+    def test_very_small_numbers(self):
+        """Test with very small numbers."""
+        result = direct_k(1e-10, 5e-10)
+        assert abs(result - 5.0) < 1e-10
+        
+    def test_fractional_results(self):
+        """Test fractional results."""
+        result = direct_k(7, 2)
+        assert abs(result - 2/7) < 1e-15
+
+
+class TestResizeDimensions:
+    """Test the resize_dimensions function."""
+    
+    def test_uniform_scaling(self):
+        """Test uniform scaling of dimensions."""
+        result = resize_dimensions(100, 50, 2.0)
+        assert result == (200.0, 100.0)
+        
+    def test_zero_dimensions(self):
+        """Test with zero dimensions."""
+        result = resize_dimensions(0, 0, 3.0)
+        assert result == (0.0, 0.0)
+        
+        result = resize_dimensions(100, 0, 2.0)
+        assert result == (200.0, 0.0)
+        
+    def test_identity_scaling(self):
+        """Test scaling with factor of 1."""
+        result = resize_dimensions(100, 50, 1.0)
+        assert result == (100.0, 50.0)
+        
+    def test_large_scaling(self):
+        """Test with large scale factors."""
+        result = resize_dimensions(10, 20, 100.0)
+        assert result == (1000.0, 2000.0)
+        
+    def test_small_scaling(self):
+        """Test with small scale factors."""
+        result = resize_dimensions(100, 200, 0.1)
+        assert result == (10.0, 20.0)
+        
+    def test_decimal_dimensions(self):
+        """Test with decimal dimensions."""
+        result = resize_dimensions(10.5, 20.7, 2.0)
+        assert result == (21.0, 41.4)
+    
+    def test_negative_dimensions_error(self):
+        """Test assertion error with negative dimensions."""
+        with pytest.raises(AssertionError, match="Width must be non-negative"):
+            resize_dimensions(-100, 50, 2.0)
+        
+        with pytest.raises(AssertionError, match="Height must be non-negative"):
+            resize_dimensions(100, -50, 2.0)
+        
+        with pytest.raises(AssertionError, match="Width must be non-negative"):
+            resize_dimensions(-100, -50, 2.0)
+    
+    def test_zero_scale_error(self):
+        """Test assertion error with zero scale factor."""
+        with pytest.raises(AssertionError, match="Scale factor must be positive"):
+            resize_dimensions(100, 50, 0)
+    
+    def test_negative_scale_error(self):
+        """Test assertion error with negative scale factor."""
+        with pytest.raises(AssertionError, match="Scale factor must be positive"):
+            resize_dimensions(100, 50, -1.5)
+        
+        with pytest.raises(AssertionError, match="Scale factor must be positive"):
+            resize_dimensions(100, 50, -0.1)
+    
+    def test_very_large_dimensions(self):
+        """Test with very large dimensions."""
+        result = resize_dimensions(1e6, 1e7, 0.001)
+        assert result == (1000.0, 10000.0)
+        
+    def test_precision_edge_cases(self):
+        """Test precision edge cases."""
+        result = resize_dimensions(1/3, 2/3, 3.0)
+        expected_width = (1/3) * 3.0
+        expected_height = (2/3) * 3.0
+        assert abs(result[0] - expected_width) < 1e-15
+        assert abs(result[1] - expected_height) < 1e-15
+
+
+class TestIntegration:
+    """Integration tests combining multiple functions."""
+    
+    def test_chained_calculations(self):
+        """Test chaining multiple calculations."""
+        # Start with a percentage
+        percent = percent_of(25, 100)  # 25%
+        
+        # Use result in proportion
+        result = solve_proportion(percent, 100, None, 200)  # 25/100 = x/200
+        assert result == 50.0
+        
+    def test_proportion_verification(self):
+        """Test proportion verification using cross multiplication."""
+        a, b, c = 3, 4, 6
+        d = solve_proportion(a, b, c, None)
+        
+        # Verify: a/b should equal c/d
+        ratio1 = a / b
+        ratio2 = c / d
+        assert abs(ratio1 - ratio2) < 1e-15
+        
+    def test_resize_and_scale_workflow(self):
+        """Test resizing and scaling workflow."""
+        # Original dimensions
+        width, height = 100, 50
+        
+        # Resize by factor of 2
+        new_width, new_height = resize_dimensions(width, height, 2.0)
+        assert new_width == 200.0
+        assert new_height == 100.0
+        
+        # Scale the area by ratio
+        original_area = width * height
+        new_area = new_width * new_height
+        area_ratio = new_area / original_area
+        assert area_ratio == 4.0  # 2^2 = 4
+        
+    def test_percentage_and_proportion_workflow(self):
+        """Test workflow combining percentages and proportions."""
+        # What percentage is 15 of 60?
+        percent = percent_of(15, 60)  # 25%
+        
+        # If 25% of some number is 30, what's the number?
+        result = solve_proportion(percent, 100, 30, None)
+        assert result == 120.0
+        
+    def test_scaling_chain(self):
+        """Test chain of scaling operations."""
+        value = 100
+        
+        # Scale by 1.5
+        value = scale_by_ratio(value, 1.5)  # 150
+        
+        # Scale by 2/3
+        value = scale_by_ratio(value, 2/3)  # 100
+        
+        # Should be back to original
+        assert abs(value - 100.0) < 1e-15
+        
+    def test_real_world_recipe_scaling(self):
+        """Test real-world recipe scaling scenario."""
+        # Original recipe serves 4, we want to serve 6
+        # Original calls for 2 cups flour
+        original_servings = 4
+        new_servings = 6
+        original_flour = 2
+        
+        # Find scaling ratio
+        ratio = new_servings / original_servings  # 1.5
+        
+        # Scale flour amount
+        new_flour = scale_by_ratio(original_flour, ratio)
+        assert new_flour == 3.0
+        
+        # Verify using proportion
+        flour_check = solve_proportion(original_flour, original_servings, None, new_servings)
+        assert flour_check == 3.0
+        
+    def test_financial_calculation_workflow(self):
+        """Test financial calculation workflow."""
+        # Investment grows from $1000 to $1250
+        initial = 1000
+        final = 1250
+        
+        # What's the growth percentage?
+        growth_amount = final - initial  # 250
+        growth_percent = percent_of(growth_amount, initial)  # 25%
+        
+        # Find the growth factor
+        growth_factor = direct_k(initial, final)  # 1.25
+        
+        # Verify by scaling
+        verification = scale_by_ratio(initial, growth_factor)
+        assert verification == final
+
+
+class TestErrorHandling:
+    """Test error handling and edge cases."""
+    
+    def test_type_validation_errors(self):
+        """Test that functions handle type validation properly."""
+        # These should work with int inputs (converted to float)
+        assert percent_of(1, 4) == 25.0
+        assert solve_proportion(1, 2, 3, None) == 6.0
+        assert scale_by_ratio(10, 2) == 20.0
+        assert direct_k(2, 6) == 3.0
+        assert resize_dimensions(10, 20, 2) == (20.0, 40.0)
+    
+    def test_boundary_conditions(self):
+        """Test mathematical boundary conditions."""
+        # Actual zero denominators should raise error
+        with pytest.raises(AssertionError):
+            percent_of(10, 0)
+        
+        # Very small but non-zero numbers should work
+        result = percent_of(10, 1e-100)
+        assert result == 1e103
+        
+        # Large numbers should work
+        result = percent_of(1e50, 1e60)
+        assert abs(result - 1e-8) < 1e-15
+    
+    def test_floating_point_precision_limits(self):
+        """Test floating point precision limits."""
+        # Very small numbers
+        result = scale_by_ratio(1e-300, 1e-300)
+        # Should not raise error, might be 0.0 due to underflow
+        assert isinstance(result, float)
+        
+        # Very large numbers
+        result = scale_by_ratio(1e100, 1e100)
+        # Should not raise error, might be inf due to overflow
+        assert isinstance(result, float)