avada-eval

Safe, Decimal-exact expression evaluator for LLM tools, derived from simpleeval.

安全、可扩展、给大模型当计算工具用的表达式求值器。派生自 simpleeval（v1.0.8，commit 3b30888d0d5954df8a11b7e5ef26d17e19a96c29，MIT，© 2013-2026 Daniel Fairhead）， 核心区别：用 decimal.Decimal 代替 float 做精确计算，并加固了资源耗尽（DoS）防护。

pip install avada-eval        # 或 uv add avada-eval

需要 Python ≥ 3.11；唯一运行时依赖 beartype（运行时类型检查，AVADA_BEARTYPE_ON=false 可关闭）。

快速示例

from avada_eval import simple_eval, SimpleEval  # 替换 `from simpleeval import ...`

simple_eval("0.1 + 0.2")  # Decimal('0.3')
simple_eval("1 / 3")  # Decimal('0.3333333333333333333333333333')
simple_eval("2 ** 100")  # 1267650600228229401496703205376（int 精确）
simple_eval("price * qty", names={"price": 19.99, "qty": 3})  # Decimal('59.97')

Decimal 语义（与 simpleeval 的差异）

默认 context：28 位有效数字、ROUND_HALF_EVEN、Emax/Emin = ±999999，InvalidOperation / DivisionByZero / Overflow 以异常抛出。设计决策见 ADR 0002。

LLM 工具用法（avada_eval.llm）

from avada_eval.llm import evaluate_for_llm, TOOL_DESCRIPTION

evaluate_for_llm("revenue * 12.5% + 1,000", {"revenue": 80000}).to_dict()
# {'ok': True, 'normalized': 'revenue * 0.125 + 1000', 'value': '11000.000', 'variables': {'revenue': '80000'}, ...}

• evaluate_for_llm 从不因表达式错误而抛异常：语法错误、未知名字、除零、安全拒绝等都以 ok=False + error / error_type 返回，模型可据此重试；TOOL_DESCRIPTION 可直接作为工具描述。 函数参数写错（pct_change(1)、round("x")）返回 InvalidArguments 等；库内部的意外异常也不外抛，而是记日志（logger avada_eval.llm.tool）并返回 ok=False、error="internal error: <类型>: <消息>"。
• sum / min / max / avg 可直接传数：sum(1, 2, 3)（该工具默认不支持列表字面量，列表只能经变量传入：sum(values)）。
• 财务函数：pct_change(new, old)、cagr(end, start, years)（均返回百分点）、ratio(a, b)、avg(...)。
• 千分位：逗号两侧无空格且分组合法（首组 1-3 位、其后每组 3 位）才视为千分位；逗号后带空格永远是参数分隔符（max(1, 234)）。
• 百分号：紧贴数字、且其后是结尾/空白/非操作数（) , * …）的 % 是百分号；10%3、10 % 3 仍是取模。

安全

安全模型继承 simpleeval 并只加强不削弱：禁止 _/func_ 前缀属性、format/format_map 等危险方法、DISALLOW_FUNCTIONS、模块访问（需显式 ModuleWrapper）、lambda / import / 赋值。

资源耗尽防护在分配或计算之前按估算值拦截（修复了 simpleeval 中 '%999999999d' % 1、f"{1:999999999}"、"a".center(999999999)、4000000 ** 4000000、 '%d' % 1e999999 等先分配/计算再检查的问题）。上限为 avada_eval.evaluator 的模块级常量，调用时读取：

import avada_eval.evaluator as evaluator

evaluator.MAX_FORMAT_WIDTH = 1000  # 与 simpleeval 一样，直接改模块属性

完整排查清单与拦不住的部分（表达式长度、推导式总内存、自定义 context 等）见 ADR 0003。 对不可信输入，仍建议限制表达式长度，并在带超时与内存上限的子进程中求值。

命令行

avada "0.1 + 0.2"
avada "round(x * 3, 1)" -v x=0.05 --rounding ROUND_HALF_UP
avada "a + 1,000" -v a=1.5 --json

开发

uv sync 后，make fmt 做格式化，./ci.sh（从仓库根运行）是唯一的零警告质量门： ruff format/check → mypy --strict → 结构检查 → 文档漂移 → pytest。

许可

MIT，见 LICENSE（保留 simpleeval 原版权声明）。