sothstan 0.1.0rc1__tar.gz

sothstan-0.1.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sothstan contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sothstan-0.1.0rc1/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: sothstan
+Version: 0.1.0rc1
+Summary: The Trial of the Hidden Voice (Sothstan) | Statistical audits for LLM API endpoints
+Author: sothstan contributors
+License: MIT
+Project-URL: Homepage, https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice
+Project-URL: Repository, https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice
+Project-URL: Issues, https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/issues
+Project-URL: Changelog, https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/security/policy
+Keywords: llm,api,fingerprint,verification,chinese,relay,模型验真
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# The Trial of the Hidden Voice — Sothstan
+
+简体中文 · [English](README.en.md)
+
+> 展示名 **The Trial of the Hidden Voice** 描绘对隐匿声音的审视；Sothstan 是该项目的短名。
+
+**中文优先的 LLM API 模型验真库。一个端点声称自己在服务模型 X——它真的在服务 X 吗？**
+用多层指纹 + 混淆集似然比给出统计判决，证据链哈希锁定，可复现、可审计。
+
+[![CI](https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/actions/workflows/ci.yml/badge.svg)](.github/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## 为什么需要它 / Why
+
+第三方中转、代理或聚合 API 往往会返回一个自报模型名。仅凭这个字段无法验证端点的实际行为是否与所声明模型一致；差异也可能来自版本变化、采样参数、服务策略或网络错误。Sothstan 用可信基线比较多种行为信号，并保留统计结果和不确定性。
+
+## 安装 / Install
+
+> 当前尚未发布到 PyPI；下方给出从 GitHub 获取并本地安装的命令。
+
+```bash
+git clone https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice.git
+cd TheTrialOfTheHiddenVoice
+python -m pip install .
+# PyPI 首发后：python -m pip install sothstan
+```
+
+## 快速开始 / Quickstart
+
+**没有官方 API key？先离线验证工具本身**（内置 mock 模型与四种攻击场景）：
+
+```bash
+sothstan selftest
+# PASS  诚实服务器 → AUTHENTIC
+
+# PASS  换模型中转 → MISMATCH（runner-up 正确指认）
+
+# PASS  仅改 model 字段 → 仍 AUTHENTIC（字段回显零权重）
+
+# PASS  伪造 usage 的说谎中转 → 仍 MISMATCH（行为/错误层暴露）
+
+```
+
+有 key 之后，两步验真：
+
+```bash
+# 第一步：对【官方】端点采集基线（至少 2 个模型，互为混淆集）
+
+sothstan collect https://api.deepseek.com/v1 --model deepseek-chat \
+    --family deepseek --out baselines/deepseek-chat.json --api-key-env DEEPSEEK_API_KEY
+sothstan collect https://api.deepseek.com/v1 --model deepseek-reasoner \
+    --family deepseek --out baselines/deepseek-reasoner.json --api-key-env DEEPSEEK_API_KEY
+
+# 第二步：验证可疑端点
+
+sothstan check https://relay.example.com/v1 --model deepseek-chat --api-key-env RELAY_KEY
+# ✅ AUTHENTIC  margin +212.4  证据链 9f3a…  exit 0
+
+# ❌ MISMATCH   runner-up: deepseek-reasoner  exit 2
+
+```
+
+## 工作原理 / How it works
+
+```
+探测（probe）──产出──> 指纹信号（signal）──对比──> 基线（baseline，官方端点采集）
+                                                        │
+                              混淆集似然比（claimed vs 全部竞争模型）
+                                                        │
+                                        判决 AUTHENTIC / SUSPICIOUS / MISMATCH / INCONCLUSIVE
+```
+
+- **tier-1 确定性层**：`usage` 自报 token 曲线（20 篇 canonical 文本，CJK 分歧最大）、
+  chat template 开销、max_tokens 限额、logprobs/n 参数支持、错误码族
+- **tier-2 行为层**：思维链形态、风格标记、reasoning 字段
+- **混淆集比较**是方法核心：冒充者通常与目标同家族（r1 冒充 v3），"像不像"没有意义，
+  "证据更支持谁"才有意义；且 claimed 总分低于硬地板时直接 MISMATCH——
+  **token 层再像也淹没不了行为层的全面矛盾**（mock 实验可复现）
+- **零权重展示项**：响应体 `model` 字段回显——改字段是最廉价的伪造，报告里可见但不计分
+
+内置 mock 服务器（Aqua/Breeze 双人格）完整演示四种场景：诚实 → AUTHENTIC；
+换模型中转 → MISMATCH（runner-up 正确指向替代模型）；只改 model 字段 → 仍 AUTHENTIC；
+**伪造 usage 的完美说谎中转 → 仍 MISMATCH（行为/错误层暴露）**。
+
+## 批量审计 / Audit
+
+月度《中转站验真报告》的生产工具：CSV 目标清单 → 受控并发 → 可发布报告（逐端点证据链哈希）：
+
+```csv
+name,base_url,model,key_env
+relay-a,https://a.example.com/v1,deepseek-chat,KEY_A
+relay-b,https://b.example.com/v1,deepseek-chat,
+```
+
+```bash
+sothstan audit targets.csv -o report.md --json-out report.json --max-workers 4
+# 退出码：0 全部 AUTHENTIC / 1 含 SUSPICIOUS / 2 含 MISMATCH / 3 全部 INCONCLUSIVE
+
+```
+
+## 对抗模式 / Adversarial
+
+canonical 文本池是公开的——中转可以对固定文本预置答案。`--adversarial` 让 token
+探测改用**按 seed 确定性生成**的对抗文本（混合文种、ZWJ emoji 序列、组合字符、
+罕见 CJK 区块、全角形式——tokenizer 分歧最大的类别）：
+
+```bash
+# 基线与验证必须同模式；换 --seed 即轮换探测集
+
+sothstan collect https://api.official.com/v1 --model m1 --family f \
+    --out baselines/m1.json --adversarial --seed 777 --api-key-env K1
+sothstan check https://relay.example.com/v1 --model m1 --adversarial --seed 777
+```
+
+- 同 seed 同文本：证据链可复现（fuzz 测试锁定确定性）
+- 模式不一致时判决会附诚实警示（基线与运行的 token 曲线不可比）
+- 诚实边界：字符池公开，安全性不靠保密，靠"探测集随 seed 轮换"的不可预置性
+
+## 诚实边界 / Honesty
+
+- 指纹验证是**统计证据，不是数学证明**——判决阈值全部公开（`verdict.THRESHOLDS_DOC`）
+- 基线必须来自官方端点；内置 `_demo_*.json` 是 mock 人格指纹，**不代表任何真实模型**
+- 军备竞赛真实存在：探测可被识别、转发。对策（种子化换题/多层信号/统计聚合）
+  见 [GAP_PROOF.md](GAP_PROOF.md) 第 4 节——部分可检测已远超现状（现状是零）
+
+## 退出码（CI 友好）
+
+| 码 | 含义 |
+|---|---|
+| 0 | AUTHENTIC |
+| 1 | SUSPICIOUS |
+| 2 | MISMATCH |
+| 3 | INCONCLUSIVE（证据不足/无竞争基线——诚实说不足） |
+| 4 | 基础设施错误（端点不可达/基线缺失） |
+
+## 与现有方案的关系 / Landscape
+
+| 方法类别 | 能回答的问题与限制 |
+|---|---|
+| 检查返回的 `model` 字段 | 能读取端点自报名称；不能单独证明服务端实际模型 |
+| 固定提示词探测 | 可观察部分响应差异；结果会受参数、版本和服务端策略影响 |
+| Sothstan | 将多个信号与可信基线比较，并报告判决、边界和可复现记录；不是密码学身份认证 |
+
+## 路线图 / Roadmap
+
+见 [ROADMAP.md](ROADMAP.md)。当前 v0.1.0rc1：5 探测器 + 混淆集判决 + mock 全链路 + CLI，
+41 项测试全绿。接下来：对抗文本模式、对抗实验矩阵、批量审计、官方基线流水线。
+
+## 开发 / Development
+
+```bash
+pip install -e ".[dev]"
+./.venv/Scripts/python.exe -m pytest -q        # Windows Git Bash
+./.venv/Scripts/python.exe -m ruff check src tests tools
+./.venv/Scripts/python.exe tools/gen_demo_baselines.py   # 重新生成 demo 基线
+```
+
+## 反馈与参与
+
+使用问题和功能建议可以在 [Discussions](https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/discussions) 交流；可复现缺陷请提交 [Issue](https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/issues)。请只附合成或脱敏后的最小样例，不要上传真实个人信息、API key 或业务原文。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。
+
+## License
+
+MIT

sothstan-0.1.0rc1/README.md

@@ -0,0 +1,165 @@
+# The Trial of the Hidden Voice — Sothstan
+
+简体中文 · [English](README.en.md)
+
+> 展示名 **The Trial of the Hidden Voice** 描绘对隐匿声音的审视；Sothstan 是该项目的短名。
+
+**中文优先的 LLM API 模型验真库。一个端点声称自己在服务模型 X——它真的在服务 X 吗？**
+用多层指纹 + 混淆集似然比给出统计判决，证据链哈希锁定，可复现、可审计。
+
+[![CI](https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/actions/workflows/ci.yml/badge.svg)](.github/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## 为什么需要它 / Why
+
+第三方中转、代理或聚合 API 往往会返回一个自报模型名。仅凭这个字段无法验证端点的实际行为是否与所声明模型一致；差异也可能来自版本变化、采样参数、服务策略或网络错误。Sothstan 用可信基线比较多种行为信号，并保留统计结果和不确定性。
+
+## 安装 / Install
+
+> 当前尚未发布到 PyPI；下方给出从 GitHub 获取并本地安装的命令。
+
+```bash
+git clone https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice.git
+cd TheTrialOfTheHiddenVoice
+python -m pip install .
+# PyPI 首发后：python -m pip install sothstan
+```
+
+## 快速开始 / Quickstart
+
+**没有官方 API key？先离线验证工具本身**（内置 mock 模型与四种攻击场景）：
+
+```bash
+sothstan selftest
+# PASS  诚实服务器 → AUTHENTIC
+
+# PASS  换模型中转 → MISMATCH（runner-up 正确指认）
+
+# PASS  仅改 model 字段 → 仍 AUTHENTIC（字段回显零权重）
+
+# PASS  伪造 usage 的说谎中转 → 仍 MISMATCH（行为/错误层暴露）
+
+```
+
+有 key 之后，两步验真：
+
+```bash
+# 第一步：对【官方】端点采集基线（至少 2 个模型，互为混淆集）
+
+sothstan collect https://api.deepseek.com/v1 --model deepseek-chat \
+    --family deepseek --out baselines/deepseek-chat.json --api-key-env DEEPSEEK_API_KEY
+sothstan collect https://api.deepseek.com/v1 --model deepseek-reasoner \
+    --family deepseek --out baselines/deepseek-reasoner.json --api-key-env DEEPSEEK_API_KEY
+
+# 第二步：验证可疑端点
+
+sothstan check https://relay.example.com/v1 --model deepseek-chat --api-key-env RELAY_KEY
+# ✅ AUTHENTIC  margin +212.4  证据链 9f3a…  exit 0
+
+# ❌ MISMATCH   runner-up: deepseek-reasoner  exit 2
+
+```
+
+## 工作原理 / How it works
+
+```
+探测（probe）──产出──> 指纹信号（signal）──对比──> 基线（baseline，官方端点采集）
+                                                        │
+                              混淆集似然比（claimed vs 全部竞争模型）
+                                                        │
+                                        判决 AUTHENTIC / SUSPICIOUS / MISMATCH / INCONCLUSIVE
+```
+
+- **tier-1 确定性层**：`usage` 自报 token 曲线（20 篇 canonical 文本，CJK 分歧最大）、
+  chat template 开销、max_tokens 限额、logprobs/n 参数支持、错误码族
+- **tier-2 行为层**：思维链形态、风格标记、reasoning 字段
+- **混淆集比较**是方法核心：冒充者通常与目标同家族（r1 冒充 v3），"像不像"没有意义，
+  "证据更支持谁"才有意义；且 claimed 总分低于硬地板时直接 MISMATCH——
+  **token 层再像也淹没不了行为层的全面矛盾**（mock 实验可复现）
+- **零权重展示项**：响应体 `model` 字段回显——改字段是最廉价的伪造，报告里可见但不计分
+
+内置 mock 服务器（Aqua/Breeze 双人格）完整演示四种场景：诚实 → AUTHENTIC；
+换模型中转 → MISMATCH（runner-up 正确指向替代模型）；只改 model 字段 → 仍 AUTHENTIC；
+**伪造 usage 的完美说谎中转 → 仍 MISMATCH（行为/错误层暴露）**。
+
+## 批量审计 / Audit
+
+月度《中转站验真报告》的生产工具：CSV 目标清单 → 受控并发 → 可发布报告（逐端点证据链哈希）：
+
+```csv
+name,base_url,model,key_env
+relay-a,https://a.example.com/v1,deepseek-chat,KEY_A
+relay-b,https://b.example.com/v1,deepseek-chat,
+```
+
+```bash
+sothstan audit targets.csv -o report.md --json-out report.json --max-workers 4
+# 退出码：0 全部 AUTHENTIC / 1 含 SUSPICIOUS / 2 含 MISMATCH / 3 全部 INCONCLUSIVE
+
+```
+
+## 对抗模式 / Adversarial
+
+canonical 文本池是公开的——中转可以对固定文本预置答案。`--adversarial` 让 token
+探测改用**按 seed 确定性生成**的对抗文本（混合文种、ZWJ emoji 序列、组合字符、
+罕见 CJK 区块、全角形式——tokenizer 分歧最大的类别）：
+
+```bash
+# 基线与验证必须同模式；换 --seed 即轮换探测集
+
+sothstan collect https://api.official.com/v1 --model m1 --family f \
+    --out baselines/m1.json --adversarial --seed 777 --api-key-env K1
+sothstan check https://relay.example.com/v1 --model m1 --adversarial --seed 777
+```
+
+- 同 seed 同文本：证据链可复现（fuzz 测试锁定确定性）
+- 模式不一致时判决会附诚实警示（基线与运行的 token 曲线不可比）
+- 诚实边界：字符池公开，安全性不靠保密，靠"探测集随 seed 轮换"的不可预置性
+
+## 诚实边界 / Honesty
+
+- 指纹验证是**统计证据，不是数学证明**——判决阈值全部公开（`verdict.THRESHOLDS_DOC`）
+- 基线必须来自官方端点；内置 `_demo_*.json` 是 mock 人格指纹，**不代表任何真实模型**
+- 军备竞赛真实存在：探测可被识别、转发。对策（种子化换题/多层信号/统计聚合）
+  见 [GAP_PROOF.md](GAP_PROOF.md) 第 4 节——部分可检测已远超现状（现状是零）
+
+## 退出码（CI 友好）
+
+| 码 | 含义 |
+|---|---|
+| 0 | AUTHENTIC |
+| 1 | SUSPICIOUS |
+| 2 | MISMATCH |
+| 3 | INCONCLUSIVE（证据不足/无竞争基线——诚实说不足） |
+| 4 | 基础设施错误（端点不可达/基线缺失） |
+
+## 与现有方案的关系 / Landscape
+
+| 方法类别 | 能回答的问题与限制 |
+|---|---|
+| 检查返回的 `model` 字段 | 能读取端点自报名称；不能单独证明服务端实际模型 |
+| 固定提示词探测 | 可观察部分响应差异；结果会受参数、版本和服务端策略影响 |
+| Sothstan | 将多个信号与可信基线比较，并报告判决、边界和可复现记录；不是密码学身份认证 |
+
+## 路线图 / Roadmap
+
+见 [ROADMAP.md](ROADMAP.md)。当前 v0.1.0rc1：5 探测器 + 混淆集判决 + mock 全链路 + CLI，
+41 项测试全绿。接下来：对抗文本模式、对抗实验矩阵、批量审计、官方基线流水线。
+
+## 开发 / Development
+
+```bash
+pip install -e ".[dev]"
+./.venv/Scripts/python.exe -m pytest -q        # Windows Git Bash
+./.venv/Scripts/python.exe -m ruff check src tests tools
+./.venv/Scripts/python.exe tools/gen_demo_baselines.py   # 重新生成 demo 基线
+```
+
+## 反馈与参与
+
+使用问题和功能建议可以在 [Discussions](https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/discussions) 交流；可复现缺陷请提交 [Issue](https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/issues)。请只附合成或脱敏后的最小样例，不要上传真实个人信息、API key 或业务原文。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。
+
+## License
+
+MIT

sothstan-0.1.0rc1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sothstan"
+version = "0.1.0rc1"
+description = "The Trial of the Hidden Voice (Sothstan) | Statistical audits for LLM API endpoints"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "sothstan contributors" }]
+keywords = ["llm", "api", "fingerprint", "verification", "chinese", "relay", "模型验真"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+sothstan = "sothstan.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice"
+Repository = "https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice"
+Issues = "https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/issues"
+Changelog = "https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/blob/main/CHANGELOG.md"
+Security = "https://github.com/cloudydreamland/TheTrialOfTheHiddenVoice/security/policy"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sothstan = ["baselines/*.json", "py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sothstan-0.1.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sothstan-0.1.0rc1/src/sothstan/__init__.py

@@ -0,0 +1,29 @@
+"""Sothstan — LLM API 模型验真。
+
+一个端点声称自己在服务模型 X，它真的在服务 X 吗？
+sothstan 用探测（probe）提取指纹信号（signal），与官方模型指纹基线（baseline）
+做混淆集似然比比较（confusion-set likelihood ratio），给出统计判决（verdict）。
+"""
+
+from sothstan._version import __version__
+from sothstan.baseline import Baseline, load_baseline, save_baseline
+from sothstan.http import ApiClient, ApiError, BudgetExceeded
+from sothstan.runner import collect_baseline_signals, verify
+from sothstan.types import Signal, VerdictLabel
+from sothstan.verdict import Verdict, decide
+
+__all__ = [
+    "ApiError",
+    "ApiClient",
+    "Baseline",
+    "BudgetExceeded",
+    "Signal",
+    "Verdict",
+    "VerdictLabel",
+    "collect_baseline_signals",
+    "decide",
+    "load_baseline",
+    "save_baseline",
+    "verify",
+    "__version__",
+]

sothstan-0.1.0rc1/src/sothstan/_version.py

@@ -0,0 +1,3 @@
+"""版本号单一定义点（避免循环导入）。"""
+
+__version__ = "0.1.0rc1"