mezzo-guard 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mezzo_guard-0.1.0/.gitignore +298 -0
- mezzo_guard-0.1.0/AGENTS.md +109 -0
- mezzo_guard-0.1.0/LICENSE +21 -0
- mezzo_guard-0.1.0/PKG-INFO +257 -0
- mezzo_guard-0.1.0/README.md +237 -0
- mezzo_guard-0.1.0/pyproject.toml +72 -0
- mezzo_guard-0.1.0/src/mezzoguard/__init__.py +23 -0
- mezzo_guard-0.1.0/src/mezzoguard/_types.py +24 -0
- mezzo_guard-0.1.0/src/mezzoguard/base_classes.py +466 -0
- mezzo_guard-0.1.0/src/mezzoguard/cache.py +35 -0
- mezzo_guard-0.1.0/src/mezzoguard/cli.py +102 -0
- mezzo_guard-0.1.0/src/mezzoguard/config.py +2 -0
- mezzo_guard-0.1.0/src/mezzoguard/errors.py +19 -0
- mezzo_guard-0.1.0/src/mezzoguard/guard/__init__.py +16 -0
- mezzo_guard-0.1.0/src/mezzoguard/guard/config.py +58 -0
- mezzo_guard-0.1.0/src/mezzoguard/guard/guard.py +206 -0
- mezzo_guard-0.1.0/src/mezzoguard/guard/policy.py +40 -0
- mezzo_guard-0.1.0/src/mezzoguard/guard/result.py +77 -0
- mezzo_guard-0.1.0/src/mezzoguard/model.py +222 -0
- mezzo_guard-0.1.0/src/mezzoguard/py.typed +0 -0
- mezzo_guard-0.1.0/src/mezzoguard/remote.py +206 -0
- mezzo_guard-0.1.0/src/mezzoguard/server/__init__.py +3 -0
- mezzo_guard-0.1.0/src/mezzoguard/server/app.py +166 -0
- mezzo_guard-0.1.0/src/mezzoguard/server/schemas.py +71 -0
- mezzo_guard-0.1.0/src/mezzoguard/server/serialize.py +20 -0
- mezzo_guard-0.1.0/tests/cache_test.py +240 -0
- mezzo_guard-0.1.0/tests/compile_test.py +21 -0
- mezzo_guard-0.1.0/tests/conftest.py +103 -0
- mezzo_guard-0.1.0/tests/onnx_benchmark.py +77 -0
- mezzo_guard-0.1.0/tests/test_chunking.py +45 -0
- mezzo_guard-0.1.0/tests/test_cli.py +88 -0
- mezzo_guard-0.1.0/tests/test_guards.py +281 -0
- mezzo_guard-0.1.0/tests/test_policy.py +84 -0
- mezzo_guard-0.1.0/tests/test_redaction.py +128 -0
- mezzo_guard-0.1.0/tests/test_remote.py +115 -0
- mezzo_guard-0.1.0/tests/test_server.py +128 -0
- mezzo_guard-0.1.0/uv.lock +1872 -0
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
.idea/
|
|
2
|
+
|
|
3
|
+
# Byte-compiled / optimized / DLL files
|
|
4
|
+
__pycache__/
|
|
5
|
+
*.py[codz]
|
|
6
|
+
*$py.class
|
|
7
|
+
|
|
8
|
+
# C extensions
|
|
9
|
+
*.so
|
|
10
|
+
|
|
11
|
+
# Distribution / packaging
|
|
12
|
+
.Python
|
|
13
|
+
build/
|
|
14
|
+
develop-eggs/
|
|
15
|
+
dist/
|
|
16
|
+
downloads/
|
|
17
|
+
eggs/
|
|
18
|
+
.eggs/
|
|
19
|
+
lib/
|
|
20
|
+
lib64/
|
|
21
|
+
parts/
|
|
22
|
+
sdist/
|
|
23
|
+
var/
|
|
24
|
+
wheels/
|
|
25
|
+
share/python-wheels/
|
|
26
|
+
*.egg-info/
|
|
27
|
+
.installed.cfg
|
|
28
|
+
*.egg
|
|
29
|
+
MANIFEST
|
|
30
|
+
|
|
31
|
+
# PyInstaller
|
|
32
|
+
# Usually these files are written by a python script from a template
|
|
33
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
34
|
+
*.manifest
|
|
35
|
+
*.spec
|
|
36
|
+
|
|
37
|
+
# Installer logs
|
|
38
|
+
pip-log.txt
|
|
39
|
+
pip-delete-this-directory.txt
|
|
40
|
+
|
|
41
|
+
# Unit test / coverage reports
|
|
42
|
+
htmlcov/
|
|
43
|
+
.tox/
|
|
44
|
+
.nox/
|
|
45
|
+
.coverage
|
|
46
|
+
.coverage.*
|
|
47
|
+
.cache
|
|
48
|
+
nosetests.xml
|
|
49
|
+
coverage.xml
|
|
50
|
+
*.cover
|
|
51
|
+
*.py.cover
|
|
52
|
+
.hypothesis/
|
|
53
|
+
.pytest_cache/
|
|
54
|
+
cover/
|
|
55
|
+
|
|
56
|
+
# Translations
|
|
57
|
+
*.mo
|
|
58
|
+
*.pot
|
|
59
|
+
|
|
60
|
+
# Django stuff:
|
|
61
|
+
*.log
|
|
62
|
+
local_settings.py
|
|
63
|
+
db.sqlite3
|
|
64
|
+
db.sqlite3-journal
|
|
65
|
+
|
|
66
|
+
# Flask stuff:
|
|
67
|
+
instance/
|
|
68
|
+
.webassets-cache
|
|
69
|
+
|
|
70
|
+
# Scrapy stuff:
|
|
71
|
+
.scrapy
|
|
72
|
+
|
|
73
|
+
# Sphinx documentation
|
|
74
|
+
docs/_build/
|
|
75
|
+
|
|
76
|
+
# PyBuilder
|
|
77
|
+
.pybuilder/
|
|
78
|
+
target/
|
|
79
|
+
|
|
80
|
+
# Jupyter Notebook
|
|
81
|
+
.ipynb_checkpoints
|
|
82
|
+
|
|
83
|
+
# IPython
|
|
84
|
+
profile_default/
|
|
85
|
+
ipython_config.py
|
|
86
|
+
|
|
87
|
+
# pyenv
|
|
88
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
89
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
90
|
+
# .python-version
|
|
91
|
+
|
|
92
|
+
# pipenv
|
|
93
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
94
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
95
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
96
|
+
# install all needed dependencies.
|
|
97
|
+
# Pipfile.lock
|
|
98
|
+
|
|
99
|
+
# UV
|
|
100
|
+
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
|
|
101
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
102
|
+
# commonly ignored for libraries.
|
|
103
|
+
# uv.lock
|
|
104
|
+
|
|
105
|
+
# poetry
|
|
106
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
107
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
108
|
+
# commonly ignored for libraries.
|
|
109
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
110
|
+
# poetry.lock
|
|
111
|
+
# poetry.toml
|
|
112
|
+
|
|
113
|
+
# pdm
|
|
114
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
115
|
+
# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
|
|
116
|
+
# https://pdm-project.org/en/latest/usage/project/#working-with-version-control
|
|
117
|
+
# pdm.lock
|
|
118
|
+
# pdm.toml
|
|
119
|
+
.pdm-python
|
|
120
|
+
.pdm-build/
|
|
121
|
+
|
|
122
|
+
# pixi
|
|
123
|
+
# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
|
|
124
|
+
# pixi.lock
|
|
125
|
+
# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
|
|
126
|
+
# in the .venv directory. It is recommended not to include this directory in version control.
|
|
127
|
+
.pixi
|
|
128
|
+
|
|
129
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
130
|
+
__pypackages__/
|
|
131
|
+
|
|
132
|
+
# Celery stuff
|
|
133
|
+
celerybeat-schedule
|
|
134
|
+
celerybeat.pid
|
|
135
|
+
|
|
136
|
+
# Redis
|
|
137
|
+
*.rdb
|
|
138
|
+
*.aof
|
|
139
|
+
*.pid
|
|
140
|
+
|
|
141
|
+
# RabbitMQ
|
|
142
|
+
mnesia/
|
|
143
|
+
rabbitmq/
|
|
144
|
+
rabbitmq-data/
|
|
145
|
+
|
|
146
|
+
# ActiveMQ
|
|
147
|
+
activemq-data/
|
|
148
|
+
|
|
149
|
+
# SageMath parsed files
|
|
150
|
+
*.sage.py
|
|
151
|
+
|
|
152
|
+
# Environments
|
|
153
|
+
.env
|
|
154
|
+
.envrc
|
|
155
|
+
.venv
|
|
156
|
+
env/
|
|
157
|
+
venv/
|
|
158
|
+
ENV/
|
|
159
|
+
env.bak/
|
|
160
|
+
venv.bak/
|
|
161
|
+
|
|
162
|
+
# Spyder project settings
|
|
163
|
+
.spyderproject
|
|
164
|
+
.spyproject
|
|
165
|
+
|
|
166
|
+
# Rope project settings
|
|
167
|
+
.ropeproject
|
|
168
|
+
|
|
169
|
+
# mkdocs documentation
|
|
170
|
+
/site
|
|
171
|
+
|
|
172
|
+
# mypy
|
|
173
|
+
.mypy_cache/
|
|
174
|
+
.dmypy.json
|
|
175
|
+
dmypy.json
|
|
176
|
+
|
|
177
|
+
# Pyre type checker
|
|
178
|
+
.pyre/
|
|
179
|
+
|
|
180
|
+
# pytype static type analyzer
|
|
181
|
+
.pytype/
|
|
182
|
+
|
|
183
|
+
# Cython debug symbols
|
|
184
|
+
cython_debug/
|
|
185
|
+
|
|
186
|
+
# Covers JetBrains IDEs: IntelliJ, GoLand, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
|
|
187
|
+
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
|
|
188
|
+
|
|
189
|
+
# User-specific stuff
|
|
190
|
+
.idea/**/workspace.xml
|
|
191
|
+
.idea/**/tasks.xml
|
|
192
|
+
.idea/**/usage.statistics.xml
|
|
193
|
+
.idea/**/dictionaries
|
|
194
|
+
.idea/**/shelf
|
|
195
|
+
|
|
196
|
+
# AWS User-specific
|
|
197
|
+
.idea/**/aws.xml
|
|
198
|
+
|
|
199
|
+
# Generated files
|
|
200
|
+
.idea/**/contentModel.xml
|
|
201
|
+
|
|
202
|
+
# Sensitive or high-churn files
|
|
203
|
+
.idea/**/dataSources/
|
|
204
|
+
.idea/**/dataSources.ids
|
|
205
|
+
.idea/**/dataSources.local.xml
|
|
206
|
+
.idea/**/sqlDataSources.xml
|
|
207
|
+
.idea/**/dynamic.xml
|
|
208
|
+
.idea/**/uiDesigner.xml
|
|
209
|
+
.idea/**/dbnavigator.xml
|
|
210
|
+
|
|
211
|
+
# Gradle
|
|
212
|
+
.idea/**/gradle.xml
|
|
213
|
+
.idea/**/libraries
|
|
214
|
+
|
|
215
|
+
# Gradle and Maven with auto-import
|
|
216
|
+
# When using Gradle or Maven with auto-import, you should exclude module files,
|
|
217
|
+
# since they will be recreated, and may cause churn. Uncomment if using
|
|
218
|
+
# auto-import.
|
|
219
|
+
# .idea/artifacts
|
|
220
|
+
# .idea/compiler.xml
|
|
221
|
+
# .idea/jarRepositories.xml
|
|
222
|
+
# .idea/modules.xml
|
|
223
|
+
# .idea/*.iml
|
|
224
|
+
# .idea/modules
|
|
225
|
+
# *.iml
|
|
226
|
+
# *.ipr
|
|
227
|
+
|
|
228
|
+
# CMake
|
|
229
|
+
cmake-build-*/
|
|
230
|
+
|
|
231
|
+
# Mongo Explorer plugin
|
|
232
|
+
.idea/**/mongoSettings.xml
|
|
233
|
+
|
|
234
|
+
# File-based project format
|
|
235
|
+
*.iws
|
|
236
|
+
|
|
237
|
+
# IntelliJ
|
|
238
|
+
out/
|
|
239
|
+
|
|
240
|
+
# mpeltonen/sbt-idea plugin
|
|
241
|
+
.idea_modules/
|
|
242
|
+
|
|
243
|
+
# JIRA plugin
|
|
244
|
+
atlassian-ide-plugin.xml
|
|
245
|
+
|
|
246
|
+
# Cursive Clojure plugin
|
|
247
|
+
.idea/replstate.xml
|
|
248
|
+
|
|
249
|
+
# SonarLint plugin
|
|
250
|
+
.idea/sonarlint/
|
|
251
|
+
.idea/sonarlint.xml # see https://community.sonarsource.com/t/is-the-file-idea-idea-idea-sonarlint-xml-intended-to-be-under-source-control/121119
|
|
252
|
+
|
|
253
|
+
# Crashlytics plugin (for Android Studio and IntelliJ)
|
|
254
|
+
com_crashlytics_export_strings.xml
|
|
255
|
+
crashlytics.properties
|
|
256
|
+
crashlytics-build.properties
|
|
257
|
+
fabric.properties
|
|
258
|
+
|
|
259
|
+
# Editor-based HTTP Client
|
|
260
|
+
.idea/httpRequests
|
|
261
|
+
http-client.private.env.json
|
|
262
|
+
|
|
263
|
+
# Android studio 3.1+ serialized cache file
|
|
264
|
+
.idea/caches/build_file_checksums.ser
|
|
265
|
+
|
|
266
|
+
# Apifox Helper cache
|
|
267
|
+
.idea/.cache/.Apifox_Helper
|
|
268
|
+
.idea/ApifoxUploaderProjectSetting.xml
|
|
269
|
+
|
|
270
|
+
# Github Copilot persisted session migrations, see: https://github.com/microsoft/copilot-intellij-feedback/issues/712#issuecomment-3322062215
|
|
271
|
+
.idea/**/copilot.data.migration.*.xml
|
|
272
|
+
|
|
273
|
+
# Abstra
|
|
274
|
+
# Abstra is an AI-powered process automation framework.
|
|
275
|
+
# Ignore directories containing user credentials, local state, and settings.
|
|
276
|
+
# Learn more at https://abstra.io/docs
|
|
277
|
+
.abstra/
|
|
278
|
+
|
|
279
|
+
# Visual Studio Code
|
|
280
|
+
# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
|
|
281
|
+
# that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
|
|
282
|
+
# and can be added to the global gitignore or merged into this file. However, if you prefer,
|
|
283
|
+
# you could uncomment the following to ignore the entire vscode folder
|
|
284
|
+
# .vscode/
|
|
285
|
+
|
|
286
|
+
# Ruff stuff:
|
|
287
|
+
.ruff_cache/
|
|
288
|
+
|
|
289
|
+
# PyPI configuration file
|
|
290
|
+
.pypirc
|
|
291
|
+
|
|
292
|
+
# Marimo
|
|
293
|
+
marimo/_static/
|
|
294
|
+
marimo/_lsp/
|
|
295
|
+
__marimo__/
|
|
296
|
+
|
|
297
|
+
# Streamlit
|
|
298
|
+
.streamlit/secrets.toml
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
## Setup
|
|
4
|
+
- `uv sync` installs runtime + dev deps (`[dependency-groups] dev`: pytest, pytest-asyncio, ruff, httpx, fastapi,
|
|
5
|
+
uvicorn). `uv.lock` is committed; use `uv add`/`uv sync`. Optional extras: `onnx`, `server`
|
|
6
|
+
(fastapi+uvicorn for `mezzo-guard serve`), `client` (httpx for `mezzoguard.remote`).
|
|
7
|
+
- `torch` is intentionally not a dependency (only `transformers`, `huggingface_hub`). Model loading raises with a
|
|
8
|
+
"pip install torch" hint; the ONNX backend needs the `onnx` extra. The fast test suite needs neither torch nor network.
|
|
9
|
+
|
|
10
|
+
## Commands
|
|
11
|
+
- Fast offline suite: `uv run pytest tests/test_*.py`
|
|
12
|
+
- Single test: `uv run pytest tests/test_guards.py::test_scan_returns_scores`
|
|
13
|
+
- Lint: `uv run ruff check .` — Format: `uv run ruff format .` (line-length 120, target py311)
|
|
14
|
+
- Do not run bare `uv run pytest`: it collects `tests/cache_test.py` (matches pytest's `*_test.py` default), which
|
|
15
|
+
executes at import, downloads real HF models, and calls `sys.exit(1)` if its checks fail.
|
|
16
|
+
- `tests/compile_test.py` and `tests/onnx_benchmark.py` are manual benchmark scripts (`uv run python tests/...`),
|
|
17
|
+
not pytest tests; they need real model downloads plus torch/onnx.
|
|
18
|
+
- No CI or pre-commit: run ruff and the test suite locally.
|
|
19
|
+
|
|
20
|
+
## Architecture
|
|
21
|
+
- `src/mezzoguard/model.py`: `Model` owns the local inference machinery — HF pipeline loading, tokenizer chunk offsets
|
|
22
|
+
(`_chunk_text`), LRU cache (`_predict`), async via `run_in_executor`. It knows nothing about categories or policies.
|
|
23
|
+
- `guard/` is the single guard package (`config`, `guard`, `policy`, `result`). `Guard(GuardBase, Model)` auto-selects
|
|
24
|
+
a preset (or a `.mezzoguard` config), always calls the pipeline with `top_k=None`, and exposes one score per
|
|
25
|
+
configured category. Prompt models therefore yield `{"unsafe": score}`, content models yield per-category scores.
|
|
26
|
+
`GuardConfig` normalizes labels and drops any category named `safe`; there is no prompt/content class split. Shared
|
|
27
|
+
helpers live in `base_classes.py` (`ModelConfig`, `GuardBase`, `_redact_text_with_spans`, decorator factories,
|
|
28
|
+
`_warn_if_deprecated`).
|
|
29
|
+
- `GuardBase` is the shared ABC for local and remote guards. Only `batch_scan`/`async_batch_scan`/`batch_redact`/
|
|
30
|
+
`async_batch_redact` are abstract; the single-text `scan`/`redact` adapters and the `scan_before_exec`/
|
|
31
|
+
`redact_before_exec` factories are concrete and shared. `Guard` and `APIGuard` both inherit it.
|
|
32
|
+
- Version is single-sourced from `__version__` in `src/mezzoguard/__init__.py` (hatch `[tool.hatch.version]`).
|
|
33
|
+
- `pyproject.toml` force-includes `src/mezzoguard/py.typed` (empty marker file, present); console script
|
|
34
|
+
`mezzo-guard = mezzoguard.cli:main`.
|
|
35
|
+
|
|
36
|
+
### Server, CLI, remote clients
|
|
37
|
+
- `cli.py` (`mezzo-guard serve <model>`) is argparse-only and imports `server`/guards lazily so `--help` works
|
|
38
|
+
without fastapi or torch. There is no guard-type flag; `create_guard(model, **kwargs)` always builds the unified
|
|
39
|
+
`mezzoguard.guard.Guard`. `create_guard`/`run_server` are module-level for tests to monkeypatch.
|
|
40
|
+
- `server/` (extra `server`): `create_app(guard, *, max_batch_texts=..., max_text_chars=...)` wraps an already-loaded
|
|
41
|
+
`Guard` in FastAPI with `GET /healthz`, `GET /v1/info`, `POST /v1/scan`, `POST /v1/redact`. Endpoints call
|
|
42
|
+
`async_batch_scan`/`async_batch_redact`; the lifespan ejects the model on shutdown. Policy wire format is
|
|
43
|
+
`{category: threshold}` plus optional `default_threshold` (falls back to `confidence`); `/v1/info` lists the
|
|
44
|
+
categories declared by the loaded guard's config. `dtype`/`device` are metadata only (no request-time overrides).
|
|
45
|
+
- `remote.py` (extra `client`): `APIGuard(url)` mirrors the local Guard API (including `async_*` and `*_before_exec`)
|
|
46
|
+
and rebuilds real `Result`/`Span` objects; `guard.info` lazily GETs `/v1/info`. httpx is imported lazily;
|
|
47
|
+
`MezzoGuardServerError` wraps non-2xx responses.
|
|
48
|
+
- `Policy.to_dict()` and the `Result.chunks` properties exist for (de)serialization across the wire.
|
|
49
|
+
|
|
50
|
+
### Model loading, precision, "quantization", ONNX
|
|
51
|
+
- `load_model()` is lazy and idempotent (`if self.pipeline: return`); a missing torch raises `RuntimeError` with the
|
|
52
|
+
install hint. `eject_model()` (or the context manager) drops the pipeline and empties the CUDA cache.
|
|
53
|
+
- `dtype="auto"` resolves to `torch.bfloat16` when `torch.cuda.is_bf16_supported()` else `torch.float16` (CPU
|
|
54
|
+
included). There is no calibration or quantization code anywhere: the only precision knobs are `dtype`,
|
|
55
|
+
`torch_compile`, and `use_onnx` (which are mutually exclusive).
|
|
56
|
+
- Default path calls `transformers.pipeline(task, model=self.name, dtype=...)` with the model id as a string, so
|
|
57
|
+
transformers can retry the load in fp32 when the requested dtype fails on the device. The `torch_compile` path loads
|
|
58
|
+
`AutoModelForSequenceClassification` itself and sets `model.forward = torch.compile(..., mode=..., dynamic=True)`,
|
|
59
|
+
so it does not get that fallback.
|
|
60
|
+
- ONNX (`use_onnx=True`, requires the `onnx` extra): exports/reuses `ORTModelForSequenceClassification` artifacts under
|
|
61
|
+
`~/.cache/mezzoguard/onnx/<model-name>` (`_resolve_onnx_dir`), loading with `export=False` afterwards. `dtype` is
|
|
62
|
+
never passed to the ORT model's `from_pretrained`, and `transformers.pipeline()` drops `dtype` for pre-instantiated
|
|
63
|
+
models, so `dtype="int8"` (as in `tests/onnx_benchmark.py`) is a silent no-op — implementing real int8 means calling
|
|
64
|
+
`optimum.ORTQuantizer` during export, not passing `dtype`.
|
|
65
|
+
- `_strip_token_type_ids()` wraps `forward` for models whose signature lacks `token_type_ids`; `load_model` imports
|
|
66
|
+
`torch`/`transformers` lazily so importing `mezzoguard` works without them.
|
|
67
|
+
- `device` (`None` default = current behavior, `"auto"` = CUDA when available) is passed to `transformers.pipeline`
|
|
68
|
+
on the torch paths and mapped to an ONNX execution provider (`CPUExecutionProvider`/`CUDAExecutionProvider`) on
|
|
69
|
+
the ONNX path; ONNX only supports `cpu`/`cuda`.
|
|
70
|
+
|
|
71
|
+
### Scan / redact internals
|
|
72
|
+
- `_chunk_text` uses the pipeline tokenizer's `offset_mapping` to return character `(start, end)` spans that cover the
|
|
73
|
+
text losslessly; `overlap >= max_seq_length` raises `ValueError`, and consecutive spans intentionally overlap.
|
|
74
|
+
- `batch_scan` flattens the chunks of every input text into one `_predict` call, then regroups them per text. Empty or
|
|
75
|
+
whitespace-only text yields no chunks and therefore zero/empty scores.
|
|
76
|
+
- `Guard._from_prediction` maps each chunk label through `config.get_category_for_label`, ignores labels that are not
|
|
77
|
+
configured (including `"safe"`), takes the per-category max across chunks, and keeps normalized `chunks` (one list of
|
|
78
|
+
label/score dicts per chunk).
|
|
79
|
+
`_predict` always passes `top_k=None` (all labels per chunk). Scores are initialized to `0.0` for every configured
|
|
80
|
+
category, so empty text still returns a complete score mapping.
|
|
81
|
+
- `_predict` de-duplicates repeated chunk texts within a batch and caches results keyed by exact chunk text.
|
|
82
|
+
`mezzoguard/config.py` `cache_enabled` is checked on every call, but `cache_maxsize` is bound as a default argument
|
|
83
|
+
in `TextLRUCache.__init__` at import time, so changing it at runtime does not resize existing or new caches.
|
|
84
|
+
- `_redact_text_with_spans` (base_classes.py) walks spans in order, merges consecutive flagged chunks into one
|
|
85
|
+
replacement, and skips text already covered by overlap, so output preserves the original text exactly except flagged
|
|
86
|
+
runs. `replace` may be a per-category dict keyed by raw category strings; unknown categories fall back to `[REDACTED]`.
|
|
87
|
+
- When `policy=None`, a default `Policy(default_threshold=confidence)` is used; thresholds are inclusive
|
|
88
|
+
(`score >= threshold`). An explicit policy without `default_threshold` keeps the backwards-compatible `0.0` fallback.
|
|
89
|
+
Returned `Span.start` is the cursor before the flagged run, so leading overlap is included.
|
|
90
|
+
|
|
91
|
+
### Config and categories
|
|
92
|
+
- `guard/config.py` `MODELS_CONFIG` is the single source of truth for supported model ids. A preset wins over a
|
|
93
|
+
`.mezzoguard` JSON fetched from the HF repo (`ModelConfig.from_model_name`, also works on a local model dir); the
|
|
94
|
+
JSON is used only when no preset exists. Neither → warning, `guard.config is None`.
|
|
95
|
+
- `GuardConfig` normalizes labels (strip, lowercase, `_`/space → `-`) and drops any category named `safe`. Categories
|
|
96
|
+
are raw strings; safe labels are simply not listed as scored categories.
|
|
97
|
+
- `ModelConfig` no longer carries a model type.
|
|
98
|
+
- A repo README's YAML frontmatter `new_version` marks the model deprecated and emits a `DeprecationWarning`
|
|
99
|
+
(`ModelConfig._parse_readme`); `from_model_name` and `get_deprecation_from_readme` are `lru_cache`d.
|
|
100
|
+
|
|
101
|
+
## Tests
|
|
102
|
+
- Use the `prompt_guard` / `content_guard` fixtures from `tests/conftest.py` (both are the same unified `Guard`, just
|
|
103
|
+
with different fake pipelines); they monkeypatch `ModelConfig` and `Model.load_model` with `FakePipeline`.
|
|
104
|
+
Constructing a real `Guard` hits the network.
|
|
105
|
+
- `FakePipeline` flags marker words: prompt guard → "kill"/"weapon"/"steal"; content guard → "kill" (violence/toxic),
|
|
106
|
+
"fuck" (sexual), "stupid" (hate-speech), "hurt"/"suicide" (self-harm), "fight" (violence).
|
|
107
|
+
- `asyncio_mode = "auto"` (pyproject), so async tests need no `@pytest.mark.asyncio`.
|
|
108
|
+
- `test_server.py` uses `fastapi.testclient.TestClient` over fake-pipeline guards; `test_remote.py` starts a
|
|
109
|
+
`uvicorn.Server` in a daemon thread on port 0 with the same fakes. Both stay offline and fast.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 RyanStudioo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: mezzo-guard
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Mezzo Guard is a Python SDK designed to provide AI-based content moderation and security for applications.
|
|
5
|
+
Author-email: Ryan Studio <ryanstudiobusiness@gmail.com>
|
|
6
|
+
Maintainer-email: Ryan Studio <ryanstudiobusiness@gmail.com>
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Keywords: LLM,ai,ai model,ai moderation,ai safety,application security,artificial intelligence,content guard,content moderation,content safety,guard,inference,jailbreak,language model,mezzo,mezzo ai,mezzo content guard,mezzo guard,mezzo jailbreak guard,mezzo moderation guard,mezzo prompt guard,mezzo security,model safety,moderation,prompt guard,prompt injection,python sdk,sdk,security
|
|
9
|
+
Requires-Python: >=3.11
|
|
10
|
+
Requires-Dist: huggingface-hub>=0.25
|
|
11
|
+
Requires-Dist: transformers<6,>=4.51
|
|
12
|
+
Provides-Extra: client
|
|
13
|
+
Requires-Dist: httpx<1,>=0.27; extra == 'client'
|
|
14
|
+
Provides-Extra: onnx
|
|
15
|
+
Requires-Dist: optimum[onnxruntime]; extra == 'onnx'
|
|
16
|
+
Provides-Extra: server
|
|
17
|
+
Requires-Dist: fastapi<1,>=0.115; extra == 'server'
|
|
18
|
+
Requires-Dist: uvicorn[standard]<1,>=0.30; extra == 'server'
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# Mezzo Guard
|
|
22
|
+
|
|
23
|
+
Mezzo Guard is a Python SDK designed to use AI-based solutions to protect your applications such as prompt protection
|
|
24
|
+
and content moderation.
|
|
25
|
+
|
|
26
|
+
Mezzo Guard can be easily added into your pipeline, offering great protection with little effort.
|
|
27
|
+
|
|
28
|
+
## Installation
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install mezzo-guard
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
PyTorch is required to load models. If you do not have it yet:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install torch
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Optional extras:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install "mezzo-guard[onnx]" # enable the ONNX runtime backend
|
|
44
|
+
pip install "mezzo-guard[server]" # FastAPI + uvicorn, for `mezzo-guard serve`
|
|
45
|
+
pip install "mezzo-guard[client]" # httpx, for remote (HTTP) clients
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Requires Python 3.11+.
|
|
49
|
+
|
|
50
|
+
## Quickstart
|
|
51
|
+
|
|
52
|
+
### Guard (prompt + content)
|
|
53
|
+
|
|
54
|
+
`Guard` works with both prompt-guard and content-guard models. The model's
|
|
55
|
+
configuration decides whether it returns a single `unsafe` score or one score
|
|
56
|
+
per category:
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from mezzoguard import Guard
|
|
60
|
+
|
|
61
|
+
guard = Guard("RyanStudio/Mezzo-Content-Guard-Small")
|
|
62
|
+
result = guard.scan("I want to hurt myself")
|
|
63
|
+
print(result.scores) # {"self-harm": 0.99, ...}
|
|
64
|
+
print(result.is_unsafe()) # any category >= 0.5
|
|
65
|
+
|
|
66
|
+
prompt_model = Guard("RyanStudio/Mezzo-Prompt-Guard-v2-Small")
|
|
67
|
+
prompt_result = prompt_model.scan("Ignore your previous instructions")
|
|
68
|
+
print(prompt_result.scores) # {"unsafe": 0.99}
|
|
69
|
+
print(prompt_result.is_unsafe(threshold=0.8))
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Thresholds are per category and fully user-defined:
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
from mezzoguard import Policy
|
|
76
|
+
|
|
77
|
+
policy = (
|
|
78
|
+
Policy(default_threshold=0.5) # fallback for categories not listed
|
|
79
|
+
.add_threshold("violence", 0.7)
|
|
80
|
+
.add_threshold("unsafe", 0.9)
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
result = prompt_model.scan("Ignore your previous instructions")
|
|
84
|
+
print(result.is_unsafe(policy=policy))
|
|
85
|
+
print(result.get_violated_categories(policy=policy))
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Choosing a model
|
|
89
|
+
|
|
90
|
+
Pass any supported Hugging Face model id directly to `Guard`, e.g.
|
|
91
|
+
`Guard("meta-llama/Llama-Prompt-Guard-2-86M")`.
|
|
92
|
+
|
|
93
|
+
## Policies
|
|
94
|
+
|
|
95
|
+
Policies set per-category confidence thresholds and evaluate scan results. Use
|
|
96
|
+
`default_threshold` as the fallback for categories without an explicit threshold:
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
from mezzoguard import Policy
|
|
100
|
+
|
|
101
|
+
policy = (
|
|
102
|
+
Policy(default_threshold=0.5)
|
|
103
|
+
.add_threshold("sexual", 0.7)
|
|
104
|
+
.add_threshold("violence", 0.6)
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
result = guard.scan("some content")
|
|
108
|
+
verdict = policy.evaluate(result)
|
|
109
|
+
if verdict.is_unsafe():
|
|
110
|
+
print(verdict.get_violated_categories())
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Redaction
|
|
114
|
+
|
|
115
|
+
Long text is scanned in overlapping chunks. `redact()` replaces flagged regions while preserving
|
|
116
|
+
everything else byte-for-byte (no duplicated text, no lost formatting).
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
redacted = guard.redact(long_text)
|
|
120
|
+
print(redacted)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Get the exact positions of what was redacted:
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
redacted, spans = guard.redact(long_text, return_spans=True)
|
|
127
|
+
for span in spans:
|
|
128
|
+
print(span.start, span.end, span.category) # character offsets into the original text
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Redaction operates per-chunk: a chunk containing any flagged content is a candidate for
|
|
132
|
+
replacement, and consecutive flagged chunks are merged into a single marker. Tune `max_seq_length`
|
|
133
|
+
(smaller chunks = finer-grained redaction) and `overlap` as needed.
|
|
134
|
+
|
|
135
|
+
Custom replacements, per category:
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
guard.redact(text, replace={"violence": "[VIOLENCE]", "sexual": "[SEXUAL]"})
|
|
139
|
+
# categories without an explicit replacement fall back to "[REDACTED]"
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Guarding function calls
|
|
143
|
+
|
|
144
|
+
Wrap any function so its input is scanned (raising on unsafe input) or redacted before execution.
|
|
145
|
+
Both sync and async functions are supported.
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
@guard.scan_before_exec(param="prompt", confidence=0.5)
|
|
149
|
+
def chat(prompt: str) -> str:
|
|
150
|
+
return generate(prompt) # never called with an unsafe prompt
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
@guard.redact_before_exec(param="prompt")
|
|
154
|
+
async def chat_async(prompt: str) -> str:
|
|
155
|
+
return generate(prompt)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Guards raise `mezzoguard.UnsafeInputError`, which carries the violated
|
|
159
|
+
categories as `{category: score}` entries.
|
|
160
|
+
|
|
161
|
+
## Async and batching
|
|
162
|
+
|
|
163
|
+
The `async_*` variants never block the event loop. Batch methods are the primitives: they scan or
|
|
164
|
+
redact many texts in a single pipeline call, and the single-text methods delegate to them with a
|
|
165
|
+
one-element batch.
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
results = guard.batch_scan(["text one", "text two"])
|
|
169
|
+
redacted = guard.batch_redact(["text one", "text two"])
|
|
170
|
+
redacted, spans_list = guard.batch_redact(texts, return_spans=True)
|
|
171
|
+
|
|
172
|
+
results = await guard.async_batch_scan(texts)
|
|
173
|
+
redacted = await guard.async_batch_redact(texts)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Performance options
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
# bf16/fp16 on GPU (default "auto" detection)
|
|
180
|
+
Guard(name, dtype="float16")
|
|
181
|
+
|
|
182
|
+
# torch.compile the model
|
|
183
|
+
Guard(name, torch_compile=True)
|
|
184
|
+
|
|
185
|
+
# ONNX Runtime backend (artifacts are exported once, then cached on disk)
|
|
186
|
+
Guard(name, use_onnx=True)
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
To free GPU/CPU memory, call `guard.eject_model()` or use a context manager:
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
with Guard(name) as guard:
|
|
193
|
+
...
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Serving over HTTP
|
|
197
|
+
|
|
198
|
+
Install the server extra and serve a model:
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
pip install "mezzo-guard[server]"
|
|
202
|
+
mezzo-guard serve RyanStudio/Mezzo-Content-Guard-v1.5-Small --dtype float16
|
|
203
|
+
# Serving RyanStudio/Mezzo-Content-Guard-v1.5-Small on http://127.0.0.1:8000
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
The model's config decides whether it behaves like a prompt guard or a content guard.
|
|
207
|
+
Performance flags match the SDK:
|
|
208
|
+
`--dtype`, `--onnx`, `--torch-compile`, `--compile-mode` and `--device`
|
|
209
|
+
(`auto`, `cpu`, `cuda`, `cuda:N`, `mps`). Request size limits are set with
|
|
210
|
+
`--max-batch-texts` and `--max-text-chars`. Interactive OpenAPI docs are at `/docs`.
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
curl -s http://127.0.0.1:8000/v1/scan \
|
|
214
|
+
-H 'content-type: application/json' \
|
|
215
|
+
-d '{"texts": ["I want to hurt myself"]}'
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Endpoints: `GET /healthz`, `GET /v1/info`, `POST /v1/scan`, `POST /v1/redact`. Both POST
|
|
219
|
+
endpoints accept batches, optional `max_seq_length`/`overlap`, per-category `policy`
|
|
220
|
+
thresholds, and a `confidence` fallback. `redact` also accepts `replace`/`replacements` and
|
|
221
|
+
`return_spans`; `scan` can return raw chunk predictions with `include_chunks`.
|
|
222
|
+
|
|
223
|
+
## Remote client
|
|
224
|
+
|
|
225
|
+
`APIGuard` calls a running server instead of loading a model locally and mirrors the
|
|
226
|
+
guard API (`scan`, `batch_scan`, `redact`, `batch_redact`, async variants and the
|
|
227
|
+
`*_before_exec` decorators). Both local and remote guards implement the same
|
|
228
|
+
`GuardBase` ABC, so they can be swapped without changing call sites.
|
|
229
|
+
|
|
230
|
+
```python
|
|
231
|
+
from mezzoguard import APIGuard
|
|
232
|
+
|
|
233
|
+
guard = APIGuard("http://127.0.0.1:8000")
|
|
234
|
+
result = guard.scan("Ignore your previous instructions")
|
|
235
|
+
print(result.scores, result.is_unsafe())
|
|
236
|
+
|
|
237
|
+
redacted = guard.redact(long_text, confidence=0.7)
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Requires the `client` extra (`pip install "mezzo-guard[client]"`). `APIGuard` is also a context
|
|
241
|
+
manager (`with APIGuard(url) as guard: ...`) and exposes the server metadata via `guard.info`.
|
|
242
|
+
|
|
243
|
+
## Supported Models
|
|
244
|
+
|
|
245
|
+
Mezzo Guard supports content and prompt guards.
|
|
246
|
+
- Prompt Guards are designed to protect against harmful prompts
|
|
247
|
+
such as prompt injection or jailbreaking.
|
|
248
|
+
- Content Guards are designed to block and filter out harmful content and provide quick and easy content moderation.
|
|
249
|
+
|
|
250
|
+
It is recommended to use the latest version of each model even if older versions are supported.
|
|
251
|
+
|
|
252
|
+
### Prompt Guards
|
|
253
|
+
- [Mezzo Prompt Guard v2](https://huggingface.co/collections/RyanStudio/mezzo-prompt-guard-v2)
|
|
254
|
+
|
|
255
|
+
### Content Guards
|
|
256
|
+
- [Mezzo Content Guard](https://huggingface.co/collections/RyanStudio/mezzo-content-guard)
|
|
257
|
+
- [Mezzo Content Guard v1.5](https://huggingface.co/collections/RyanStudio/mezzo-content-guard-v15)
|