______________________________________________________________________

标题：Proportio–精确比例计算器表情符号🧮 颜色来源：红色颜色To：灰色 sdk：毕业 app_file：app.py 固定：false 许可证：apache-2.0 标签：

mcp服务器
比例计算器
格拉迪奥
python
数学
llm工具

______________________________________________________________________

![License](LICENSE) ![Python](https://python.org) ](Dockerfile) ![Tests](tests/) ![MCP Server](https://modelcontextprotocol.io)

通过基于断言的验证和MCP服务器集成，对比例、百分比和缩放操作进行专业的数学计算。

______________________________________________________________________

现场演示

HF太空演示

______________________________________________________________________

🎯 概述

Proportio是一个专门的数学计算服务器，专为需要精确比例计算的LLM代理和应用程序而设计。内置于 基于断言的验证 和 零容忍误差处理，它通过web界面和模型上下文协议（MCP）集成提供可靠的数学运算。

关键用例

配方缩放：根据不同份量调整配料数量
财务计算：计算百分比、比率和比例增长
工程：调整尺寸、缩放测量值并保持比例关系
数据分析：计算百分比、比率和比例变换
LLM集成：通过MCP协议提供可靠的数学运算

______________________________________________________________________

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

______________________________________________________________________

✨ 特性

🔢 数学函数

百分比计算 -精确地将零件转换为百分比
比例求解 -解决a/b=c/d关系中的缺失项
比率度量 -按精确比率缩放值
比例常数 -在y=kx关系中找到k
尺寸调整 -宽度/高度对的均匀缩放

🛡️ 验证架构

基于断言的验证 -明确的数学前提条件
零异常处理 -无需尝试捕获块，快速故障检测
精确的错误消息 -清晰、可操作的错误描述
类型安全 -强大的输入验证和类型检查

🌐 集成选项

web界面 -基于Gradio的专业用户界面，具有自定义品牌
MCP服务器 -LLM代理的本地模型上下文协议支持
Docker就绪 -具有安全最佳实践的容器化部署
API访问 -具有全面文档的直接函数调用

🎨 专业设计

定制品牌 -红黑白主题，带几何标志
响应布局 -针对台式机和移动设备进行了优化
拆分结果 -输入/输出部分明确分离
错误处理 -用户友好的错误消息和验证

______________________________________________________________________

______________________________________________________________________

🚀 快速开始

使用Docker（推荐）

# 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

地方发展

# Install dependencies
pip install -r requirements.txt

# Run the server
python proportion_server.py

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

快速功能示例

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)

______________________________________________________________________

🔧 核心功能

1. `percent_of(part, whole)`

计算该部分占整体的百分比。

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

数学前提：

whole != 0 （除以零保护）

现实世界的例子：

销售转化率
测试分数百分比
增长率计算

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

按比例a/b=c/d求解缺失项（只有一个参数必须为None）。

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

数学前提：

只有一个值必须为None（缺失）
分裂的分母！=0（因缺失值而异）

现实世界的例子：

食谱缩放（4份：2杯=6份：？杯）
货币汇率
地图比例尺计算

3. `scale_by_ratio(value, ratio)`

按给定比率缩放值。

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

使用案例：

应用折扣百分比
缩放测量
财务计算

4. `direct_k(x, y)`

在直接变分y=kx中找到比例常数k。

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)

数学前提：

x != 0 （除以零保护）

应用：

物理计算（力=k×位移）
经济性（成本=k×数量）
工程（应力=k×应变）

5. `resize_dimensions(width, height, scale)`

使用统一的比例因子调整尺寸。

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)

数学前提：

width >= 0 （尺寸必须为非负）
height >= 0 （尺寸必须为非负）
scale > 0 （比例因子必须为正）

应用：

图像缩放
屏幕分辨率缩放
建筑图纸

______________________________________________________________________

🏗️ 建筑

基于断言的验证

Proportio用途 基于断言的验证 贯穿始终，提供了几个关键优势：

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

优点：

快速故障：通过精确的消息进行即时错误检测
无例外开销：零尝试捕获复杂性
明确前提条件：明确记录数学要求
可预测的行为：所有功能的一致错误处理

项目结构

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

依赖架构

简化依赖关系 （只需要3个）：

gradio[mcp]>=5.0.0 -具有MCP服务器功能的Web框架
pydantic>=2.8.0 -数据验证和解析
pytest>=8.0.0 -测试框架

错误处理原理

没有尝试捕捉块 -所有验证都是通过断言完成的：

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

______________________________________________________________________

📦 安装

系统要求

Python 3.11+
点包管理器
码头工人 （可选，用于容器化部署）

本地安装

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

开发安装

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

建造集装箱

# 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

集装箱特征

安全：非root用户执行
优化：单阶段构建，图像尺寸最小
灵活性：可配置的端口和环境设置
健康：自动流程管理

生产部署

# 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

______________________________________________________________________

🧪 测试

测试套件覆盖范围

58项综合测试 涵盖：

✅ 所有5个核心功能的基本功能
✅ 边缘情况和边界条件
✅ 错误处理和断言验证
✅ 集成工作流程和链式计算
✅ 浮点精度和数学精度
✅ 类型验证和输入净化

运行测试

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

模型上下文协议支持

Proportio提供本地 MCP服务器功能 实现无缝LLM集成：

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

与LLM代理一起使用

MCP服务器将所有数学函数作为LLM可以直接调用的工具公开：

可用的MCP工具：

percent_of -计算百分比关系
solve_proportion -解决缺失的比例项
scale_by_ratio -应用缩放比例
direct_k -找到比例常数
resize_dimensions -缩放维度对

MCP连接示例

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

集成优势

可靠的数学：LLM可以委派复杂的计算
错误处理：清除无效输入的错误消息
类型安全：自动输入验证和转换
演出：快速、直接的数学运算

______________________________________________________________________

📖 api参考

函数签名

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."""

错误消息

所有功能都提供清晰、可操作的错误消息：

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

返回类型

单一值: float 数学结果
尺寸对: Tuple[float, float] 宽度/高度
错误: AssertionError 带有描述性信息

______________________________________________________________________

🛠️ 发展

项目理念

基于断言的验证 -无需尝试捕捉复杂性
数学精度 -精确计算，前提条件明确
最小依赖性 -仅限基本套餐
综合测试 -边缘情况下的高测试覆盖率
专业设计 -干净、品牌化的用户界面

代码的风格

# 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

添加新功能

实施核心逻辑 -添加功能 proportion_server.py
添加数学前提条件 -明确记录约束
创建演示功能 -添加Gradio接口包装器
编写综合测试 -覆盖所有边缘案例
更新文档 -添加示例和用例

贡献指南

分叉存储库 -创建功能分支
遵循代码样式 -使用基于断言的验证
添加测试 -确保全面的测试覆盖率
更新文档 -保持README最新
提交拉取请求 -包括变更说明

______________________________________________________________________

📝 许可证

该项目根据 Apache许可证2.0 -看看许可证文件以获取详细信息。

关键许可点

✅ 商业用途 -在商业应用中使用
✅ 修改 -修改和分发更改
✅ 分布 -分发原始版本或修改后的版本
✅ 专利使用 -出资人授予专利权
⚠️ 归因 -必须包括许可和版权声明
⚠️ 状态变化 -必须记录修改

______________________________________________________________________

🤝 支持

获取帮助

问题:
文档：此README和内联代码文档
例子：参见 tests/test_tools.py 使用示例

贡献

我们欢迎捐款！请查看发展指南部分。

报告Bug

报告错误时，请包括：

环境详细信息 （Python版本、操作系统、Docker版本）
繁殖步骤 （最小代码示例）
预期行为与实际行为
错误消息 （全栈跟踪（如适用））

______________________________________________________________________

内置于❤️ 用于数学精度和LLM积分

*Proportio-数学与可靠性的结合*

proportio (Leksval)

快速接入

详细介绍

现场演示

🎯 概述

关键用例

✨ 特性

🔢 数学函数

🛡️ 验证架构

🌐 集成选项

🎨 专业设计

📋 目录

🚀 快速开始

使用Docker（推荐）

地方发展

快速功能示例

🔧 核心功能

1. percent_of(part, whole)

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

3. scale_by_ratio(value, ratio)

4. direct_k(x, y)

5. resize_dimensions(width, height, scale)

🏗️ 建筑

基于断言的验证

项目结构

依赖架构

错误处理原理

📦 安装

系统要求

本地安装

开发安装

🐳 Docker部署

建造集装箱

集装箱特征

生产部署

🧪 测试

测试套件覆盖范围

运行测试

测试类别

单元测试

集成测试

边缘案例测试

样本测试输出

🔌 MCP集成

模型上下文协议支持

与LLM代理一起使用

MCP连接示例

集成优势

📖 api参考

函数签名

错误消息

返回类型

🛠️ 发展

项目理念

代码的风格

添加新功能

贡献指南

📝 许可证

关键许可点

🤝 支持

获取帮助

贡献

报告Bug

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `percent_of(part, whole)`

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

3. `scale_by_ratio(value, ratio)`

4. `direct_k(x, y)`

5. `resize_dimensions(width, height, scale)`