haloguard 0.1.1__tar.gz

haloguard-0.1.1/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

haloguard-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check src tests scripts
+      - name: Mypy
+        run: mypy
+      - name: pip-audit
+        run: pip-audit
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest tests -v
+
+  install-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Fresh-venv install smoke test
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install .
+          /tmp/smoke/bin/haloguard version

haloguard-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and sdist
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run test suite before publishing
+        run: |
+          pip install -e ".[dev]"
+          pytest tests -v
+
+  publish:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: [publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract changelog section for this version
+        id: changelog
+        run: |
+          python - <<'EOF'
+          import re
+          from pathlib import Path
+          text = Path("CHANGELOG.md").read_text(encoding="utf-8")
+          version = "${{ github.ref_name }}".lstrip("v")
+          pattern = rf"## \[{re.escape(version)}\]\n(.*?)(?=\n## \[|\Z)"
+          match = re.search(pattern, text, flags=re.DOTALL)
+          body = match.group(1).strip() if match else "See CHANGELOG.md"
+          Path("release_notes.md").write_text(body + "\n", encoding="utf-8")
+          EOF
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release_notes.md
+          files: dist/*

haloguard-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+*.onnx
+*.bin
+HaloGuard_System_Architecture.docx
+*.data

haloguard-0.1.1/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial scaffold: `src/haloguard/` layout with `core/` and `scorers/` subpackages.
+- Exception hierarchy (`HaloGuardError`, `ModelLoadError`, `InputTooLargeError`,
+  `InferenceTimeoutError`, `ConfigError`).
+- `FirewallResult` frozen dataclass contract.
+- Golden dataset of 15 hand-labeled (context, response) pairs used to validate
+  entailment scoring (`tests/golden_dataset/labeled_pairs.jsonl`).
+- `Firewall.check()` / `acheck()` / `check_batch()` backed by ONNX Runtime (CPU),
+  with fail-open/fail-closed behaviour, input size caps, and an inference timeout.
+- Consistency mode: context-free scoring by cross-checking the response's own
+  claims pairwise with the NLI model (batched inference).
+- `FirewallInput` / `FirewallResult` contract shared by SDK, CLI, and hooks.
+- Typer CLI (`haloguard check`, `haloguard version`) with exit codes
+  0 PASS / 1 FLAG / 2 BLOCK / 3 internal error and `--json` output.
+- Integrations: LangChain callback handler, LlamaIndex-style query hook, and
+  raw client adapters (OpenAI / Anthropic / Ollama) via `guarded_call`.
+- `models/` subpackage: pinned SHA256 manifest verified on every load, plus a
+  local cache dir (`platformdirs`) with `HALOGUARD_MODEL_DIR` override.
+- `scripts/export_onnx.py` to rebuild the ONNX artifact from the source model.
+- GitHub Actions CI (lint, type-check, 3 OS x Python 3.9-3.12 test matrix,
+  fresh-venv install smoke test, pip-audit) and PyPI trusted-publishing
+  release workflow gated on version tags.
+
+### Changed
+- Quantization strategy: naive dynamic INT8 quantization measurably hurt accuracy
+  (a borderline hallucination's risk dropped 0.84 -> 0.33, flipping it to PASS).
+  Switched to static uint8 quantization with graph preprocessing and calibration
+  data, which keeps golden-set verdicts identical to the torch reference.
+- Runtime inference uses `onnxruntime` + `tokenizers` only; `sentence-transformers`
+  / torch moved to the optional `export` extra.
+
+### Notes
+- The quantized artifact is ~161MB (fp32 export ~568MB), larger than the design
+  doc's ~35-90MB estimate: DeBERTa-v3's 128k-vocabulary embedding dominates the
+  file size. Install-size expectations in the doc should be revised accordingly.

haloguard-0.1.1/LICENSE

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

haloguard-0.1.1/MANIFEST.in

@@ -0,0 +1,6 @@
+exclude *.data
+exclude *.onnx
+exclude *.docx
+prune .mypy_cache
+prune .pytest_cache
+prune .ruff_cache

haloguard-0.1.1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: haloguard
+Version: 0.1.1
+Summary: Local-first hallucination firewall for LLM applications
+Project-URL: Homepage, https://github.com/KunalSoyane/Halogaurd
+Project-URL: Issues, https://github.com/KunalSoyane/Halogaurd/issues
+Project-URL: Changelog, https://github.com/KunalSoyane/Halogaurd/blob/main/CHANGELOG.md
+Author: Kunal Soyane
+License-Expression: MIT
+License-File: LICENSE
+Keywords: hallucination,llm,nli,onnx,rag,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: tokenizers>=0.19
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: export
+Requires-Dist: optimum[onnxruntime]>=1.21; extra == 'export'
+Requires-Dist: sentence-transformers<6,>=3.0; extra == 'export'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == 'llamaindex'
+Description-Content-Type: text/markdown
+
+# HaloGuard
+
+A local-first hallucination firewall for LLM applications. HaloGuard sits between an
+LLM and the application consuming its output, scoring every response for hallucination
+risk before it reaches a user. Everything runs on the caller's machine -- no prompt,
+response, or context ever leaves the device.
+
+## Scoring modes
+
+- **Entailment mode** (RAG-style): scores whether the response is supported by supplied
+  source context, using an NLI cross-encoder (`DeBERTa-v3-small`, ONNX, quantized).
+- **Consistency mode** (no context): scores whether the response is internally
+  consistent, cross-checking its own claims with the same NLI model.
+
+Mode is selected automatically by input shape (`auto`), or set explicitly.
+
+## Install
+
+```bash
+pip install haloguard
+```
+
+One-time model setup (builds the ONNX artifact into your local cache):
+
+```bash
+pip install "haloguard[export]"
+python scripts/export_onnx.py
+```
+
+## SDK quickstart
+
+```python
+from haloguard import Firewall
+
+fw = Firewall()  # threshold=0.7, block_threshold=0.9, mode="auto"
+
+# Entailment mode: context supplied
+result = fw.check(
+    prompt="Where is the Eiffel Tower?",
+    response="The Eiffel Tower is in Paris.",
+    context="The Eiffel Tower is located in Paris and was completed in 1889.",
+)
+print(result.verdict, result.score, result.reason)
+
+# Consistency mode: no context
+result = fw.check(
+    prompt="When is the meeting?",
+    response="The meeting is on Tuesday. The meeting is on Friday.",
+)
+```
+
+Every check returns a `FirewallResult`. Also available: `acheck()` (async),
+`check_batch()` (many items over one loaded session).
+
+## CLI
+
+```bash
+haloguard check --prompt "..." --response "..."                 # consistency mode
+haloguard check --prompt "..." --response "..." --context FILE  # entailment mode
+haloguard check ... --json                                      # machine-readable
+haloguard version
+```
+
+Exit codes: `0` PASS / `1` FLAG / `2` BLOCK / `3` internal error (incl. UNKNOWN).
+
+## Framework hooks
+
+```python
+# LangChain:  pip install "haloguard[langchain]"
+from haloguard.integrations.langchain_handler import HaloGuardCallbackHandler
+handler = HaloGuardCallbackHandler(context_provider=lambda _text: retrieved_context)
+
+# LlamaIndex-style query responses (duck-typed, no hard dependency)
+from haloguard.integrations.llamaindex_handler import HaloGuardQueryHook
+result = HaloGuardQueryHook().check_response(query_response)
+
+# Any client SDK: adapt to generate(prompt) -> str, then score
+from haloguard.integrations.raw_wrappers import guarded_call, openai_generate
+response, result = guarded_call(openai_generate(client), prompt, context=context)
+```
+
+## Verdicts
+
+- `score` -- 0.0-1.0 hallucination risk (higher = more likely hallucinated)
+- `verdict` -- `PASS` (risk < threshold), `FLAG` (threshold <= risk < block_threshold),
+  `BLOCK` (risk >= block_threshold), `UNKNOWN` (scoring failed, fail-open)
+- `reason`, `mode_used`, `latency_ms`
+
+`UNKNOWN` is the fail-open verdict returned when scoring itself fails and
+`strict_mode=False` (the default). Set `strict_mode=True` to fail closed instead.
+
+## Honest limitations
+
+HaloGuard is **defense-in-depth, not a guarantee**. An adversarially crafted response
+can read as entailed/consistent to any NLI model while still being false. The measured
+false-negative rate on the golden benchmark is the real accuracy statement; treat
+HaloGuard as one layer in a safety stack, not the only one.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests -v        # unit tests always; integration tests need model artifacts
+ruff check src tests scripts
+mypy
+```
+
+Integration tests run real inference against `tests/golden_dataset/labeled_pairs.jsonl`
+and are skipped automatically when model artifacts are absent.
+
+## License
+
+MIT

haloguard-0.1.1/README.md

@@ -0,0 +1,113 @@
+# HaloGuard
+
+A local-first hallucination firewall for LLM applications. HaloGuard sits between an
+LLM and the application consuming its output, scoring every response for hallucination
+risk before it reaches a user. Everything runs on the caller's machine -- no prompt,
+response, or context ever leaves the device.
+
+## Scoring modes
+
+- **Entailment mode** (RAG-style): scores whether the response is supported by supplied
+  source context, using an NLI cross-encoder (`DeBERTa-v3-small`, ONNX, quantized).
+- **Consistency mode** (no context): scores whether the response is internally
+  consistent, cross-checking its own claims with the same NLI model.
+
+Mode is selected automatically by input shape (`auto`), or set explicitly.
+
+## Install
+
+```bash
+pip install haloguard
+```
+
+One-time model setup (builds the ONNX artifact into your local cache):
+
+```bash
+pip install "haloguard[export]"
+python scripts/export_onnx.py
+```
+
+## SDK quickstart
+
+```python
+from haloguard import Firewall
+
+fw = Firewall()  # threshold=0.7, block_threshold=0.9, mode="auto"
+
+# Entailment mode: context supplied
+result = fw.check(
+    prompt="Where is the Eiffel Tower?",
+    response="The Eiffel Tower is in Paris.",
+    context="The Eiffel Tower is located in Paris and was completed in 1889.",
+)
+print(result.verdict, result.score, result.reason)
+
+# Consistency mode: no context
+result = fw.check(
+    prompt="When is the meeting?",
+    response="The meeting is on Tuesday. The meeting is on Friday.",
+)
+```
+
+Every check returns a `FirewallResult`. Also available: `acheck()` (async),
+`check_batch()` (many items over one loaded session).
+
+## CLI
+
+```bash
+haloguard check --prompt "..." --response "..."                 # consistency mode
+haloguard check --prompt "..." --response "..." --context FILE  # entailment mode
+haloguard check ... --json                                      # machine-readable
+haloguard version
+```
+
+Exit codes: `0` PASS / `1` FLAG / `2` BLOCK / `3` internal error (incl. UNKNOWN).
+
+## Framework hooks
+
+```python
+# LangChain:  pip install "haloguard[langchain]"
+from haloguard.integrations.langchain_handler import HaloGuardCallbackHandler
+handler = HaloGuardCallbackHandler(context_provider=lambda _text: retrieved_context)
+
+# LlamaIndex-style query responses (duck-typed, no hard dependency)
+from haloguard.integrations.llamaindex_handler import HaloGuardQueryHook
+result = HaloGuardQueryHook().check_response(query_response)
+
+# Any client SDK: adapt to generate(prompt) -> str, then score
+from haloguard.integrations.raw_wrappers import guarded_call, openai_generate
+response, result = guarded_call(openai_generate(client), prompt, context=context)
+```
+
+## Verdicts
+
+- `score` -- 0.0-1.0 hallucination risk (higher = more likely hallucinated)
+- `verdict` -- `PASS` (risk < threshold), `FLAG` (threshold <= risk < block_threshold),
+  `BLOCK` (risk >= block_threshold), `UNKNOWN` (scoring failed, fail-open)
+- `reason`, `mode_used`, `latency_ms`
+
+`UNKNOWN` is the fail-open verdict returned when scoring itself fails and
+`strict_mode=False` (the default). Set `strict_mode=True` to fail closed instead.
+
+## Honest limitations
+
+HaloGuard is **defense-in-depth, not a guarantee**. An adversarially crafted response
+can read as entailed/consistent to any NLI model while still being false. The measured
+false-negative rate on the golden benchmark is the real accuracy statement; treat
+HaloGuard as one layer in a safety stack, not the only one.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests -v        # unit tests always; integration tests need model artifacts
+ruff check src tests scripts
+mypy
+```
+
+Integration tests run real inference against `tests/golden_dataset/labeled_pairs.jsonl`
+and are skipped automatically when model artifacts are absent.
+
+## License
+
+MIT

haloguard-0.1.1/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "haloguard"
+version = "0.1.1"
+description = "Local-first hallucination firewall for LLM applications"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Kunal Soyane" }]
+keywords = ["llm", "hallucination", "nli", "rag", "safety", "onnx"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "onnxruntime>=1.17",
+    "tokenizers>=0.19",
+    "platformdirs>=4.0",
+    "pydantic>=2.7",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+export = [
+    "optimum[onnxruntime]>=1.21",
+    "sentence-transformers>=3.0,<6",
+]
+langchain = ["langchain-core>=0.2"]
+llamaindex = ["llama-index-core>=0.10"]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "pip-audit>=2.7",
+]
+
+[project.scripts]
+haloguard = "haloguard.cli.commands:app"
+
+[project.urls]
+Homepage = "https://github.com/KunalSoyane/Halogaurd"
+Issues = "https://github.com/KunalSoyane/Halogaurd/issues"
+Changelog = "https://github.com/KunalSoyane/Halogaurd/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/haloguard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: tests that run real model inference against the golden dataset",
+]
+
+[tool.ruff]
+src = ["src", "tests"]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["typer.Option", "typer.Argument"]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/*" = ["E501"]
+
+[tool.mypy]
+python_version = "3.12"
+mypy_path = "src"
+packages = ["haloguard"]
+warn_unused_ignores = true
+check_untyped_defs = true
+ignore_missing_imports = true