maze-moderation-sdk 0.1.0__tar.gz

maze_moderation_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `maze-moderation-sdk` will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning during public releases.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-17
+
+### Added
+
+- Public SDK surface: `normalize`, `scan_local`, `review_cloud`, `collect_signals`, `review_text`.
+- Frozen dataclass contracts (`Hit`, `CloudVerdict`, `Signals`, `Verdict`) and `RiskStrategy` / `CloudProvider` protocols.
+- Local review: variant normalization, AC automaton lexicon scan, privacy regex, bundled default lexicon snapshot.
+- Cloud review: `AliyunProvider` for Alibaba Cloud text moderation APIs.
+- `DefaultRiskStrategy` with L0–L3 verdict mapping, fail-secure and degraded-mode handling.
+- PyPI publish pipeline via GitHub tag and Trusted Publishing.

maze_moderation_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tada
+
+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.

maze_moderation_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .ruff_cache *
+global-exclude .ruff_cache/*

maze_moderation_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: maze-moderation-sdk
+Version: 0.1.0
+Summary: Maze 内容审核 SDK：文本审核先行，后续扩展图片与视频审核。
+Author: Tada
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MazeAI-pro/content_security
+Project-URL: Repository, https://github.com/MazeAI-pro/content_security
+Project-URL: Documentation, https://github.com/MazeAI-pro/content_security/tree/main/sdks/moderation#readme
+Project-URL: Changelog, https://github.com/MazeAI-pro/content_security/blob/main/sdks/moderation/CHANGELOG.md
+Project-URL: Issues, https://github.com/MazeAI-pro/content_security/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyahocorasick>=2.0
+Requires-Dist: opencc>=1.1
+Requires-Dist: pypinyin>=0.51
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# maze-moderation-sdk
+
+Maze 内容审核 SDK。当前首发文本审核能力，后续在同一个 SDK 下扩展图片、视频审核。
+
+文本审核模块是无状态文本审核核——不碰会话状态、不碰 Redis、不碰配置中心、不碰任何 channel。所有配置由调用方构造 `ReviewConfig` 注入，密钥由调用方构造 `CloudProvider` 时注入，永不进包逻辑。
+
+完整设计见 `../../../to-tada/security/design-sdk.md`，开发计划见 `../../../dev-plan/text-censor-sdk-dev-plan.md`。
+
+## 作为 SDK 引入
+
+阶段 A（本地联调）推荐使用 sibling editable path：
+
+```toml
+[project]
+dependencies = ["maze-moderation-sdk"]
+
+[tool.uv.sources]
+maze-moderation-sdk = { path = "../content_security/sdks/moderation", editable = true }
+```
+
+团队内 CI 或跨仓验证可锁定 Git tag：
+
+```toml
+[project]
+dependencies = ["maze-moderation-sdk"]
+
+[tool.uv.sources]
+maze-moderation-sdk = { git = "ssh://git@github.com/MazeAI-pro/content_security.git", tag = "v0.1.0", subdirectory = "sdks/moderation" }
+```
+
+公开发布到 PyPI 后：
+
+```toml
+dependencies = ["maze-moderation-sdk>=0.1,<0.2"]
+```
+
+不要把本地 path 依赖写进生产环境配置。PyPI 发布说明见 [`docs/publish.md`](docs/publish.md)。
+
+## 公共 API
+
+文本审核能力位于 `maze_moderation.text`：
+
+| 函数 | 层 | 说明 |
+| --- | --- | --- |
+| `normalize(text)` | 纯函数 | 变体归一化（零宽/全半角/繁简/大小写/重复压缩/拼音） |
+| `scan_local(text, *, lexicon)` | 只本地 | 已归一化文本上的 AC 自动机扫描 |
+| `review_cloud(text, *, provider, chat_id, done)` | 只云 | 只调云 API，不跑本地 DFA |
+| `collect_signals(text, *, config)` | mechanism | 跑 DFA + 云，返回原始 `Signals`，不做判定 |
+| `review_text(text, *, config)` | mechanism+policy | 收集信号后交由 `config.risk_strategy` 判定，出 `Verdict` |
+
+外加 `RiskStrategy` / `CloudProvider` 两个 Protocol 和一组 frozen dataclass（`Hit`/`CloudVerdict`/`Signals`/`Verdict`）。
+
+## 三种用法
+
+| 消费方 | 用法 |
+| --- | --- |
+| tada | `review_text` + `DefaultRiskStrategy`，阈值走 config 微调；流式切片在包外多次调 |
+| 第二个项目 | `review_text` + 默认策略，非流式，一段调一次 |
+| 任意未来项目 | `collect_signals` 拿原始信号自己合并，或传自定义 `RiskStrategy` |
+
+## 接入示例
+
+```python
+from maze_moderation.text import ReviewConfig, review_text, DefaultRiskStrategy
+from maze_moderation.text.cloud.aliyun import AliyunProvider
+
+# 有状态编排（如 tada）：编排层构造 config，会话状态/流式切片留在包外
+cfg = ReviewConfig(
+    cloud_provider=AliyunProvider(
+        access_key="...",
+        access_secret="...",
+        region="cn-shanghai",
+        service="llm_response_moderation",  # 场景由调用方选：评论/昵称/LLM 等
+    ),
+    risk_strategy=DefaultRiskStrategy(l2_confidence_threshold=0.75),
+    lexicon_path="",            # "" = 包内默认词库
+)
+verdict = await review_text(user_text, config=cfg)
+if verdict.action == "refuse":
+    ...  # 调用方自己处置
+
+# 无状态、非流式（第二个项目）：同样的 review_text 直调
+cfg = ReviewConfig(cloud_provider=AliyunProvider(...))
+verdict = await review_text(output_text, config=cfg)
+```
+
+## 依赖边界
+
+- **依赖**：`pyahocorasick`、`opencc`、`pypinyin`、`httpx`。
+- **不依赖**：`redis`、`fastapi`、`agentscope`、Config Center、任何 tada 内部模块。
+
+## 版本策略
+
+公共面（五函数签名 + frozen dataclass + 两个 Protocol）= SemVer 契约，改字段即 major bump。首发 `0.1.0` 已发布到 PyPI；后续 breaking change 走 major bump。
+
+## 本地审核（M2）
+
+> **local 层定位**：不替云端识别敏感词，泛化召回（语义/上下文/对抗变体）交给云端。local 层只做云端难以低成本覆盖的四件事——**确定性拦截**（高置信明确违禁词，零延迟）、**断网兜底**（云端降级时仍出 L3）、**隐私前置**（PII 正则本地命中即拦，不外发）、**业务热修**（竞品/品牌/黑话黑名单，加词分钟级生效）。故词库**控规模、提精度**，不追求泛化覆盖。
+
+```python
+from maze_moderation.text import load_lexicon, scan_local, ReviewConfig
+
+# 包内默认词库（konsheng 快照 v1，3267 词，全 hard，按 4 类分文件）
+lexicon = load_lexicon()
+
+# 外部词库覆盖 + 业务黑名单
+lexicon = load_lexicon(
+    "/path/to/lexicon",
+    extra_words=ReviewConfig(business_blacklist=("竞品名称",)).business_blacklist,
+)
+hits = scan_local("待审文本", lexicon=lexicon)
+```
+
+外部词库目录结构：
+
+```
+lexicon/
+  manifest.json    # version + files 元数据（category/severity）
+  v1/              # 与 manifest.version 同名的子目录
+    涉政.txt        # 文件名即 category；本地层全 hard，故只分类不分级
+    暴恐.txt        # 每行一个词；跨分类冲突按红线优先级归一文件
+    色情.txt
+    灰区.txt
+```
+
+词库维护：当前快照基于 konsheng 词库经人工加工（合并去重、剔除误伤词、分类调整），
+维护与重建说明见 `docs/lexicon-maintenance.md`。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest                # 覆盖率门槛 80%（见 pyproject.toml）
+```

maze_moderation_sdk-0.1.0/README.md

@@ -0,0 +1,134 @@
+# maze-moderation-sdk
+
+Maze 内容审核 SDK。当前首发文本审核能力，后续在同一个 SDK 下扩展图片、视频审核。
+
+文本审核模块是无状态文本审核核——不碰会话状态、不碰 Redis、不碰配置中心、不碰任何 channel。所有配置由调用方构造 `ReviewConfig` 注入，密钥由调用方构造 `CloudProvider` 时注入，永不进包逻辑。
+
+完整设计见 `../../../to-tada/security/design-sdk.md`，开发计划见 `../../../dev-plan/text-censor-sdk-dev-plan.md`。
+
+## 作为 SDK 引入
+
+阶段 A（本地联调）推荐使用 sibling editable path：
+
+```toml
+[project]
+dependencies = ["maze-moderation-sdk"]
+
+[tool.uv.sources]
+maze-moderation-sdk = { path = "../content_security/sdks/moderation", editable = true }
+```
+
+团队内 CI 或跨仓验证可锁定 Git tag：
+
+```toml
+[project]
+dependencies = ["maze-moderation-sdk"]
+
+[tool.uv.sources]
+maze-moderation-sdk = { git = "ssh://git@github.com/MazeAI-pro/content_security.git", tag = "v0.1.0", subdirectory = "sdks/moderation" }
+```
+
+公开发布到 PyPI 后：
+
+```toml
+dependencies = ["maze-moderation-sdk>=0.1,<0.2"]
+```
+
+不要把本地 path 依赖写进生产环境配置。PyPI 发布说明见 [`docs/publish.md`](docs/publish.md)。
+
+## 公共 API
+
+文本审核能力位于 `maze_moderation.text`：
+
+| 函数 | 层 | 说明 |
+| --- | --- | --- |
+| `normalize(text)` | 纯函数 | 变体归一化（零宽/全半角/繁简/大小写/重复压缩/拼音） |
+| `scan_local(text, *, lexicon)` | 只本地 | 已归一化文本上的 AC 自动机扫描 |
+| `review_cloud(text, *, provider, chat_id, done)` | 只云 | 只调云 API，不跑本地 DFA |
+| `collect_signals(text, *, config)` | mechanism | 跑 DFA + 云，返回原始 `Signals`，不做判定 |
+| `review_text(text, *, config)` | mechanism+policy | 收集信号后交由 `config.risk_strategy` 判定，出 `Verdict` |
+
+外加 `RiskStrategy` / `CloudProvider` 两个 Protocol 和一组 frozen dataclass（`Hit`/`CloudVerdict`/`Signals`/`Verdict`）。
+
+## 三种用法
+
+| 消费方 | 用法 |
+| --- | --- |
+| tada | `review_text` + `DefaultRiskStrategy`，阈值走 config 微调；流式切片在包外多次调 |
+| 第二个项目 | `review_text` + 默认策略，非流式，一段调一次 |
+| 任意未来项目 | `collect_signals` 拿原始信号自己合并，或传自定义 `RiskStrategy` |
+
+## 接入示例
+
+```python
+from maze_moderation.text import ReviewConfig, review_text, DefaultRiskStrategy
+from maze_moderation.text.cloud.aliyun import AliyunProvider
+
+# 有状态编排（如 tada）：编排层构造 config，会话状态/流式切片留在包外
+cfg = ReviewConfig(
+    cloud_provider=AliyunProvider(
+        access_key="...",
+        access_secret="...",
+        region="cn-shanghai",
+        service="llm_response_moderation",  # 场景由调用方选：评论/昵称/LLM 等
+    ),
+    risk_strategy=DefaultRiskStrategy(l2_confidence_threshold=0.75),
+    lexicon_path="",            # "" = 包内默认词库
+)
+verdict = await review_text(user_text, config=cfg)
+if verdict.action == "refuse":
+    ...  # 调用方自己处置
+
+# 无状态、非流式（第二个项目）：同样的 review_text 直调
+cfg = ReviewConfig(cloud_provider=AliyunProvider(...))
+verdict = await review_text(output_text, config=cfg)
+```
+
+## 依赖边界
+
+- **依赖**：`pyahocorasick`、`opencc`、`pypinyin`、`httpx`。
+- **不依赖**：`redis`、`fastapi`、`agentscope`、Config Center、任何 tada 内部模块。
+
+## 版本策略
+
+公共面（五函数签名 + frozen dataclass + 两个 Protocol）= SemVer 契约，改字段即 major bump。首发 `0.1.0` 已发布到 PyPI；后续 breaking change 走 major bump。
+
+## 本地审核（M2）
+
+> **local 层定位**：不替云端识别敏感词，泛化召回（语义/上下文/对抗变体）交给云端。local 层只做云端难以低成本覆盖的四件事——**确定性拦截**（高置信明确违禁词，零延迟）、**断网兜底**（云端降级时仍出 L3）、**隐私前置**（PII 正则本地命中即拦，不外发）、**业务热修**（竞品/品牌/黑话黑名单，加词分钟级生效）。故词库**控规模、提精度**，不追求泛化覆盖。
+
+```python
+from maze_moderation.text import load_lexicon, scan_local, ReviewConfig
+
+# 包内默认词库（konsheng 快照 v1，3267 词，全 hard，按 4 类分文件）
+lexicon = load_lexicon()
+
+# 外部词库覆盖 + 业务黑名单
+lexicon = load_lexicon(
+    "/path/to/lexicon",
+    extra_words=ReviewConfig(business_blacklist=("竞品名称",)).business_blacklist,
+)
+hits = scan_local("待审文本", lexicon=lexicon)
+```
+
+外部词库目录结构：
+
+```
+lexicon/
+  manifest.json    # version + files 元数据（category/severity）
+  v1/              # 与 manifest.version 同名的子目录
+    涉政.txt        # 文件名即 category；本地层全 hard，故只分类不分级
+    暴恐.txt        # 每行一个词；跨分类冲突按红线优先级归一文件
+    色情.txt
+    灰区.txt
+```
+
+词库维护：当前快照基于 konsheng 词库经人工加工（合并去重、剔除误伤词、分类调整），
+维护与重建说明见 `docs/lexicon-maintenance.md`。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest                # 覆盖率门槛 80%（见 pyproject.toml）
+```

maze_moderation_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maze-moderation-sdk"
+version = "0.1.0"
+description = "Maze 内容审核 SDK：文本审核先行，后续扩展图片与视频审核。"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Tada" }]
+dependencies = [
+    "pyahocorasick>=2.0",
+    "opencc>=1.1",
+    "pypinyin>=0.51",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/MazeAI-pro/content_security"
+Repository = "https://github.com/MazeAI-pro/content_security"
+Documentation = "https://github.com/MazeAI-pro/content_security/tree/main/sdks/moderation#readme"
+Changelog = "https://github.com/MazeAI-pro/content_security/blob/main/sdks/moderation/CHANGELOG.md"
+Issues = "https://github.com/MazeAI-pro/content_security/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["maze_moderation*"]
+
+[tool.setuptools.package-data]
+"maze_moderation.text" = [
+    "local/lexicon/manifest.json",
+    "local/lexicon/v1/*.txt",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--cov=maze_moderation --cov-report=term-missing --cov-fail-under=80"
+testpaths = ["tests"]

maze_moderation_sdk-0.1.0/setup.cfg

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

maze_moderation_sdk-0.1.0/src/maze_moderation_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,5 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml