| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247 |
- """``calculator``:唯一允许产生“新数字”的工具,因此输入必须可溯源。
- 支持的运算:
- * ``sum`` / ``mean`` / ``median`` / ``min`` / ``max`` / ``count`` —— 统计;
- * ``growth``((本期/上期-1))、``ratio``(a/b)、``index``(a/b*1000)、``share``(a/合计);
- * ``expression`` —— 只允许数字、四则运算、括号和已绑定变量名(无函数、无属性访问)。
- 返回值同时给出 ``inputs``(每个输入值及其来源 call_id/row_hash)与
- ``_trace.calculation_id``;核验层据此验证“答案里的数字由这些输入算出”。
- """
- from __future__ import annotations
- import ast
- import hashlib
- import json
- import statistics
- from decimal import Decimal, DivisionByZero, InvalidOperation
- from .ledger import ledger
- from .objects import new_id
- ALLOWED_OPS = {"sum", "mean", "avg", "median", "min", "max", "count", "growth", "ratio", "index", "share", "expression"}
- class CalcError(ValueError):
- """计算参数非法。"""
- def _decimal(value: object) -> Decimal:
- if isinstance(value, Decimal):
- return value
- if isinstance(value, bool):
- raise CalcError("布尔值不能参与计算")
- try:
- return Decimal(str(value).replace(",", "").strip())
- except (InvalidOperation, AttributeError, ValueError) as error:
- raise CalcError(f"无法转换为数值: {value!r}") from error
- class _Evaluator(ast.NodeVisitor):
- """白名单式表达式求值(不使用 eval)。"""
- def __init__(self, variables: dict[str, Decimal]) -> None:
- self.variables = variables
- self.used: list[str] = []
- def evaluate(self, expression: str) -> Decimal:
- try:
- tree = ast.parse(expression, mode="eval")
- except SyntaxError as error:
- raise CalcError(f"表达式语法错误: {error.msg}") from error
- return self.visit(tree.body)
- def visit_BinOp(self, node: ast.BinOp): # noqa: N802
- left = self.visit(node.left)
- right = self.visit(node.right)
- if isinstance(node.op, ast.Add):
- return left + right
- if isinstance(node.op, ast.Sub):
- return left - right
- if isinstance(node.op, ast.Mult):
- return left * right
- if isinstance(node.op, ast.Div):
- if right == 0:
- raise CalcError("除数为 0")
- return left / right
- if isinstance(node.op, ast.Pow):
- return left**right
- if isinstance(node.op, ast.Mod):
- if right == 0:
- raise CalcError("取模的除数为 0")
- return left % right
- raise CalcError(f"不支持的运算符: {type(node.op).__name__}")
- def visit_UnaryOp(self, node: ast.UnaryOp): # noqa: N802
- value = self.visit(node.operand)
- if isinstance(node.op, ast.USub):
- return -value
- if isinstance(node.op, ast.UAdd):
- return value
- raise CalcError("不支持的一元运算")
- def visit_Constant(self, node: ast.Constant): # noqa: N802
- if isinstance(node.value, bool) or not isinstance(node.value, (int, float)):
- raise CalcError("表达式只允许数字常量")
- return _decimal(node.value)
- def visit_Name(self, node: ast.Name): # noqa: N802
- if node.id not in self.variables:
- raise CalcError(f"未绑定变量: {node.id}")
- self.used.append(node.id)
- return self.variables[node.id]
- def visit_Expression(self, node: ast.Expression): # noqa: N802
- return self.visit(node.body)
- def generic_visit(self, node): # noqa: D401
- raise CalcError(f"表达式包含不允许的语法: {type(node).__name__}")
- def _result_hash(payload: object) -> str:
- return "sha256:" + hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")).hexdigest()
- def calculate(
- op: str,
- inputs: list[dict] | None = None,
- expression: str | None = None,
- *,
- session_id: str = "",
- label: str = "",
- ) -> dict:
- """执行一次计算并登记台账。"""
- op = str(op or "sum").lower()
- if op not in ALLOWED_OPS:
- raise CalcError(f"不支持的运算: {op}(可用:{sorted(ALLOWED_OPS)})")
- inputs = inputs or []
- if not inputs and op not in ("expression",):
- raise CalcError("至少需要一个输入值")
- values: list[Decimal] = []
- enriched: list[dict] = []
- unverified = 0
- for index, item in enumerate(inputs):
- if isinstance(item, (int, float, str)):
- item = {"value": item}
- if not isinstance(item, dict):
- raise CalcError(f"第 {index + 1} 个输入格式错误")
- raw = item.get("value")
- if raw is None:
- raise CalcError(f"第 {index + 1} 个输入缺少 value")
- value = _decimal(raw)
- values.append(value)
- call_id = str(item.get("from_call_id") or "")
- row_hash = str(item.get("row_hash") or "")
- verified = False
- if call_id:
- entry = ledger.get(call_id)
- if entry:
- verified = True
- if row_hash:
- payload_text = json.dumps(entry["result"], ensure_ascii=False, default=str)
- verified = row_hash in payload_text
- if not verified:
- unverified += 1
- enriched.append(
- {
- "index": index,
- "label": str(item.get("label") or ""),
- "value": str(value),
- "from_call_id": call_id or None,
- "row_hash": row_hash or None,
- "verified": verified,
- }
- )
- variables = {chr(ord("a") + index): value for index, value in enumerate(values)}
- variables.update({f"v{index + 1}": value for index, value in enumerate(values)})
- if op in ("sum", "mean", "avg", "median", "min", "max", "count"):
- if op == "sum":
- result = sum(values)
- elif op in ("mean", "avg"):
- result = sum(values) / len(values)
- elif op == "median":
- result = _decimal(statistics.median(sorted(values)))
- elif op == "min":
- result = min(values)
- elif op == "max":
- result = max(values)
- else:
- result = _decimal(len(values))
- shown = f"{op}({', '.join(str(value) for value in values)})"
- elif op == "growth":
- if len(values) != 2:
- raise CalcError("growth 需要两个输入:[本期, 上期]")
- if values[1] == 0:
- raise CalcError("上期为 0,环比无法计算(按需求留空而不是填 0)")
- result = values[0] / values[1] - 1
- shown = f"({values[0]} / {values[1]} - 1)"
- elif op == "ratio":
- if len(values) != 2:
- raise CalcError("ratio 需要两个输入:[分子, 分母]")
- if values[1] == 0:
- raise CalcError("分母为 0,比值无法计算")
- result = values[0] / values[1]
- shown = f"({values[0]} / {values[1]})"
- elif op == "index":
- if len(values) != 2:
- raise CalcError("index 需要两个输入:[当期, 基期]")
- if values[1] == 0:
- raise CalcError("基期为 0,指数无法计算")
- result = values[0] / values[1] * Decimal(1000)
- shown = f"({values[0]} / {values[1]} * 1000)"
- elif op == "share":
- if len(values) < 2:
- raise CalcError("share 需要 [部分, 合计]")
- if values[1] == 0:
- raise CalcError("合计为 0,占比无法计算")
- result = values[0] / values[1]
- shown = f"({values[0]} / {values[1]})"
- else:
- if not expression:
- raise CalcError("expression 运算需要提供 expression")
- evaluator = _Evaluator(variables)
- result = evaluator.evaluate(expression)
- shown = expression
- if not result.is_finite():
- raise CalcError("计算结果不是有限数值")
- calculation_id = new_id("calc")
- input_signature = [{"value": str(value), "from_call_id": item["from_call_id"], "row_hash": item["row_hash"]} for value, item in zip(values, enriched)]
- trace = {
- "calculation_id": calculation_id,
- "result_hash": _result_hash({"result": str(result), "inputs": input_signature, "op": op}),
- "op": op,
- }
- payload = {
- "call_id": calculation_id,
- "tool": "calculator",
- "op": op,
- "label": label,
- "expression": shown,
- "result": str(result),
- "inputs": enriched,
- "unverified_inputs": unverified,
- "all_inputs_verified": unverified == 0,
- "_trace": trace,
- }
- ledger.record(
- calculation_id,
- "calculator",
- {"op": op, "inputs": inputs, "expression": expression, "label": label},
- payload,
- session_id=session_id,
- rows=[
- {
- "values": {"result": str(result)},
- "_trace": {"object_id": "", "table": "calculator", "row_index": -1, "row_hash": trace["result_hash"]},
- }
- ],
- )
- return payload
|