humanbound-firewall 0.3.2__tar.gz → 0.3.4__tar.gz

{humanbound_firewall-0.3.2/src/humanbound_firewall.egg-info → humanbound_firewall-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: humanbound-firewall
-Version: 0.3.2
+Version: 0.3.4
 Summary: Multi-tier firewall for AI agents — blocks prompt injections, jailbreaks, and scope violations; fast local tiers screen every request, only uncertain cases reach an LLM judge
 Author-email: Humanbound <hello@humanbound.ai>
 Maintainer-email: Demetris Gerogiannis <hello@humanbound.ai>, Kostas Siabanis <hello@humanbound.ai>
@@ -34,7 +34,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: requests>=2.28
 Provides-Extra: openai
-Requires-Dist: openai>=1.0; extra == "openai"
+Requires-Dist: openai>=1.58; extra == "openai"
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.30; extra == "anthropic"
 Provides-Extra: gemini
@@ -45,7 +45,7 @@ Requires-Dist: transformers>=4.40; extra == "tier1"
 Requires-Dist: protobuf>=3.20; extra == "tier1"
 Requires-Dist: sentencepiece>=0.1; extra == "tier1"
 Provides-Extra: all
-Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: openai>=1.58; extra == "all"
 Requires-Dist: anthropic>=0.30; extra == "all"
 Requires-Dist: google-generativeai>=0.3; extra == "all"
 Requires-Dist: torch>=2.0; extra == "all"

{humanbound_firewall-0.3.2 → humanbound_firewall-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "humanbound-firewall"
-version = "0.3.2"
+version = "0.3.4"
 description = "Multi-tier firewall for AI agents — blocks prompt injections, jailbreaks, and scope violations; fast local tiers screen every request, only uncertain cases reach an LLM judge"
 readme = "README.md"
 license = "Apache-2.0"
@@ -49,7 +49,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-openai = ["openai>=1.0"]
+openai = ["openai>=1.58"]
 anthropic = ["anthropic>=0.30"]
 gemini = ["google-generativeai>=0.3"]
 tier1 = [
@@ -59,7 +59,7 @@ tier1 = [
     "sentencepiece>=0.1",
 ]
 all = [
-    "openai>=1.0",
+    "openai>=1.58",
     "anthropic>=0.30",
     "google-generativeai>=0.3",
     "torch>=2.0",

{humanbound_firewall-0.3.2 → humanbound_firewall-0.3.4}/src/humanbound_firewall/__init__.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 import sys
 from typing import TYPE_CHECKING
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 from .models import CLASSES, VERDICT_MAP, AgentConfig, Category, EvalResult, Turn, Verdict
 

{humanbound_firewall-0.3.2 → humanbound_firewall-0.3.4}/src/humanbound_firewall/firewall.py

@@ -220,9 +220,17 @@ class Firewall:
         fail: str = "open",
         on_decision=None,
         withheld_template: str | None = None,
+        on_refusal: str = "block",
     ):
         """Deployment choices (classes, mode, fail, on_decision, withheld_template) are the
-        Guard's; `mode` defaults to the policy file's settings.mode. See guard.Guard."""
+        Guard's; `mode` defaults to the policy file's settings.mode. See guard.Guard.
+
+        `on_refusal` is what a Tier 3 judge that refuses to evaluate the payload means (Claude's
+        `refusal` stop, an Azure OpenAI content filter): "block" (the default: the provider's
+        safety layer judged the text harmful) or "review" (uncertain, decided by `fail`)."""
+        if on_refusal not in ("block", "review"):
+            raise ValueError(f"Unknown on_refusal '{on_refusal}'. Expected 'block' or 'review'.")
+        self._on_refusal = on_refusal
         self._config = config
         self._streamer = streamer
         self._ensemble = ensemble
@@ -253,6 +261,7 @@ class Firewall:
         fail: str = "open",
         on_decision=None,
         withheld_template: str | None = None,
+        on_refusal: str = "block",
     ) -> "Firewall":
         """Create a Firewall from configuration.
 
@@ -271,6 +280,8 @@ class Firewall:
             on_decision: Observe-only callback fired with every Decision.
             withheld_template: Text replacing a withheld payload; may use {category},
                 {explanation}, {cls}, {boundary}.
+            on_refusal: block | review — what a judge that refuses to evaluate the payload
+                means (a provider safety refusal or content filter).
         """
         config = load_config(config_path)
 
@@ -321,6 +332,7 @@ class Firewall:
             fail=fail,
             on_decision=on_decision,
             withheld_template=withheld_template,
+            on_refusal=on_refusal,
         )
 
     def evaluate(
@@ -746,7 +758,7 @@ class Firewall:
         from .firewall_judge import stream_and_extract_verdict
 
         return stream_and_extract_verdict(
-            self._streamer, system_prompt, user_prompt, timeout, session_id
+            self._streamer, system_prompt, user_prompt, timeout, session_id, self._on_refusal
         )
 
     def reload_config(self, config_path: str | Path):

humanbound_firewall-0.3.4/src/humanbound_firewall/firewall_judge.py

@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2024-2026 Humanbound
+"""Streaming LLM judge — the verdict is the letter the reply starts with.
+
+The judge answers `<letter> <explanation>`. The letter is read off the start of the reply and only
+counts as a standalone word: the first word is read to its boundary before it is trusted, so "C"
+followed by "ertainly" is not a restriction verdict, and a letter inside the payload's own text
+(a judge captured into echoing it) never becomes one. A reply that opens with anything else — a
+preamble, a continuation of the payload — is a protocol violation: the judge is asked once more,
+tersely, and if the retry does not start with a letter either the result is "no verdict", which a
+fail-closed deployment withholds. The first reply is dropped as soon as it is known to hold no
+verdict, so the retry starts at once; the retry alone is read to its end.
+
+A judge whose provider refuses to evaluate the payload — Claude stopping with `refusal`, an Azure
+OpenAI content filter, an OpenAI `refusal` — gives no letter either, but that is not doubt: the
+provider's own safety layer judged the text harmful. The firewall's job is to stop exactly such
+text, so by default a refusal is a block (`on_refusal="block"`). A deployment that would rather
+treat it as an uncertain verdict, decided by its fail mode, sets `on_refusal="review"`.
+"""
+
+import threading
+
+from .firewall import _extract_token
+from .models import VERDICT_MAP, Category, EvalResult, Verdict
+
+_WRAPPERS = " \t\r\n*#`\"'_>-"
+_RETRY_SUFFIX = "\n\nReply with the verdict letter only (P, A, B, C or D), then the explanation."
+ON_REFUSAL = ("block", "review")
+# What a provider's content filter says when it rejects the request itself (Azure OpenAI's
+# prompt filter, OpenAI's moderation), as opposed to any other error.
+_FILTER_MARKERS = ("content_filter", "content management policy", "content_policy_violation")
+
+
+def _read_verdict(head: str, ended: bool = False):
+    """Read the verdict off the start of the reply.
+
+    Returns (letter, remainder) once the reply is known to start with a standalone verdict
+    letter, (None, None) while more text is needed to know, and (None, "") once it is clear
+    the reply does not start with one.
+    """
+    i = 0
+    while i < len(head) and head[i] in _WRAPPERS:
+        i += 1
+    if i >= len(head):
+        return (None, "") if ended else (None, None)  # only wrappers so far
+    first = head[i]
+    if not first.isalpha() or first.upper() not in VERDICT_MAP:
+        return None, ""  # the reply starts with something else
+    if i + 1 >= len(head):
+        # The word is not finished: wait for its boundary (a one-letter reply resolves at the end).
+        return (first.upper(), "") if ended else (None, None)
+    if head[i + 1].isalpha():
+        return None, ""  # the letter is the start of a word
+    rest = head[i + 1 :].lstrip(_WRAPPERS.replace("-", "").replace(">", ""))
+    return first.upper(), rest
+
+
+def _refusal(chunk) -> str | None:
+    """The reason, when a streamed chunk says the provider refused to answer; else None.
+
+    Anthropic ends a refused message with `stop_reason: "refusal"` (and a `stop_details` category);
+    OpenAI and Azure OpenAI send a `refusal` text or finish with `content_filter`. Only real strings
+    count, so a chunk without these fields is never mistaken for a refusal.
+    """
+    if getattr(chunk, "type", None) == "message_delta":
+        delta = getattr(chunk, "delta", None)
+        if getattr(delta, "stop_reason", None) == "refusal":
+            details = getattr(delta, "stop_details", None) or getattr(chunk, "stop_details", None)
+            category = getattr(details, "category", None)
+            return (
+                f"provider refusal: {category}" if isinstance(category, str) else "provider refusal"
+            )
+        return None
+    choices = getattr(chunk, "choices", None)
+    if isinstance(choices, (list, tuple)) and choices:
+        choice = choices[0]
+        refusal = getattr(getattr(choice, "delta", None), "refusal", None)
+        if isinstance(refusal, str) and refusal.strip():
+            return f"provider refusal: {refusal.strip()[:120]}"
+        if getattr(choice, "finish_reason", None) == "content_filter":
+            return "provider content filter"
+    return None
+
+
+def _filtered(error: BaseException) -> str | None:
+    """The reason, when an error is the provider's content filter rejecting the request; else None."""
+    code = getattr(error, "code", None)
+    text = str(error)
+    if code == "content_filter" or any(marker in text for marker in _FILTER_MARKERS):
+        return "provider content filter"
+    return None
+
+
+def stream_and_extract_verdict(
+    streamer,
+    system_prompt: str,
+    user_prompt: str,
+    timeout: int,
+    session_id: str,
+    on_refusal: str = "block",
+) -> EvalResult:
+    """Stream the judge's reply; return as soon as the verdict letter is known."""
+    if on_refusal not in ON_REFUSAL:
+        raise ValueError(f"Unknown on_refusal '{on_refusal}'. Expected one of {ON_REFUSAL}.")
+    result_holder: list[EvalResult | None] = [None]
+    decision_event = threading.Event()
+    explanation_ready = threading.Event()
+
+    def stream_once(user_p: str, read_to_end: bool = False):
+        """One judge call. Returns (letter, explanation_parts, head, refusal): letter None = no
+        verdict; refusal names why the provider refused, when it did. A first reply that holds
+        no verdict is dropped where that is known, so the retry is not made to wait out a
+        preamble; only the retry is read to its end (`read_to_end`), to catch a late refusal."""
+        head, parts, letter, no_verdict = "", [], None, False
+        stream = streamer.ping(
+            system_p=system_prompt, user_p=user_p, max_tokens=1024, temperature=0.0
+        )
+        for chunk in stream:
+            if letter is None and (no_verdict or not head.strip()):
+                # A refusal counts while the reply holds no verdict: before the judge has said
+                # anything, and after what it has said is known not to be a verdict letter — a
+                # preamble answers nothing, so the refusal is the only signal there is. It does
+                # not count while a letter is still resolving ("P" before its boundary) or once
+                # one has been read: a filter that cuts an explanation short leaves the verdict.
+                refused = _refusal(chunk)
+                if refused:
+                    return None, [], head, refused
+            try:
+                token = _extract_token(chunk)
+            except Exception as e:
+                # A chunk that cannot be read is not an answer. Gemini raises here when its
+                # safety filter blocked the reply, so the refusal is the chunk itself.
+                if letter is not None:
+                    break  # the verdict is already in; stop reading the explanation
+                return None, [], head, f"provider refusal: unreadable chunk ({type(e).__name__})"
+            if no_verdict or token is None:
+                # The reply does not start with a letter. Nothing more is read from it, but the
+                # stream is followed to its end: a refusal still decides, and arrives last.
+                continue
+            if letter is not None:
+                parts.append(token)
+                continue
+            head += token
+            found, remainder = _read_verdict(head)
+            if found is None:
+                if remainder is not None:
+                    no_verdict = True  # decided: no verdict, but a refusal may still follow
+                    if not read_to_end:
+                        # Leave at once: the retry must not wait out a long preamble, or a
+                        # judge that only thinks out loud costs the caller its whole timeout.
+                        return None, [], head, None
+                continue
+            letter = found
+            _decide(letter)
+            if remainder.strip():
+                parts.append(remainder)
+        if letter is None and not no_verdict:
+            found, remainder = _read_verdict(head, ended=True)
+            if found is not None:
+                letter = found
+                _decide(letter)
+        return letter, parts, head, None
+
+    def _decide(letter):
+        verdict, category = VERDICT_MAP[letter]
+        result_holder[0] = EvalResult(
+            verdict=verdict,
+            category=category,
+            raw_letter=letter,
+            session_id=session_id,
+            _explanation_ready=explanation_ready,
+        )
+        decision_event.set()
+
+    def _refused(reason: str):
+        """The provider refused to evaluate the payload: a block by default."""
+        if on_refusal == "block":
+            result_holder[0] = EvalResult(
+                verdict=Verdict.BLOCK,
+                category=Category.VIOLATION,
+                explanation=f"Judge refused to evaluate the payload ({reason}); treated as an attack.",
+                session_id=session_id,
+            )
+        else:
+            result_holder[0] = EvalResult(
+                verdict=Verdict.REVIEW,
+                category=Category.UNCERTAIN,
+                explanation=f"Judge refused to evaluate the payload ({reason}).",
+                session_id=session_id,
+            )
+        decision_event.set()
+
+    def _run():
+        try:
+            letter, parts, head, refused = stream_once(user_prompt)
+            if letter is None and not refused and head.strip():
+                # A protocol violation: ask once more, tersely.
+                letter, parts, head2, refused = stream_once(
+                    user_prompt + _RETRY_SUFFIX, read_to_end=True
+                )
+                head = head2 if letter is None else head
+        except Exception as e:
+            if result_holder[0] is None:
+                filtered = _filtered(e)
+                if filtered:
+                    _refused(filtered)
+                else:
+                    result_holder[0] = EvalResult(
+                        verdict=Verdict.REVIEW,
+                        category=Category.UNCERTAIN,
+                        explanation=f"Stream error: {str(e)[:200]}",
+                        session_id=session_id,
+                    )
+                    decision_event.set()
+            explanation_ready.set()
+            return
+
+        if result_holder[0] is not None:
+            explanation = "".join(parts).strip()
+            result_holder[0].explanation = explanation.lstrip(" \t\r\n*#`\"'_").strip()
+        elif refused:
+            _refused(refused)
+        else:
+            said = head.strip().replace("\n", " ")[:120]
+            explanation = (
+                f"Judge did not start with a verdict: '{said}'"
+                if said
+                else "Judge returned no verdict."
+            )
+            result_holder[0] = EvalResult(
+                verdict=Verdict.REVIEW,
+                category=Category.UNCERTAIN,
+                explanation=explanation,
+                session_id=session_id,
+            )
+            decision_event.set()
+        explanation_ready.set()
+
+    thread = threading.Thread(target=_run, daemon=True)
+    thread.start()
+
+    if not decision_event.wait(timeout=timeout):
+        raise TimeoutError("Evaluation timed out waiting for verdict.")
+
+    return result_holder[0]

{humanbound_firewall-0.3.2 → humanbound_firewall-0.3.4}/src/humanbound_firewall/integrations/langchain.py

@@ -34,6 +34,7 @@ Usage:
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 import threading
 from collections import deque
@@ -215,8 +216,8 @@ class HumanboundFirewallMiddleware(AgentMiddleware):
             return written  # a later model call in the same run: the turn was judged already
         if self.firewall.guard.mode_for("request") == "off":
             return written
-        text = messages[-1].content
-        if not isinstance(text, str):
+        text = _text(messages[-1].content)
+        if text is None:  # no text to judge (an image alone)
             return written
         window = self._window(messages[:-1])
         if self._background("request"):  # log mode: a request is never rejected, so do not wait
@@ -277,13 +278,15 @@ class HumanboundFirewallMiddleware(AgentMiddleware):
         return not self._log_blocking and self.firewall.guard.mode_for(cls) == "log"
 
     def _screen(self, request, result):
-        if not isinstance(result, ToolMessage) or not isinstance(result.content, str):
+        if not isinstance(result, ToolMessage):
+            return result
+        payload = _text(result.content)
+        if payload is None:  # no text to judge (an image or file alone)
             return result
         name = request.tool_call.get("name", "")
         cls = self.firewall.config.class_of(name)
         description = str(getattr(getattr(request, "tool", None), "description", "") or "")
         # Everything the judge sees is fixed here, when the tool returned.
-        payload = result.content
         window = self._window(request.state.get("messages", []))
         boundary = {
             **self._tool_boundary(name, description),
@@ -411,11 +414,10 @@ class HumanboundFirewallMiddleware(AgentMiddleware):
         window = []
         for message in messages:
             for kind, role in _ROLES:
-                if isinstance(message, kind) and isinstance(message.content, str):
-                    if message.content:
-                        window.append(
-                            {"role": role, "content": message.content[: self._history_chars]}
-                        )
+                if isinstance(message, kind):
+                    text = _text(message.content)
+                    if text:
+                        window.append({"role": role, "content": text[: self._history_chars]})
         return window[-self._history_messages :]
 
 
@@ -425,6 +427,63 @@ def _tool_name(tool) -> str:
 
 def _last_human(messages) -> str:
     for message in reversed(list(messages)):
-        if isinstance(message, HumanMessage) and isinstance(message.content, str):
-            return message.content
+        if isinstance(message, HumanMessage):
+            text = _text(message.content)
+            if text is not None:
+                return text
     return ""
+
+
+# The block types that carry no text to judge: the model reads them as media, and their payload
+# is bytes or a URL. Everything else is screened, whatever its type — LangChain keeps document,
+# search_result, json, custom_tool_call_output and file blocks as tool content, a human turn can
+# carry text-plain, and each one reaches the model as text. Listing what to skip rather than what
+# to read means a block type added later is screened by default: over-screening is the safe
+# failure, a block that slips past is not.
+_MEDIA_BLOCKS = frozenset({"image", "image_url", "audio", "video"})
+# Dropped from a block's JSON form: raw media bytes, which carry no text and would swamp the judge.
+_BINARY_FIELDS = frozenset({"base64", "data_base64", "bytes"})
+
+
+def _text(content) -> str | None:
+    """The text a message carries, whether its content is a string or a list of content blocks.
+
+    LangChain allows both (`str | list[str | dict]`): multimodal messages and MCP tool results with
+    several parts or an image arrive as a list. Plain strings and `{"type": "text"}` blocks are
+    joined with newlines, so text split across blocks is judged as one payload. Any other block —
+    a document, a search result, JSON, a custom tool's output — is judged as its JSON form, since
+    the model reads the text inside it. Pure media blocks are skipped. None when nothing is left.
+    """
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return None
+    parts = []
+    for block in content:
+        if isinstance(block, str):
+            parts.append(block)
+        elif isinstance(block, dict):
+            if block.get("type") in _MEDIA_BLOCKS:
+                continue
+            if block.get("type") == "text" and isinstance(block.get("text"), str):
+                parts.append(block["text"])
+            else:
+                parts.append(_block_json(block))
+    parts = [p for p in parts if p]
+    return "\n".join(parts) if parts else None
+
+
+def _block_json(block: dict) -> str:
+    """A non-text block as JSON for the judge, with raw media bytes dropped at any depth."""
+
+    def strip(value):
+        if isinstance(value, dict):
+            return {k: strip(v) for k, v in value.items() if k not in _BINARY_FIELDS}
+        if isinstance(value, list):
+            return [strip(v) for v in value]
+        return value
+
+    try:
+        return json.dumps(strip(block), ensure_ascii=False, default=str)
+    except (TypeError, ValueError):
+        return str(block)

{humanbound_firewall-0.3.2 → humanbound_firewall-0.3.4}/src/humanbound_firewall/llm/azureopenai.py

@@ -8,9 +8,10 @@ from os import getenv
 import requests
 
 # Same parameter handling as the OpenAI provider (see there for the reasoning): the modern
-# `max_completion_tokens` for every deployment, and `temperature` retried away once on the 400
-# that names it. Azure deployment names are arbitrary, so a model-name list could never work here.
-from .openai import _models_without_temperature, _rejects_temperature, _sampling_params
+# `max_completion_tokens` for every deployment, and `temperature` / `reasoning_effort` dropped on
+# the 400 that names them. Azure deployment names are arbitrary, so a model-name list could never
+# work here — the drop-and-remember is keyed on the deployment name just the same.
+from .openai import _note_rejected, _sampling_params
 
 ALLOWED_MAX_OUT_TOKENS = 4096
 DEFAULT_MAX_OUT_TOKENS = 2048
@@ -37,6 +38,7 @@ class LLMStreamer:
             azure_endpoint=integ.get("endpoint", ""),
         )
         self.model = integ["model"]
+        self.reasoning_effort = integ.get("reasoning_effort")
 
     def ping(
         self, system_p, user_p, max_tokens=DEFAULT_MAX_OUT_TOKENS, temperature=DEFAULT_TEMPERATURE
@@ -46,21 +48,26 @@ class LLMStreamer:
             {"role": "system", "content": system_p},
             {"role": "user", "content": user_p},
         ]
-        params = _sampling_params(self.model, max_tokens, temperature)
-        try:
-            return self.__client.chat.completions.create(
-                model=self.model, messages=messages, timeout=LLM_PING_TIMEOUT, stream=True, **params
-            )
-        except Exception as e:
-            if "temperature" not in params or not (
-                getattr(e, "status_code", None) == 400 and _rejects_temperature(str(e))
-            ):
-                raise
-            _models_without_temperature.add(self.model)
-            params.pop("temperature")
-            return self.__client.chat.completions.create(
-                model=self.model, messages=messages, timeout=LLM_PING_TIMEOUT, stream=True, **params
-            )
+        params = _sampling_params(self.model, max_tokens, temperature, self.reasoning_effort)
+        while True:
+            try:
+                return self.__client.chat.completions.create(
+                    model=self.model,
+                    messages=messages,
+                    timeout=LLM_PING_TIMEOUT,
+                    stream=True,
+                    **params,
+                )
+            except Exception as e:
+                drop = (
+                    _note_rejected(self.model, str(e), getattr(e, "param", None)) & params.keys()
+                    if getattr(e, "status_code", None) == 400
+                    else set()
+                )
+                if not drop:
+                    raise
+                for name in drop:
+                    params.pop(name)
 
 
 class LLMPinger:
@@ -81,7 +88,9 @@ class LLMPinger:
                     {"role": "system", "content": system_p},
                     {"role": "user", "content": user_p},
                 ],
-                **_sampling_params(integ["model"], max_tokens, temperature),
+                **_sampling_params(
+                    integ["model"], max_tokens, temperature, integ.get("reasoning_effort")
+                ),
             },
             timeout=LLM_PING_TIMEOUT,
         )
@@ -109,10 +118,8 @@ class LLMPinger:
                     continue
                 raise Exception("502/Rate limit error.")
             elif resp.status_code == 400:
-                model = self._provider["integration"]["model"]
-                if model not in _models_without_temperature and _rejects_temperature(resp.text):
-                    _models_without_temperature.add(model)
-                    continue  # retry once, now without temperature
+                if _note_rejected(self._provider["integration"]["model"], resp.text):
+                    continue  # retry; the next request omits the param(s) the deployment rejected
                 raise Exception(f"502/Inappropriate content ({resp.text}).")
             else:
                 raise Exception(f"502/Error pinging LLM - {resp.status_code}/{resp.text}")

{humanbound_firewall-0.3.2 → humanbound_firewall-0.3.4}/src/humanbound_firewall/llm/models.py

@@ -19,6 +19,11 @@ class ProviderIntegration(BaseModel):
     model: str
     endpoint: str | None = None
     api_version: str | None = None
+    # Reasoning effort for the judge, when the model is a reasoning model that accepts it
+    # (e.g. OpenAI "minimal" | "low" | "medium" | "high"). Left None, no effort is sent and
+    # the model's own default applies. A model that rejects the parameter has it dropped on
+    # the first 400 and remembered, the same way an unsupported temperature is.
+    reasoning_effort: str | None = None
 
 
 class Provider(BaseModel):