Release 0.5.1 to main

.github/actions/unplug-scan/README.md

@@ -27,7 +27,7 @@ jobs:
  with:
  base-ref: main
  install-mode: pypi
- unplug-version: ">=0.4.0,<0.5"
+ unplug-version: ">=0.5.0,<0.6"
 ```
 
 ## Inputs
@@ -38,7 +38,7 @@ jobs:
 | `python-version` | `3.12` | Python version |
 | `working-directory` | `sdk` | Path to SDK tree when `install-mode: local` |
 | `install-mode` | `local` | `local` (uv sync) or `pypi` (install from PyPI) |
-| `unplug-version` | `>=0.4.0,<0.5` | Version constraint for PyPI install |
+| `unplug-version` | `>=0.5.0,<0.6` | Version constraint for PyPI install |
 
 ## What gets scanned
 

.github/workflows/ci.yml

@@ -21,14 +21,14 @@ jobs:
  run:
  working-directory: sdk
  steps:
- - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
  - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
  with:
  enable-cache: true
  version: "0.6.14"
 
- - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
  with:
  python-version: ${{ matrix.python-version }}
 

.github/workflows/integrations-live.yml

@@ -42,6 +42,26 @@ jobs:
  test: tests/optional/live/test_pydantic_ai_live.py
  - extra: semantic-kernel
  test: tests/optional/live/test_semantic_kernel_live.py
+ - extra: openai-agents
+ test: tests/optional/live/test_openai_agents_live.py
+ - extra: langchain
+ test: tests/optional/live/test_langchain_live.py
+ - extra: google-adk
+ test: tests/optional/live/test_google_adk_live.py
+ - extra: smolagents
+ test: tests/optional/live/test_smolagents_live.py
+ - extra: dspy
+ test: tests/optional/live/test_dspy_live.py
+ - extra: strands
+ test: tests/optional/live/test_strands_live.py
+ - extra: letta
+ test: tests/optional/live/test_letta_live.py
+ - extra: griptape
+ test: tests/optional/live/test_griptape_live.py
+ - extra: ag2
+ test: tests/optional/live/test_ag2_live.py
+ - extra: atomic-agents
+ test: tests/optional/live/test_atomic_agents_live.py
  name: live (${{ matrix.extra }})
  defaults:
  run:
@@ -54,26 +74,32 @@ jobs:
  enable-cache: true
  version: "0.6.14"
 
- - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
  with:
  python-version: "3.12"
 
- - name: Install (one framework extra in isolation)
- run: uv sync --extra dev --extra ${{ matrix.extra }}
+ - name: Install (fresh per-framework resolution — matches `pip install "unplug-ai[extra]"`)
+ # Deliberately NOT `uv sync` from the unified lock: that lock co-resolves
+ # every extra together and pins some frameworks down to old, broken
+ # releases (e.g. semantic-kernel 1.15, which imports `Url` from
+ # `pydantic.networks` — gone in Pydantic v2). A user never installs all
+ # frameworks at once; they run `pip install "unplug-ai[langgraph]"`, which
+ # resolves that one framework freshly. We mirror that here.
+ run: |
+ uv venv
+ uv pip install -e ".[dev,${{ matrix.extra }}]"
 
  - name: Live integration test
  run: |
  set +e
-uv run pytest -q -m requires_integrations ${{ matrix.test }}
+.venv/bin/python -m pytest -q -m requires_integrations ${{ matrix.test }}
  rc=$?
  set -e
- # Exit 5 = pytest collected nothing because the module self-skipped:
- # the framework installed but is unimportable under our pinned deps
- # (e.g. an upstream release incompatible with our Pydantic v2). That is
- # an upstream conflict, not an Unplug regression — surface it loudly but
- # don't block. Real test failures (exit 1) still fail the job.
+ # Exit 5 = the module self-skipped: the framework is unimportable even
+ # under a fresh resolution (a genuine upstream break). Surface it loudly
+ # but don't block the release. Real test failures (exit 1) still fail.
  if [ "$rc" -eq 5 ]; then
- echo "::warning title=Live integration skipped::${{ matrix.extra }} installed but its live tests were skipped (framework unimportable under current deps). Tolerated; not blocking."
+ echo "::warning title=Live integration skipped::${{ matrix.extra }} installed but its live tests were skipped (framework unimportable under a fresh resolution). Tolerated; not blocking."
  exit 0
  fi
  exit $rc

.github/workflows/pr-scan.yml

@@ -17,7 +17,7 @@ jobs:
  scan:
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
  with:
  fetch-depth: 0
 

.github/workflows/publish-pypi.yml

@@ -20,14 +20,14 @@ jobs:
  run:
  working-directory: sdk
  steps:
- - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
  - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
  with:
  enable-cache: true
  version: "0.6.14"
 
- - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
  with:
  python-version: "3.12"
 

.github/workflows/reusable-agent-scan.yml

@@ -26,7 +26,7 @@ jobs:
  scan:
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
  with:
  fetch-depth: 0
 

CHANGELOG.md

@@ -2,7 +2,44 @@
 
 All notable changes to the `unplug-ai` SDK.
 
-## [Unreleased]
+## [0.5.1] — 2026-07-20
+
+### Fixed
+
+- Python 3.13: `unplug-ai[ml]` / `[all]` install without a Rust toolchain — widen `transformers` constraint to `>=4.44,<5.13` so `tokenizers` resolves to a cp313 wheel (was pinned via `transformers>=4.44,<4.45` → `tokenizers==0.19.1`)
+
+### Security
+
+- Pin bundled model catalog to immutable Hugging Face commit SHAs under `Unplug-AI/`; drop unpublished medium/large tiers that pointed at a non-existent org
+
+### Added
+
+- Beginner onboarding: [`sdk/docs/GETTING_STARTED.md`](sdk/docs/GETTING_STARTED.md) (5-minute path)
+- Agent-host guide: [`sdk/docs/AGENT_ACTIONS.md`](sdk/docs/AGENT_ACTIONS.md) (ALLOW / REVIEW / BLOCK + `ApprovalProvider`)
+- `HookDecision.needs_review` and `HookDecision.is_block` helpers for integration adapters
+- Stable public API facades under `unplug.api.*` for policy, privacy, cache,
+ boundaries, normalization, encoding, and ML runtime imports used by server/MCP
+ dependents ([`sdk/docs/PUBLIC_API.md`](sdk/docs/PUBLIC_API.md))
+
+### Changed
+
+- Integrations hub: pick-your-path table, PyPI doc links, REVIEW vs BLOCK section
+- `unplug-audit --probes` skips FP/encoding batteries when ML is inactive (boundary probes still run); clearer CLI hints
+- `unplug.example.toml`: ML settings commented by default (regex-only copy-paste safe)
+- PyPI `Documentation` URL points to Getting Started; `scan_context_file` tuple examples fixed in READMEs
+- `unplug-scan-action` default version pin bumped to `>=0.5.0,<0.6`
+- `CONTRIBUTING.md`: full framework extras table
+
+## [0.5.0] — 2026-06-27
+
+### Added
+
+- Integration adapters for seven more agent frameworks: **OpenAI Agents SDK** (`unplug.integrations.openai_agents`, native input/output guardrails), **LangChain** (`unplug.integrations.langchain`, LCEL Runnable guards + a tool-gating callback handler), **Google ADK** (`unplug.integrations.google_adk`, `before_model` / `before_tool` callbacks), **smolagents** (`unplug.integrations.smolagents`, task gate + `final_answer_checks` + tool guard), **DSPy** (`unplug.integrations.dspy`, `unplug_guard_module` wrapping + `dspy_guard_tool` for ReAct), **Strands Agents** (`unplug.integrations.strands`, a `HookProvider` that cancels destructive tool calls), and **Letta** (`unplug.integrations.letta`, client-boundary message/response guards)
+- Per-framework optional extras `unplug-ai[openai-agents]`, `[langchain]`, `[google-adk]`, `[smolagents]`, `[dspy]`, `[strands]`, `[letta]`, all folded into the `integrations` meta-extra
+- Three more framework adapters: **Griptape** (`unplug.integrations.griptape`, `on_before_run` / `on_after_run` task hooks + tool gate), **AG2** (`unplug.integrations.ag2`, `ConversableAgent` message hooks + `ag2_guard_tool`, distinct from the Microsoft `autogen` extra), and **Atomic Agents** (`unplug.integrations.atomic_agents`, Pydantic IO-schema input/output guards)
+- Optional extras `unplug-ai[griptape]`, `[ag2]`, `[atomic-agents]` (the last gated to Python ≥3.12, which the library requires), folded into the `integrations` meta-extra
+- Per-framework guides under `integrations/` and runnable demos under `examples/` for each new adapter
+- Expanded the agent security matrix from 40 to **72 angles** (ten new framework bindings), plus live tests and dedicated `Integrations (live)` CI legs for each new extra
 
 ## [0.4.1] — 2026-06-25
 

CONTRIBUTING.md

@@ -14,7 +14,7 @@ uv sync --all-extras --dev # everything, including optional extras
 uv sync --dev
 ```
 
-3. Optional extras map to scanner features — install only what you touch:
+3. Optional extras map to scanner features and integrations — install only what you touch:
 
 | Extra | Enables |
 |-------|---------|
@@ -24,6 +24,28 @@ uv sync --dev
 | `litellm` | LLM judge for borderline cases |
 | `haystack` | Haystack RAG integration |
 | `scrape` | Firecrawl content provider |
+| `langgraph` | LangGraph node hooks |
+| `langchain` | LangChain Runnable + callback hooks |
+| `openai-agents` | OpenAI Agents SDK guardrails |
+| `google-adk` | Google ADK before-model / before-tool callbacks |
+| `smolagents` | smolagents task + final-answer checks |
+| `crewai` | CrewAI task/output guards |
+| `autogen` | Microsoft AutoGen AgentChat hooks |
+| `ag2` | AG2 (community AutoGen fork) hooks |
+| `agno` | Agno pre/post run hooks |
+| `dspy` | DSPy module guards |
+| `strands` | Strands Agents hook provider |
+| `letta` | Letta message guards |
+| `griptape` | Griptape before/after run hooks |
+| `atomic-agents` | Atomic Agents schema guards (Python ≥3.12) |
+| `llama-index` | LlamaIndex node postprocessor |
+| `pydantic-ai` | Pydantic AI validators |
+| `semantic-kernel` | Semantic Kernel filters |
+| `mcp` | MCP client-side tooling tests |
+| `integrations` | **Meta-extra:** all framework extras above |
+| `all` | ML + presidio + yara + scrape + haystack + litellm |
+
+Integration guides: [`sdk/integrations/README.md`](sdk/integrations/README.md). New contributor docs: [`sdk/docs/GETTING_STARTED.md`](sdk/docs/GETTING_STARTED.md), [`sdk/docs/AGENT_ACTIONS.md`](sdk/docs/AGENT_ACTIONS.md).
 
 4. Verify your environment: `make check` (lint + format + tests).
 
@@ -52,6 +74,7 @@ GitHub Actions runs on every PR to `dev` ([`.github/workflows/ci.yml`](.github/w
 2. **Tests** — full pytest suite (`pytest -q`)
 3. **Exfil demo gate** — `test_exfil_demo_integration.py` + `sdk/examples/agent_exfil_demo.py`
 4. **Security regression** — explicit subset (adversarial, encodings, secrets, agent hardening, etc.)
+5. **Coverage** — SDK coverage report with an 80% minimum gate (`make test-cov`)
 
 ## Local checks (SDK)
 
@@ -65,6 +88,9 @@ make check
 # Exact CI parity before PR (includes exfil demo + security subset)
 make check-ci
 
+# Coverage report and 80% minimum gate
+make test-cov
+
 # Auto-fix formatting and safe lint fixes
 make fix
 

README.md

@@ -83,6 +83,8 @@ On the neuralchemy prompt-injection set, regex-only detection reaches **F1 0.56
 
 See [sdk/README.md](sdk/README.md) for config (`unplug.toml`), `unplug-audit`, and dev gates (`make check`, `make check-ci`).
 
+**New to Unplug?** [`sdk/docs/GETTING_STARTED.md`](sdk/docs/GETTING_STARTED.md) · **Agent hosts:** [`sdk/docs/AGENT_ACTIONS.md`](sdk/docs/AGENT_ACTIONS.md)
+
 ## Development
 
 ```bash

sdk/Makefile

@@ -56,7 +56,7 @@ test:
 	uv run pytest -v
 
 test-cov:
-	uv run pytest -q -m "not requires_docker and not slow" --cov=unplug --cov-report=xml:coverage.xml --cov-report=term --cov-fail-under=75 --junitxml=pytest.xml
+	uv run pytest -q -m "not requires_docker and not slow" --cov=unplug --cov-report=xml:coverage.xml --cov-report=term --cov-fail-under=80 --junitxml=pytest.xml
 
 test-security:
 	uv run pytest tests/security tests/unit/core/agent/test_agent_hardening.py -v

sdk/README.md

@@ -108,10 +108,22 @@ Wire Unplug into any agent that fetches external content or calls tools:
 5. **Scan agent output.** `guard.scan_output(text)`. Set `strip_on_output = true` to remove boundary markers from redacted output.
 6. **New trusted turn.** `guard.reset_session_taint()` clears taint and degradation.
 
-Context files (AGENTS.md and similar): `guard.scan_context_file(text, filename="AGENTS.md")` before loading into the system prompt.
+Context files (AGENTS.md and similar) — returns ``(text_for_prompt, scan_result)``; use the
+placeholder text when blocked, never the raw file:
+
+```python
+text_for_prompt, result = guard.scan_context_file(raw, filename="AGENTS.md")
+if not result.safe:
+ system_prompt = text_for_prompt # blocked placeholder, not raw content
+```
+
+See [`docs/AGENT_ACTIONS.md`](docs/AGENT_ACTIONS.md) for **REVIEW** vs **BLOCK** handling
+and human approval via ``ApprovalProvider``.
 
 Full walkthrough: [`examples/agent_exfil_demo.py`](examples/agent_exfil_demo.py) shows a hidden webpage injection leading to a tainted session, an exfil tool call held for review, and a destructive call blocked — see [`agent_exfil_demo.txt`](examples/agent_exfil_demo.txt) for sample output.
 
+New here? Start with [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) (5-minute path).
+
 ## Long documents and streams
 
 Documents past 8K chars are scanned with sliding windows (2048 chars, 256 overlap) so the full text is covered, not just head and tail. Configure under `[catalog.tiers.tiny.config]` or `unplug.toml`.
@@ -189,9 +201,10 @@ All published model metrics come from a frozen golden-eval harness on held-out d
 Verify your wiring anytime:
 
 ```bash
-unplug-audit # wiring + ML status
-unplug-audit --probes # FP + encoding + boundary batteries
+unplug-audit # wiring + ML status (regex-only OK)
+unplug-audit --probes # boundary probes always; FP/encoding need ML (see below)
 unplug-audit --require-ml # fail if checkpoint / config / ML not active
+unplug-audit --probes --require-ml # full probe batteries (FP + encoding + boundary)
 unplug-scan-pr --base-ref main # scan changed agent/MCP files in a PR (CI)
 ```
 
@@ -230,6 +243,8 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for layering and optional extra
 ## Examples
 
 - [`examples/quickstart.py`](examples/quickstart.py): minimal local Guard scan
+- [`examples/public_api_surface_demo.py`](examples/public_api_surface_demo.py): stable
+ `unplug.api.*` imports for server/MCP-style dependents
 - [`examples/server_client.py`](examples/server_client.py): HTTP client against a running sidecar
 - [`examples/agent_exfil_demo.py`](examples/agent_exfil_demo.py): hidden injection, tainted session, blocked exfil tool call
 - [`examples/langgraph_hooks_demo.py`](examples/langgraph_hooks_demo.py) and [`examples/agno_hooks_demo.py`](examples/agno_hooks_demo.py): framework hooks
@@ -240,6 +255,9 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for layering and optional extra
 
 | Doc | Covers |
 |-----|--------|
+| [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) | 5-minute install → scan (beginners) |
+| [`docs/AGENT_ACTIONS.md`](docs/AGENT_ACTIONS.md) | ALLOW / REVIEW / BLOCK + ApprovalProvider |
+| [`docs/PUBLIC_API.md`](docs/PUBLIC_API.md) | Stable `unplug.api.*` imports for server/MCP dependents |
 | [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Hosted vs embedded vs sidecar architecture |
 | [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) | Regex vs regex + ML eval results (neuralchemy, microsoft) |
 | [`docs/ML_INTEGRATION.md`](docs/ML_INTEGRATION.md) | Checkpoint layout, thresholds, long-text and streaming config |
@@ -258,6 +276,7 @@ cd sdk && uv sync --all-extras --dev
 make fix # auto-fix lint + format
 make check # lint + format check + full pytest
 make check-ci # CI parity: check + exfil demo + security regression
+make test-cov # coverage report + 80% minimum gate
 make test-security
 make audit # unplug-audit wiring
 make audit-ml # unplug-audit --require-ml

sdk/demo/requirements.txt

@@ -1,8 +1,8 @@
-gradio>=5.0
+gradio>=6.19.0
 --extra-index-url https://download.pytorch.org/whl/cpu
 torch>=2.0
-transformers>=4.44,<4.45
+transformers>=4.44,<5.13
 huggingface_hub>=0.23
 sentencepiece>=0.2
 numpy>=1.26
-unplug-ai==0.2.3
+unplug-ai==0.4.1