humanbound-firewall 0.2.0__py3-none-any.whl

humanbound_firewall/__init__.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2024-2026 Humanbound
+"""humanbound-firewall: Multi-tier firewall for AI agents.
+
+Tier 0:   Input sanitization
+Tier 1:   Basic attack detection (pre-trained, single-turn)
+Tier 2:   Agent-specific classification (trained, multi-turn, 3+ turns)
+Tier 3:   LLM-as-a-judge (handles uncertain cases)
+
+Designed for low cold-import cost: importing this module loads only stdlib and
+pydantic-adjacent dependencies. Heavy components (Firewall, HBFW, LLM clients)
+are loaded lazily on first attribute access.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+__version__ = "0.2.0"
+
+from .models import VERDICT_MAP, AgentConfig, Category, EvalResult, Turn, Verdict
+
+_LAZY_ATTRS = {
+    "Firewall": ".firewall",
+    "AttackDetector": ".firewall",
+    "AttackDetectorEnsemble": ".firewall",
+    "Provider": ".llm",
+    "ProviderIntegration": ".llm",
+    "ProviderName": ".llm",
+    "get_llm_pinger": ".llm",
+    "get_llm_streamer": ".llm",
+    "HBFW": ".hbfw",
+    "load_model_class": ".hbfw",
+    "save_hbfw": ".hbfw",
+    "load_hbfw": ".hbfw",
+}
+
+
+def __getattr__(name: str):
+    """Lazy attribute loader (PEP 562).
+
+    Defers importing heavy submodules until first attribute access so that
+    bare `import humanbound_firewall` stays fast (< 200 ms target).
+    """
+    if name in _LAZY_ATTRS:
+        import importlib
+
+        module = importlib.import_module(_LAZY_ATTRS[name], __name__)
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_ATTRS))
+
+
+if TYPE_CHECKING:
+    # Make the lazy names visible to static type checkers and IDEs.
+    from .firewall import AttackDetector, AttackDetectorEnsemble, Firewall
+    from .hbfw import HBFW, load_hbfw, load_model_class, save_hbfw
+    from .llm import (
+        Provider,
+        ProviderIntegration,
+        ProviderName,
+        get_llm_pinger,
+        get_llm_streamer,
+    )
+
+
+__all__ = [
+    "Firewall",
+    "AttackDetector",
+    "AttackDetectorEnsemble",
+    "EvalResult",
+    "AgentConfig",
+    "Verdict",
+    "Category",
+    "Turn",
+    "VERDICT_MAP",
+    "Provider",
+    "ProviderIntegration",
+    "ProviderName",
+    "get_llm_pinger",
+    "get_llm_streamer",
+    "HBFW",
+    "load_model_class",
+    "save_hbfw",
+    "load_hbfw",
+]
+
+# Backwards-compat shim: legacy imports (`import hb_firewall`) and legacy
+# pickled `.hbfw` models that reference the `hb_firewall.*` module path
+# continue to work. Scope: 0.2.x only — will be removed in 0.3.
+sys.modules.setdefault("hb_firewall", sys.modules[__name__])

humanbound_firewall/cache.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2024-2026 Humanbound
+"""Prompt cache — avoids rebuilding the system prompt on every evaluation."""
+
+import hashlib
+
+from .judge import build_system_prompt
+from .models import AgentConfig
+
+
+class PromptCache:
+    """Caches the built system prompt to avoid recomputation.
+
+    The system prompt (agent scope + intents + few-shots) is constant across
+    evaluations. Only the user message and session context change. Caching
+    the base prompt saves ~1-2ms per call and enables provider-level caching
+    (Anthropic prompt caching, OpenAI prefix caching).
+    """
+
+    def __init__(self):
+        self._base_prompt: str | None = None
+        self._config_hash: str | None = None
+
+    def get_or_build(self, config: AgentConfig) -> str:
+        """Return cached base prompt or build and cache a new one."""
+        current_hash = self._hash_config(config)
+
+        if self._base_prompt is not None and self._config_hash == current_hash:
+            return self._base_prompt
+
+        # Build fresh prompt (without session context — that's added per-call)
+        self._base_prompt = build_system_prompt(config, session_turns=None)
+        self._config_hash = current_hash
+
+        return self._base_prompt
+
+    def invalidate(self):
+        """Force rebuild on next call."""
+        self._base_prompt = None
+        self._config_hash = None
+
+    @staticmethod
+    def _hash_config(config: AgentConfig) -> str:
+        """Hash config fields that affect the system prompt."""
+        key = (
+            f"{config.business_scope}|{config.more_info}|"
+            f"{','.join(config.permitted_intents)}|"
+            f"{','.join(config.restricted_intents)}|"
+            f"{len(config.few_shots)}"
+        )
+        return hashlib.md5(key.encode()).hexdigest()

humanbound_firewall/config.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2024-2026 Humanbound
+"""YAML configuration loader."""
+
+from pathlib import Path
+
+import yaml
+
+from .models import AgentConfig
+
+
+def load_config(path: str | Path) -> AgentConfig:
+    """Load agent configuration from a YAML file."""
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    with open(path, encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    if not isinstance(data, dict):
+        raise ValueError(f"Invalid config format in {path}")
+
+    scope = data.get("scope", {})
+    intents = data.get("intents", {})
+    settings = data.get("settings", {})
+
+    return AgentConfig(
+        name=data.get("name", ""),
+        version=str(data.get("version", "1.0")),
+        business_scope=scope.get("business", ""),
+        more_info=scope.get("more_info", ""),
+        permitted_intents=intents.get("permitted", []),
+        restricted_intents=intents.get("restricted", []),
+        timeout=settings.get("timeout", 5),
+        mode=settings.get("mode", "block"),
+        session_window=settings.get("session_window", 5),
+        tier2_min_turns=settings.get("tier2_min_turns", 3),
+        risk_tolerance=settings.get("risk_tolerance", "medium"),
+        temperature=settings.get("temperature", 0.0),
+        few_shots=data.get("few_shots", []),
+    )