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.
Files changed (37) hide show
  1. mezzo_guard-0.1.0/.gitignore +298 -0
  2. mezzo_guard-0.1.0/AGENTS.md +109 -0
  3. mezzo_guard-0.1.0/LICENSE +21 -0
  4. mezzo_guard-0.1.0/PKG-INFO +257 -0
  5. mezzo_guard-0.1.0/README.md +237 -0
  6. mezzo_guard-0.1.0/pyproject.toml +72 -0
  7. mezzo_guard-0.1.0/src/mezzoguard/__init__.py +23 -0
  8. mezzo_guard-0.1.0/src/mezzoguard/_types.py +24 -0
  9. mezzo_guard-0.1.0/src/mezzoguard/base_classes.py +466 -0
  10. mezzo_guard-0.1.0/src/mezzoguard/cache.py +35 -0
  11. mezzo_guard-0.1.0/src/mezzoguard/cli.py +102 -0
  12. mezzo_guard-0.1.0/src/mezzoguard/config.py +2 -0
  13. mezzo_guard-0.1.0/src/mezzoguard/errors.py +19 -0
  14. mezzo_guard-0.1.0/src/mezzoguard/guard/__init__.py +16 -0
  15. mezzo_guard-0.1.0/src/mezzoguard/guard/config.py +58 -0
  16. mezzo_guard-0.1.0/src/mezzoguard/guard/guard.py +206 -0
  17. mezzo_guard-0.1.0/src/mezzoguard/guard/policy.py +40 -0
  18. mezzo_guard-0.1.0/src/mezzoguard/guard/result.py +77 -0
  19. mezzo_guard-0.1.0/src/mezzoguard/model.py +222 -0
  20. mezzo_guard-0.1.0/src/mezzoguard/py.typed +0 -0
  21. mezzo_guard-0.1.0/src/mezzoguard/remote.py +206 -0
  22. mezzo_guard-0.1.0/src/mezzoguard/server/__init__.py +3 -0
  23. mezzo_guard-0.1.0/src/mezzoguard/server/app.py +166 -0
  24. mezzo_guard-0.1.0/src/mezzoguard/server/schemas.py +71 -0
  25. mezzo_guard-0.1.0/src/mezzoguard/server/serialize.py +20 -0
  26. mezzo_guard-0.1.0/tests/cache_test.py +240 -0
  27. mezzo_guard-0.1.0/tests/compile_test.py +21 -0
  28. mezzo_guard-0.1.0/tests/conftest.py +103 -0
  29. mezzo_guard-0.1.0/tests/onnx_benchmark.py +77 -0
  30. mezzo_guard-0.1.0/tests/test_chunking.py +45 -0
  31. mezzo_guard-0.1.0/tests/test_cli.py +88 -0
  32. mezzo_guard-0.1.0/tests/test_guards.py +281 -0
  33. mezzo_guard-0.1.0/tests/test_policy.py +84 -0
  34. mezzo_guard-0.1.0/tests/test_redaction.py +128 -0
  35. mezzo_guard-0.1.0/tests/test_remote.py +115 -0
  36. mezzo_guard-0.1.0/tests/test_server.py +128 -0
  37. 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)