jevaudit 0.1.0__py3-none-any.whl

jevaudit/__init__.py

@@ -0,0 +1,17 @@
+"""jevaudit — 通用校准审计器（audit ANY decision model, not just Jev）。
+
+decide → 三指纹账本 → Brier + 基线 + 校准曲线报告。
+三轮实战沉淀的 gotchas 内建：真值语义先证伪 / price 语义修正 / 基线 0.25 常数。
+"""
+from jevaudit.ledger import canonical, input_hash, output_hash, code_hash, add_record, load_ledger
+from jevaudit.gating import gate2, GateResult
+from jevaudit.accuracy_report import brier_score, calibration_curve, report
+from jevaudit.price_sem import implied_price, residual_check, match_tick
+
+__all__ = [
+    "canonical", "input_hash", "output_hash", "code_hash", "add_record", "load_ledger",
+    "gate2", "GateResult",
+    "brier_score", "calibration_curve", "report",
+    "implied_price", "residual_check", "match_tick",
+]
+__version__ = "0.1.0"

jevaudit/accuracy_report.py

@@ -0,0 +1,73 @@
+"""accuracy_report.py — Brier Score + 校准曲线 -> calibration_report.md。
+
+Brier = (1/N) * sum((p_i - o_i)^2)，仅统计 outcome in {0,1}（skipped 不计分）。
+目标：验证置信度 p 与真实概率 o 的匹配程度，置信度漂移率 <= 0.01。
+"""
+import statistics
+
+from .ledger import load_ledger
+
+REPORT = "calibration_report.md"
+
+
+def scorable(rows: list) -> list:
+    """可计分条目：p 存在且 outcome in {0,1}。"""
+    return [r for r in rows
+            if isinstance(r.get("p"), (int, float))
+            and r.get("outcome") in (0, 1)]
+
+
+def brier_score(p_list: list, o_list: list) -> float:
+    """Brier Score。p_list/o_list 等长；outcome=None 表示 skipped 不计分。"""
+    pairs = [(p, o) for p, o in zip(p_list, o_list) if o in (0, 1)]
+    if not pairs:
+        raise ValueError("no scorable samples")
+    return sum((p - o) ** 2 for p, o in pairs) / len(pairs)
+
+
+def calibration_curve(p_list: list, o_list: list, buckets: int = 5) -> list:
+    """校准曲线：按 p 值等宽分桶，每桶返回 {lo, hi, n, mean_p, mean_o}。"""
+    pairs = sorted((p, o) for p, o in zip(p_list, o_list) if o in (0, 1))
+    if not pairs:
+        return []
+    width = 1.0 / buckets
+    curve = []
+    for i in range(buckets):
+        lo, hi = i * width, (i + 1) * width
+        seg = [(p, o) for p, o in pairs if lo <= p < hi or (i == buckets - 1 and p == 1.0)]
+        if not seg:
+            continue
+        curve.append({
+            "lo": round(lo, 2), "hi": round(hi, 2), "n": len(seg),
+            "mean_p": round(statistics.mean(p for p, _ in seg), 4),
+            "mean_o": round(statistics.mean(o for _, o in seg), 4),
+        })
+    return curve
+
+
+def report(rows: list, out: str = REPORT) -> str:
+    """产出 Markdown 报告（难听话逻辑内置：样本不足不下结论）。"""
+    scor = scorable(rows)
+    lines = ["# Calibration Report (mm-audit-poc)", ""]
+    if len(scor) < 3:
+        lines.append(f"**样本不足（n={len(scor)} < 3），不下结论。**")
+    else:
+        b = brier_score([r["p"] for r in scor], [r["outcome"] for r in scor])
+        # 对照基线：全猜 0.5 的 Brier（常数 0.25，与结果分布无关）
+        base = sum((0.5 - o) ** 2 for o in (r["outcome"] for r in scor)) / len(scor)
+        curve = calibration_curve([r["p"] for r in scor], [r["outcome"] for r in scor])
+        drift = abs(statistics.mean(r["p"] for r in scor)
+                    - statistics.mean(r["outcome"] for r in scor))
+        lines += [
+            f"- n={len(scor)}  Brier={b:.4f}",
+            f"- 对照基线（全猜 0.5）Brier={base:.4f}  {'✅ Jev 优于瞎猜' if b < base else '❌ Jev 不优于瞎猜（≈随机）'}",
+            f"- 漂移率 |mean_p - mean_o| = {drift:.4f}  {'✅ <=0.01 达标' if drift <= 0.01 else '❌ >0.01 未达标'}",
+            "",
+            "| p 桶 | n | mean_p | mean_o |",
+            "|---|---|---|---|",
+        ]
+        for c in curve:
+            lines.append(f"| [{c['lo']}, {c['hi']}) | {c['n']} | {c['mean_p']} | {c['mean_o']} |")
+    with open(out, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+    return out

jevaudit/gating.py

@@ -0,0 +1,32 @@
+"""gating.py — 三段式置信度门控（用户令门控带）。
+
+    Score >= 0.70  -> KEEP    （自动采用决策，直接出单/调开执行层）
+    0.30 <= Score < 0.70 -> CONFIRM（存 fallback log，后置复核）
+    Score < 0.30   -> DROP    （直接抛弃，节省算力开销）
+
+注意：与 jevkit 现成 gate()（act/confirm/escalate）不同，本模块是
+做市 PoC 专用门控带，不改旧件、不互相污染。
+"""
+import enum
+
+
+class GateResult(enum.Enum):
+    KEEP = "KEEP"
+    CONFIRM = "CONFIRM"
+    DROP = "DROP"
+
+
+ACT = 0.70
+DROP_BELOW = 0.30
+
+
+def gate2(p: float, act: float = ACT, drop_below: float = DROP_BELOW) -> GateResult:
+    """置信度门控。p 必须在 [0,1]。"""
+    p = float(p)
+    if not 0.0 <= p <= 1.0:
+        raise ValueError(f"p out of range: {p}")
+    if p >= act:
+        return GateResult.KEEP
+    if p >= drop_below:
+        return GateResult.CONFIRM
+    return GateResult.DROP

jevaudit/ledger.py

@@ -0,0 +1,61 @@
+"""ledger.py — 追加写 JSONL 对账账本（原子落盘 + 坏行容忍 + 三指纹）。"""
+import hashlib
+import json
+import os
+
+
+def canonical(obj) -> str:
+    """规范 JSON：ensure_ascii=False + sort_keys + 紧凑分隔符。"""
+    return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _sha(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def input_hash(state: str, questions: dict) -> str:
+    """指纹 1：sha256(规范化的 state+questions)[:32]。输入给偏了首查它。"""
+    return _sha(canonical({"state": state, "questions": questions}))[:32]
+
+
+def output_hash(response) -> str:
+    """指纹 2：sha256(模型原始响应)[:32]。同输入重跑结果变了没（模型漂移）。"""
+    return _sha(canonical(response))[:32]
+
+
+def code_hash(script_path: str = None) -> str:
+    """指纹 3：sha256(判定脚本字节)[:16]，src- 前缀。是不是我们改了逻辑。"""
+    p = script_path or os.path.join(os.path.dirname(os.path.abspath(__file__)), "mm_poc.py")
+    try:
+        with open(p, "rb") as f:
+            return "src-" + hashlib.sha256(f.read()).hexdigest()[:12]
+    except OSError:
+        return "src-unavailable"
+
+
+def add_record(path: str, record: dict) -> None:
+    """原子追加一行 JSONL。幂等无害：只追加不重写。"""
+    line = canonical(record) + "\n"
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+    try:
+        os.write(fd, line.encode("utf-8"))
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def load_ledger(path: str) -> list:
+    """读回账本，坏行容忍（跳过不可解析行，不抛异常）。"""
+    rows = []
+    if not os.path.exists(path):
+        return rows
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue  # 坏行容忍
+    return rows

jevaudit/price_sem.py

@@ -0,0 +1,28 @@
+"""price_sem.py — price 列语义修正（动手派根因报告落地）。
+
+核心规则：price 列是截断/舍入后的展示价（残差恒 < 0.0125），
+usdcSize 是精确执行金额。**price 列严禁精确校验**：
+- 真执行价 = usdcSize / size（implied price）
+- 校验用 tick 级容差（0.01/0.001）或残差结构检查
+"""
+BAND = 0.0125  # 实测截断带（残差峰值钉在 +0.0125）
+
+
+def implied_price(size: float, usdc_size: float) -> float:
+    """真执行价 = usdcSize / size。别再用展示价当真值。"""
+    return usdc_size / size
+
+
+def residual_check(price: float, implied: float, band: float = BAND) -> str:
+    """残差结构三态：ok / reverse（SELL 侧，标注不判死）/ out_of_band。"""
+    d = implied - price
+    if d < 0:
+        return "reverse"
+    if d < band:
+        return "ok"
+    return "out_of_band"
+
+
+def match_tick(price: float, implied: float, tick: float = 0.01) -> bool:
+    """tick 级容差校验选项。"""
+    return abs(implied - price) <= tick

jevaudit-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: jevaudit
+Version: 0.1.0
+Summary: Universal calibration auditor for decision models: decide -> three-fingerprint ledger -> Brier + baselines + calibration curve. Audits ANY decision model, not just Jev.
+Author: jevaudit contributors
+License: MIT
+Keywords: calibration,audit,brier,decision,ledger,llm,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# jevaudit — 通用校准审计器
+
+> Audit ANY decision model, not just Jev.
+> decide → 三指纹账本 → Brier + 基线 + 校准曲线报告。
+
+## Why
+
+任何"模型给概率、事后有真值"的决策系统都需要审计：置信度 p 和真实结果 o
+到底差多少？是不是瞎猜？基线是多少？jevaudit 把审计变成三件套：
+**账本（可回溯）+ Brier（可比较）+ 校准曲线（可诊断）**。
+
+- **三指纹账本**：input_hash / output_hash / code_hash——输入给偏了、模型漂移了、
+  判定脚本改了，首查指纹
+- **基线内置**：全猜 0.5 的 Brier = **0.25 常数**（与结果分布无关），模型低于
+  0.25 才是有用——报告自动对比，难听话自动打（>0.4 直接写"接近随机"）
+- **前视防护**：审计时只看决策时点可得的信息，结算后的信息严禁进输入
+
+## Install
+
+```bash
+pip install jevaudit   # (after publish — for now: copy the jevaudit/ directory)
+```
+
+## Quickstart
+
+```python
+from jevaudit import add_record, load_ledger, input_hash, output_hash, code_hash
+from jevaudit import gate2, brier_score, calibration_curve, report
+
+# 1) 每次决策记一条（三指纹 + check_spec 必填）
+add_record("ledger.jsonl", {
+    "id": "dec-001",
+    "input_hash": input_hash(state, questions),   # sha256(规范输入)[:32]
+    "output_hash": output_hash(response),         # sha256(响应)[:32]
+    "code_hash": code_hash(),                     # sha256(判定脚本)[:16]
+    "p": 0.95,                                    # 模型给的置信度
+    "outcome": 1,                                 # 真实回填结果 (1/0)
+    "check_spec": {"baseline": "implied_price", "tick": 0.01},  # 用的什么基准
+})
+
+# 2) 审计：Brier + 基线 + 校准曲线
+rows = load_ledger("ledger.jsonl")
+b = brier_score([r["p"] for r in rows], [r["outcome"] for r in rows])
+curve = calibration_curve([r["p"] for r in rows], [r["outcome"] for r in rows])
+report(rows, "calibration_report.md")   # 产出 Markdown（含 0.25 基线对比行）
+
+# 3) 门控：KEEP / CONFIRM / DROP
+action = gate2(0.75)   # KEEP (>=0.7) / CONFIRM (0.3-0.7) / DROP (<0.3)
+```
+
+## Gotchas（三轮实战沉淀，踩不到的坑）
+
+1. **Brier 难看时，第一步永远是证伪校验基准**（真值语义/价格语义/结算语义），
+   第二步才怀疑模型——两次实战：真值生成器语义反了 → Brier 必然反向
+2. **price 列严禁精确校验**：展示价是截断/舍入价（残差恒 < 0.0125），
+   真执行价 = `implied_price(usdcSize/size)`；校验用 tick 级容差（0.01/0.001）
+3. **check_spec 必填**：记录用的什么基准/容差，让"度量分歧"可回溯，
+   不然下个人又把基准当真值查一遍
+4. **["0","0"] 是退化态**：已结算二元市场必须恰好一边=1，两边全 0 = 未真结算，拒
+5. **outcomePrices 可能是字符串**（JSON 编码数组），先 json.loads 再算
+6. **残差 <0 的反例（~1.4%）疑似 SELL 侧语义**：标注 `reverse`，不判死不混入
+7. **样本 <3 不下结论**；漂移率 |mean_p − mean_o| > 0.01 如实打 ❌，不圆场
+
+## 配套
+
+- **jevkit**（PyPI）：OpenRouter Decisions API (Jev) 的第一个开源第三方客户端
+  —— client + CLI + gate 模式
+- 实战战绩：n=100 黑箱审计（Polymarket 真实交易 vs Jev，前视防护 100/100）
+
+## License
+
+MIT

jevaudit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+jevaudit/__init__.py,sha256=BwAiptQBaAW2a24fksBCZE3iR0eazJigLrJuGXyVqm8,815
+jevaudit/accuracy_report.py,sha256=ceFl9Z2mxIc27Wz_NhYxIV77vl0pES7HwNznjdk-ha0,3170
+jevaudit/gating.py,sha256=JRQX-kT1aHyazjGdy2H1AwI_vKOKQumTXzEO2AOtXdQ,945
+jevaudit/ledger.py,sha256=69obBQRSiujZdYEeScbkvMklqsmQ3gRfW5_AUD2dwG0,2058
+jevaudit/price_sem.py,sha256=PQ8XYbk38TOAsafB0ac82eZ3sK65mFsoAcJMEBZsjks,1030
+jevaudit-0.1.0.dist-info/METADATA,sha256=yBTvE13DdV2ftFlJGtPPW61aDVtF5E7amUeHBsqIp_M,4047
+jevaudit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+jevaudit-0.1.0.dist-info/top_level.txt,sha256=9KO-Wk54zcpGc00y5klBAqBlc1BH_GxydEbwXtdi5a0,9
+jevaudit-0.1.0.dist-info/RECORD,,

jevaudit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jevaudit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jevaudit