calc.py 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247
  1. """``calculator``:唯一允许产生“新数字”的工具,因此输入必须可溯源。
  2. 支持的运算:
  3. * ``sum`` / ``mean`` / ``median`` / ``min`` / ``max`` / ``count`` —— 统计;
  4. * ``growth``((本期/上期-1))、``ratio``(a/b)、``index``(a/b*1000)、``share``(a/合计);
  5. * ``expression`` —— 只允许数字、四则运算、括号和已绑定变量名(无函数、无属性访问)。
  6. 返回值同时给出 ``inputs``(每个输入值及其来源 call_id/row_hash)与
  7. ``_trace.calculation_id``;核验层据此验证“答案里的数字由这些输入算出”。
  8. """
  9. from __future__ import annotations
  10. import ast
  11. import hashlib
  12. import json
  13. import statistics
  14. from decimal import Decimal, DivisionByZero, InvalidOperation
  15. from .ledger import ledger
  16. from .objects import new_id
  17. ALLOWED_OPS = {"sum", "mean", "avg", "median", "min", "max", "count", "growth", "ratio", "index", "share", "expression"}
  18. class CalcError(ValueError):
  19. """计算参数非法。"""
  20. def _decimal(value: object) -> Decimal:
  21. if isinstance(value, Decimal):
  22. return value
  23. if isinstance(value, bool):
  24. raise CalcError("布尔值不能参与计算")
  25. try:
  26. return Decimal(str(value).replace(",", "").strip())
  27. except (InvalidOperation, AttributeError, ValueError) as error:
  28. raise CalcError(f"无法转换为数值: {value!r}") from error
  29. class _Evaluator(ast.NodeVisitor):
  30. """白名单式表达式求值(不使用 eval)。"""
  31. def __init__(self, variables: dict[str, Decimal]) -> None:
  32. self.variables = variables
  33. self.used: list[str] = []
  34. def evaluate(self, expression: str) -> Decimal:
  35. try:
  36. tree = ast.parse(expression, mode="eval")
  37. except SyntaxError as error:
  38. raise CalcError(f"表达式语法错误: {error.msg}") from error
  39. return self.visit(tree.body)
  40. def visit_BinOp(self, node: ast.BinOp): # noqa: N802
  41. left = self.visit(node.left)
  42. right = self.visit(node.right)
  43. if isinstance(node.op, ast.Add):
  44. return left + right
  45. if isinstance(node.op, ast.Sub):
  46. return left - right
  47. if isinstance(node.op, ast.Mult):
  48. return left * right
  49. if isinstance(node.op, ast.Div):
  50. if right == 0:
  51. raise CalcError("除数为 0")
  52. return left / right
  53. if isinstance(node.op, ast.Pow):
  54. return left**right
  55. if isinstance(node.op, ast.Mod):
  56. if right == 0:
  57. raise CalcError("取模的除数为 0")
  58. return left % right
  59. raise CalcError(f"不支持的运算符: {type(node.op).__name__}")
  60. def visit_UnaryOp(self, node: ast.UnaryOp): # noqa: N802
  61. value = self.visit(node.operand)
  62. if isinstance(node.op, ast.USub):
  63. return -value
  64. if isinstance(node.op, ast.UAdd):
  65. return value
  66. raise CalcError("不支持的一元运算")
  67. def visit_Constant(self, node: ast.Constant): # noqa: N802
  68. if isinstance(node.value, bool) or not isinstance(node.value, (int, float)):
  69. raise CalcError("表达式只允许数字常量")
  70. return _decimal(node.value)
  71. def visit_Name(self, node: ast.Name): # noqa: N802
  72. if node.id not in self.variables:
  73. raise CalcError(f"未绑定变量: {node.id}")
  74. self.used.append(node.id)
  75. return self.variables[node.id]
  76. def visit_Expression(self, node: ast.Expression): # noqa: N802
  77. return self.visit(node.body)
  78. def generic_visit(self, node): # noqa: D401
  79. raise CalcError(f"表达式包含不允许的语法: {type(node).__name__}")
  80. def _result_hash(payload: object) -> str:
  81. return "sha256:" + hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")).hexdigest()
  82. def calculate(
  83. op: str,
  84. inputs: list[dict] | None = None,
  85. expression: str | None = None,
  86. *,
  87. session_id: str = "",
  88. label: str = "",
  89. ) -> dict:
  90. """执行一次计算并登记台账。"""
  91. op = str(op or "sum").lower()
  92. if op not in ALLOWED_OPS:
  93. raise CalcError(f"不支持的运算: {op}(可用:{sorted(ALLOWED_OPS)})")
  94. inputs = inputs or []
  95. if not inputs and op not in ("expression",):
  96. raise CalcError("至少需要一个输入值")
  97. values: list[Decimal] = []
  98. enriched: list[dict] = []
  99. unverified = 0
  100. for index, item in enumerate(inputs):
  101. if isinstance(item, (int, float, str)):
  102. item = {"value": item}
  103. if not isinstance(item, dict):
  104. raise CalcError(f"第 {index + 1} 个输入格式错误")
  105. raw = item.get("value")
  106. if raw is None:
  107. raise CalcError(f"第 {index + 1} 个输入缺少 value")
  108. value = _decimal(raw)
  109. values.append(value)
  110. call_id = str(item.get("from_call_id") or "")
  111. row_hash = str(item.get("row_hash") or "")
  112. verified = False
  113. if call_id:
  114. entry = ledger.get(call_id)
  115. if entry:
  116. verified = True
  117. if row_hash:
  118. payload_text = json.dumps(entry["result"], ensure_ascii=False, default=str)
  119. verified = row_hash in payload_text
  120. if not verified:
  121. unverified += 1
  122. enriched.append(
  123. {
  124. "index": index,
  125. "label": str(item.get("label") or ""),
  126. "value": str(value),
  127. "from_call_id": call_id or None,
  128. "row_hash": row_hash or None,
  129. "verified": verified,
  130. }
  131. )
  132. variables = {chr(ord("a") + index): value for index, value in enumerate(values)}
  133. variables.update({f"v{index + 1}": value for index, value in enumerate(values)})
  134. if op in ("sum", "mean", "avg", "median", "min", "max", "count"):
  135. if op == "sum":
  136. result = sum(values)
  137. elif op in ("mean", "avg"):
  138. result = sum(values) / len(values)
  139. elif op == "median":
  140. result = _decimal(statistics.median(sorted(values)))
  141. elif op == "min":
  142. result = min(values)
  143. elif op == "max":
  144. result = max(values)
  145. else:
  146. result = _decimal(len(values))
  147. shown = f"{op}({', '.join(str(value) for value in values)})"
  148. elif op == "growth":
  149. if len(values) != 2:
  150. raise CalcError("growth 需要两个输入:[本期, 上期]")
  151. if values[1] == 0:
  152. raise CalcError("上期为 0,环比无法计算(按需求留空而不是填 0)")
  153. result = values[0] / values[1] - 1
  154. shown = f"({values[0]} / {values[1]} - 1)"
  155. elif op == "ratio":
  156. if len(values) != 2:
  157. raise CalcError("ratio 需要两个输入:[分子, 分母]")
  158. if values[1] == 0:
  159. raise CalcError("分母为 0,比值无法计算")
  160. result = values[0] / values[1]
  161. shown = f"({values[0]} / {values[1]})"
  162. elif op == "index":
  163. if len(values) != 2:
  164. raise CalcError("index 需要两个输入:[当期, 基期]")
  165. if values[1] == 0:
  166. raise CalcError("基期为 0,指数无法计算")
  167. result = values[0] / values[1] * Decimal(1000)
  168. shown = f"({values[0]} / {values[1]} * 1000)"
  169. elif op == "share":
  170. if len(values) < 2:
  171. raise CalcError("share 需要 [部分, 合计]")
  172. if values[1] == 0:
  173. raise CalcError("合计为 0,占比无法计算")
  174. result = values[0] / values[1]
  175. shown = f"({values[0]} / {values[1]})"
  176. else:
  177. if not expression:
  178. raise CalcError("expression 运算需要提供 expression")
  179. evaluator = _Evaluator(variables)
  180. result = evaluator.evaluate(expression)
  181. shown = expression
  182. if not result.is_finite():
  183. raise CalcError("计算结果不是有限数值")
  184. calculation_id = new_id("calc")
  185. input_signature = [{"value": str(value), "from_call_id": item["from_call_id"], "row_hash": item["row_hash"]} for value, item in zip(values, enriched)]
  186. trace = {
  187. "calculation_id": calculation_id,
  188. "result_hash": _result_hash({"result": str(result), "inputs": input_signature, "op": op}),
  189. "op": op,
  190. }
  191. payload = {
  192. "call_id": calculation_id,
  193. "tool": "calculator",
  194. "op": op,
  195. "label": label,
  196. "expression": shown,
  197. "result": str(result),
  198. "inputs": enriched,
  199. "unverified_inputs": unverified,
  200. "all_inputs_verified": unverified == 0,
  201. "_trace": trace,
  202. }
  203. ledger.record(
  204. calculation_id,
  205. "calculator",
  206. {"op": op, "inputs": inputs, "expression": expression, "label": label},
  207. payload,
  208. session_id=session_id,
  209. rows=[
  210. {
  211. "values": {"result": str(result)},
  212. "_trace": {"object_id": "", "table": "calculator", "row_index": -1, "row_hash": trace["result_hash"]},
  213. }
  214. ],
  215. )
  216. return payload