integrable-firewall 0.1.0__py3-none-any.whl

integrable_firewall/__init__.py

@@ -0,0 +1,38 @@
+"""Connect an AI agent built in code to its firewall.
+
+The firewall screens every user message, every tool call before it runs and
+every tool result before the model reads it. One adapter protects one agent::
+
+    from integrable_firewall.langchain import FirewallMiddleware
+    agent = create_agent(model, tools, middleware=[FirewallMiddleware(agent="support-widget")])
+
+Adapters: ``integrable_firewall.langchain``, ``integrable_firewall.openai_agents``,
+``integrable_firewall.adk``, ``integrable_firewall.pydantic_ai``. Each imports
+its framework only when it is imported itself.
+"""
+
+from ._client import (
+    TIMEOUT_SECONDS,
+    UNREACHABLE,
+    Firewall,
+    FirewallAgentMismatch,
+    FirewallBlocked,
+    FirewallConfigError,
+    FirewallError,
+    Verdict,
+    key_variable,
+)
+from ._version import __version__
+
+__all__ = [
+    "Firewall",
+    "Verdict",
+    "FirewallBlocked",
+    "FirewallError",
+    "FirewallConfigError",
+    "FirewallAgentMismatch",
+    "UNREACHABLE",
+    "TIMEOUT_SECONDS",
+    "key_variable",
+    "__version__",
+]

integrable_firewall/_client.py

@@ -0,0 +1,652 @@
+"""The core: settings, the three events over HTTP, the answer read, failing closed.
+
+Wire protocol: ``packages/PROTOCOL.md`` in the firewall repository. Standard
+library only (``urllib``), Python 3.9 or later. Every request runs in a thread
+of its own with a total deadline of 9.5 s, so the async entry points never
+block the event loop and a server that trickles its answer cannot hold a step
+past the deadline.
+
+The key is read from the ``key`` option or the environment, checked against
+the agent name, and sent only as the ``Authorization`` header to the
+configured URL: never logged, never put in an error message, never forwarded
+on a redirect (redirects are not followed at all).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import json
+import logging
+import math
+import os
+import re
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+from ._version import __version__
+
+__all__ = [
+    "Firewall",
+    "Verdict",
+    "FirewallBlocked",
+    "FirewallError",
+    "FirewallConfigError",
+    "FirewallAgentMismatch",
+    "UNREACHABLE",
+    "TIMEOUT_SECONDS",
+    "key_variable",
+]
+
+PACKAGE = "integrable-firewall"
+USER_AGENT = f"integrable-firewall-python/{__version__}"
+
+#: The total time one request may take; the server's own budget is 10 s.
+TIMEOUT_SECONDS = 9.5
+
+#: What the model (or the app, for a user message) reads when the firewall
+#: cannot be reached or answers with an error. Quoted from PROTOCOL.md.
+UNREACHABLE: Dict[str, str] = {
+    "UserPromptSubmit": "Firewall: the firewall could not be reached, so this message was not processed.",
+    "PreToolUse": "Firewall: the firewall could not be reached, so this step did not run.",
+    "PostToolUse": "Firewall: the firewall could not be reached, so this result was withheld.",
+}
+
+# A stop the firewall answered without a reason (the server always sends one).
+_STOPPED: Dict[str, str] = {
+    "UserPromptSubmit": "Firewall: this message was blocked.",
+    "PreToolUse": "Firewall: this step was stopped.",
+    "PostToolUse": "Firewall: this result was withheld.",
+}
+
+_EVENTS = ("UserPromptSubmit", "PreToolUse", "PostToolUse")
+_AGENT_RE = re.compile(r"^[a-z0-9._-]{1,40}$")
+_KEY_RE = re.compile(r"^fwa_[0-9a-f]{64}_(?P<agent>[a-z0-9._-]{1,40})$")  # server/agent-keys.mjs AGENT_KEY_RE
+_MAX_ANSWER_BYTES = 32 * 1024 * 1024
+
+log = logging.getLogger("integrable_firewall")
+
+
+class FirewallError(Exception):
+    """A configuration or usage error of the firewall adapter (never a decision)."""
+
+
+class FirewallConfigError(FirewallError, ValueError):
+    """The adapter's settings are wrong: the agent name, the key or the URL."""
+
+
+class FirewallAgentMismatch(FirewallError):
+    """One adapter was used for a second agent: one adapter protects one agent."""
+
+
+class FirewallBlocked(Exception):
+    """The firewall blocked the user's message, which did not reach the model.
+
+    ``reason`` is the firewall's reason ("Firewall: ..."), for the app to answer
+    its user with or to replace with its own words. ``unreachable`` is true when
+    the block is the fail-closed answer to a firewall that could not be reached.
+    """
+
+    def __init__(self, reason: str, verdict: Optional["Verdict"] = None) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.verdict = verdict
+
+    @property
+    def unreachable(self) -> bool:
+        return bool(self.verdict is not None and self.verdict.failed_closed)
+
+
+@dataclasses.dataclass(frozen=True)
+class Verdict:
+    """The firewall's answer, normalised.
+
+    ``action`` is one of:
+
+    - ``"pass"``: go on unchanged.
+    - ``"block"``: the message does not reach the model, the tool does not run,
+      or the result is withheld; the model (or the app) reads ``reason``.
+    - ``"replace"`` (tool results only): the model reads ``value`` in place of
+      the tool's result.
+
+    ``error`` is set when the verdict is the fail-closed answer to a firewall
+    that could not be reached or answered with an error; it says why (never the
+    key) and is what the adapter logs.
+    """
+
+    action: str
+    reason: Optional[str] = None
+    value: Any = None
+    context: Optional[str] = None
+    error: Optional[str] = None
+    status: Optional[int] = None
+
+    @property
+    def passed(self) -> bool:
+        return self.action == "pass"
+
+    @property
+    def blocked(self) -> bool:
+        return self.action == "block"
+
+    @property
+    def replaced(self) -> bool:
+        return self.action == "replace"
+
+    @property
+    def failed_closed(self) -> bool:
+        return self.error is not None
+
+    def model_text(self) -> str:
+        """The text the model reads in place of the tool's result."""
+        if self.action == "replace":
+            return value_text(self.value)
+        return self.reason or ""
+
+
+def key_variable(agent: str) -> str:
+    """The environment variable that holds one agent's key.
+
+    ``support-widget`` -> ``FIREWALL_KEY_SUPPORT_WIDGET``.
+    """
+    return "FIREWALL_KEY_" + re.sub(r"[^A-Z0-9]", "_", agent.upper())
+
+
+def _env(name: str) -> Optional[str]:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Never follow a redirect: the key goes to the configured URL only."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[override]
+        return None
+
+
+class _Timeout(Exception):
+    pass
+
+
+class Firewall:
+    """A client for one agent's firewall.
+
+    ``Firewall(agent="support-widget")`` reads the URL from ``FIREWALL_URL`` and
+    the key from ``FIREWALL_KEY_SUPPORT_WIDGET``, then ``FIREWALL_KEY``; the
+    ``url`` and ``key`` options come first. A key made for another agent is a
+    :class:`FirewallConfigError` here, before anything is sent. A missing URL is
+    not an error: every call fails closed and one warning names the variable.
+
+    The adapters (``integrable_firewall.langchain``, ``.openai_agents``,
+    ``.adk``, ``.pydantic_ai``) build on this class; it can also be used
+    directly for a framework without an adapter.
+    """
+
+    def __init__(
+        self,
+        agent: str,
+        *,
+        url: Optional[str] = None,
+        key: Optional[str] = None,
+        framework: Optional[str] = None,
+        timeout: float = TIMEOUT_SECONDS,
+    ) -> None:
+        if not isinstance(agent, str) or not _AGENT_RE.match(agent) or not agent.strip("."):
+            raise FirewallConfigError(
+                f"integrable_firewall: the agent name {agent!r} is not valid: use 1 to 40 lowercase "
+                "letters, digits, '.', '_' or '-', the name the firewall knows the agent by "
+                "(for example 'support-widget')."
+            )
+        self.agent = agent
+        self.framework = framework
+        try:
+            timeout = float(timeout)
+        except (TypeError, ValueError):
+            raise FirewallConfigError("integrable_firewall: timeout must be a number of seconds.") from None
+        if not timeout > 0:
+            raise FirewallConfigError("integrable_firewall: timeout must be more than 0 seconds.")
+        self._timeout = min(timeout, TIMEOUT_SECONDS)
+
+        resolved_url = url.strip() if isinstance(url, str) and url.strip() else _env("FIREWALL_URL")
+        self.url: Optional[str] = resolved_url.rstrip("/") if resolved_url else None
+        if self.url is not None:
+            parts = urllib.parse.urlsplit(self.url)
+            if parts.scheme not in ("http", "https") or not parts.hostname:
+                where = "the url option" if url else "FIREWALL_URL"
+                raise FirewallConfigError(
+                    f"integrable_firewall: {where} must be the firewall's http or https address "
+                    f"(for example https://example.cloudfront.net), not {self.url!r}."
+                )
+            if parts.query or parts.fragment:
+                raise FirewallConfigError(
+                    "integrable_firewall: the firewall's address takes no query or fragment."
+                )
+
+        variable = key_variable(agent)
+        agent_key, shared_key = _env(variable), _env("FIREWALL_KEY")
+        resolved_key: Optional[str] = None
+        source: Optional[str] = None
+        if isinstance(key, str) and key.strip():
+            resolved_key, source = key.strip(), "the key option"
+        elif agent_key is not None:
+            resolved_key, source = agent_key, variable
+        elif shared_key is not None:
+            resolved_key, source = shared_key, "FIREWALL_KEY"
+        if resolved_key is not None:
+            match = _KEY_RE.match(resolved_key)
+            if match is None:
+                raise FirewallConfigError(
+                    f"integrable_firewall: the key from {source} is not a firewall agent key "
+                    "(fwa_<64 hex>_<agent name>). Use the key the firewall made for "
+                    f"'{agent}', placed in {variable}."
+                )
+            if match.group("agent") != agent:
+                raise FirewallConfigError(
+                    f"integrable_firewall: the key from {source} is for the agent "
+                    f"'{match.group('agent')}', but this adapter protects '{agent}'. One adapter "
+                    f"protects one agent: use the key made for '{agent}', placed in {variable}."
+                )
+        self._key = resolved_key
+        self._key_source = source
+        self._key_variable = variable
+
+        self._endpoint = f"{self.url}/hook/{agent}" if self.url else None
+        self._opener = urllib.request.build_opener(_NoRedirect())
+        self._pin_lock = threading.Lock()
+        self._pinned: Optional[Tuple[Any, str]] = None
+
+        if self.url is None:
+            log.warning(
+                "integrable_firewall: FIREWALL_URL is not set, so every step of the agent '%s' "
+                "fails closed until it is.",
+                agent,
+            )
+        elif self._key is not None and urllib.parse.urlsplit(self.url).scheme == "http" and not _is_loopback(self.url):
+            log.warning(
+                "integrable_firewall: the firewall's address for '%s' is plain http, so its key "
+                "travels unencrypted; use the https address.",
+                agent,
+            )
+
+    def __repr__(self) -> str:
+        return f"Firewall(agent={self.agent!r}, url={self.url!r}, key={'set' if self._key else 'none'})"
+
+    # ------------------------------------------------------------------ pinning
+
+    def pin(self, identity: Any, label: str) -> None:
+        """Bind this adapter to the first framework agent it sees.
+
+        ``identity`` is a name (compared by value) or an object (compared by
+        identity); ``label`` says what it is, for the error. Any other agent
+        raises :class:`FirewallAgentMismatch`: one adapter protects one agent.
+        """
+        with self._pin_lock:
+            if self._pinned is None:
+                self._pinned = (identity, label)
+                return
+            pinned, pinned_label = self._pinned
+            same = pinned == identity if isinstance(pinned, str) and isinstance(identity, str) else pinned is identity
+            if same:
+                return
+        raise FirewallAgentMismatch(
+            f"integrable_firewall: one adapter protects one agent. This adapter is for "
+            f"'{self.agent}' and protects {pinned_label}, but it was just used by {label}, so the "
+            f"firewall stopped there. Give {label} an adapter of its own, with its own agent name and key."
+        )
+
+    # ------------------------------------------------------------------ events
+
+    def user_message(self, prompt: str, *, session_id: Optional[str] = None) -> Verdict:
+        """Screen a new message from the agent's user (``UserPromptSubmit``)."""
+        return self._send("UserPromptSubmit", self._payload("UserPromptSubmit", session_id, prompt=to_text(prompt)))
+
+    def before_tool(
+        self,
+        tool_name: str,
+        tool_input: Any,
+        *,
+        session_id: Optional[str] = None,
+        tool_use_id: Optional[str] = None,
+    ) -> Verdict:
+        """Screen a tool call before it runs (``PreToolUse``)."""
+        return self._send("PreToolUse", self._tool_payload("PreToolUse", session_id, tool_name, tool_input, tool_use_id))
+
+    def after_tool(
+        self,
+        tool_name: str,
+        tool_input: Any,
+        tool_response: Any,
+        *,
+        session_id: Optional[str] = None,
+        tool_use_id: Optional[str] = None,
+    ) -> Verdict:
+        """Screen a tool's result before the model reads it (``PostToolUse``)."""
+        payload = self._tool_payload("PostToolUse", session_id, tool_name, tool_input, tool_use_id)
+        payload["tool_response"] = jsonable(tool_response)
+        return self._send("PostToolUse", payload)
+
+    async def auser_message(self, prompt: str, *, session_id: Optional[str] = None) -> Verdict:
+        return await self._asend("UserPromptSubmit", self._payload("UserPromptSubmit", session_id, prompt=to_text(prompt)))
+
+    async def abefore_tool(
+        self,
+        tool_name: str,
+        tool_input: Any,
+        *,
+        session_id: Optional[str] = None,
+        tool_use_id: Optional[str] = None,
+    ) -> Verdict:
+        return await self._asend("PreToolUse", self._tool_payload("PreToolUse", session_id, tool_name, tool_input, tool_use_id))
+
+    async def aafter_tool(
+        self,
+        tool_name: str,
+        tool_input: Any,
+        tool_response: Any,
+        *,
+        session_id: Optional[str] = None,
+        tool_use_id: Optional[str] = None,
+    ) -> Verdict:
+        payload = self._tool_payload("PostToolUse", session_id, tool_name, tool_input, tool_use_id)
+        payload["tool_response"] = jsonable(tool_response)
+        return await self._asend("PostToolUse", payload)
+
+    def check_user_message(self, prompt: str, *, session_id: Optional[str] = None) -> None:
+        """Like :meth:`user_message`, raising :class:`FirewallBlocked` on a block."""
+        verdict = self.user_message(prompt, session_id=session_id)
+        if not verdict.passed:
+            raise FirewallBlocked(verdict.reason or UNREACHABLE["UserPromptSubmit"], verdict)
+
+    async def acheck_user_message(self, prompt: str, *, session_id: Optional[str] = None) -> None:
+        verdict = await self.auser_message(prompt, session_id=session_id)
+        if not verdict.passed:
+            raise FirewallBlocked(verdict.reason or UNREACHABLE["UserPromptSubmit"], verdict)
+
+    # ------------------------------------------------------------------ internals
+
+    def _payload(self, event: str, session_id: Optional[str], **fields: Any) -> Dict[str, Any]:
+        client: Dict[str, Any] = {"package": PACKAGE, "version": __version__, "language": "python"}
+        if self.framework:
+            client["framework"] = self.framework
+        payload: Dict[str, Any] = {
+            "hook_event_name": event,
+            "session_id": str(session_id) if session_id else new_session_id(),
+            "firewall_client": client,
+        }
+        payload.update(fields)
+        return payload
+
+    def _tool_payload(
+        self, event: str, session_id: Optional[str], tool_name: str, tool_input: Any, tool_use_id: Optional[str]
+    ) -> Dict[str, Any]:
+        payload = self._payload(event, session_id, tool_name=str(tool_name), tool_input=as_object(tool_input))
+        if tool_use_id:
+            payload["tool_use_id"] = str(tool_use_id)
+        return payload
+
+    def _body(self, payload: Mapping[str, Any]) -> bytes:
+        return json.dumps(payload, ensure_ascii=True, allow_nan=False, separators=(",", ":")).encode("ascii")
+
+    def _post(self, body: bytes) -> Tuple[int, bytes]:
+        assert self._endpoint is not None
+        headers = {"Content-Type": "application/json", "User-Agent": USER_AGENT}
+        if self._key:
+            headers["Authorization"] = f"Bearer {self._key}"
+        request = urllib.request.Request(self._endpoint, data=body, headers=headers, method="POST")
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                return response.status, response.read(_MAX_ANSWER_BYTES + 1)
+        except urllib.error.HTTPError as error:
+            try:
+                error.close()
+            except Exception:
+                pass
+            return error.code, b""
+
+    def _send(self, event: str, payload: Dict[str, Any]) -> Verdict:
+        if self._endpoint is None:
+            return self._fail(event, "FIREWALL_URL is not set", warn=False)
+        try:
+            body = self._body(payload)
+        except (TypeError, ValueError) as error:  # jsonable() leaves nothing unserialisable
+            return self._fail(event, f"the event could not be serialised ({type(error).__name__})")
+        try:
+            status, data = _call_with_deadline(lambda: self._post(body), self._timeout)
+        except _Timeout:
+            return self._fail(event, f"no answer within {self._timeout:g} s")
+        except Exception as error:
+            return self._fail(event, _describe(error))
+        return self._read(event, status, data)
+
+    async def _asend(self, event: str, payload: Dict[str, Any]) -> Verdict:
+        if self._endpoint is None:
+            return self._fail(event, "FIREWALL_URL is not set", warn=False)
+        try:
+            body = self._body(payload)
+        except (TypeError, ValueError) as error:
+            return self._fail(event, f"the event could not be serialised ({type(error).__name__})")
+        try:
+            status, data = await _acall_with_deadline(lambda: self._post(body), self._timeout)
+        except _Timeout:
+            return self._fail(event, f"no answer within {self._timeout:g} s")
+        except Exception as error:
+            return self._fail(event, _describe(error))
+        return self._read(event, status, data)
+
+    def _fail(self, event: str, why: str, *, status: Optional[int] = None, warn: bool = True) -> Verdict:
+        if warn:
+            log.warning("integrable_firewall: %s, so the %s of the agent '%s' failed closed.", why, _NOUN[event], self.agent)
+        return Verdict("block", reason=UNREACHABLE[event], error=why, status=status)
+
+    def _read(self, event: str, status: int, data: bytes) -> Verdict:
+        if status == 204:
+            return Verdict("pass", status=204)
+        if status in (401, 403):
+            if self._key is None:
+                hint = f"no key was found: set {self._key_variable}"
+            else:
+                hint = f"the key from {self._key_source} is wrong, replaced or not for '{self.agent}'"
+            return self._fail(event, f"the firewall refused the request (HTTP {status}): {hint}", status=status)
+        if status != 200:
+            return self._fail(event, f"the firewall answered HTTP {status}", status=status)
+        if len(data) > _MAX_ANSWER_BYTES:
+            return self._fail(event, "the firewall's answer was too large to read", status=status)
+        try:
+            body = json.loads(data.decode("utf-8"))
+        except (UnicodeDecodeError, ValueError):
+            return self._fail(event, "the firewall's answer was not JSON", status=status)
+        if not isinstance(body, dict):
+            return self._fail(event, "the firewall's answer was not a JSON object", status=status)
+        return read_answer(event, body)
+
+
+_NOUN = {"UserPromptSubmit": "user message", "PreToolUse": "tool call", "PostToolUse": "tool result"}
+
+
+def read_answer(event: str, body: Mapping[str, Any]) -> Verdict:
+    """Read a ``200`` body for one event. Anything unknown is the most restrictive outcome."""
+    if event not in _EVENTS:
+        raise ValueError(f"unknown event {event!r}")
+    hso = body.get("hookSpecificOutput")
+    hso = hso if isinstance(hso, Mapping) else {}
+    reason = _reason(body.get("reason"))
+
+    if event == "UserPromptSubmit":
+        return Verdict("block", reason=reason or _STOPPED[event], status=200)
+
+    if event == "PreToolUse":
+        # deny and ask both mean the tool does not run; anything else is read as deny.
+        return Verdict("block", reason=_reason(hso.get("permissionDecisionReason")) or reason or _STOPPED[event], status=200)
+
+    # PostToolUse
+    updated = hso.get("updatedToolOutput")
+    context = _reason(hso.get("additionalContext"))
+    if body.get("decision") == "block":
+        if updated is not None:
+            return Verdict("replace", reason=reason, value=updated, context=context, status=200)
+        return Verdict("block", reason=reason or _STOPPED[event], status=200)
+    if updated is not None:
+        return Verdict("replace", reason=reason, value=updated, context=context, status=200)
+    return Verdict("block", reason=reason or _STOPPED[event], status=200)
+
+
+def _reason(value: Any) -> Optional[str]:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _describe(error: BaseException) -> str:
+    if isinstance(error, urllib.error.URLError):
+        inner = error.reason
+        if isinstance(inner, BaseException):
+            return f"the firewall could not be reached ({type(inner).__name__}: {inner})"
+        return f"the firewall could not be reached ({inner})"
+    if isinstance(error, TimeoutError) or type(error).__name__ == "timeout":
+        return "the firewall did not answer in time"
+    return f"the firewall could not be reached ({type(error).__name__}: {error})"
+
+
+def _is_loopback(url: str) -> bool:
+    host = (urllib.parse.urlsplit(url).hostname or "").lower()
+    return host in ("localhost", "::1") or host.startswith("127.") or host.endswith(".localhost")
+
+
+def _call_with_deadline(fn: Any, timeout: float) -> Any:
+    """Run ``fn`` in a daemon thread; give up after ``timeout`` seconds in all."""
+    outcome: Dict[str, Any] = {}
+    done = threading.Event()
+
+    def run() -> None:
+        try:
+            outcome["value"] = fn()
+        except BaseException as error:  # handed to the caller
+            outcome["error"] = error
+        finally:
+            done.set()
+
+    threading.Thread(target=run, name="integrable-firewall-request", daemon=True).start()
+    if not done.wait(timeout):
+        raise _Timeout()
+    if "error" in outcome:
+        raise outcome["error"]
+    return outcome["value"]
+
+
+async def _acall_with_deadline(fn: Any, timeout: float) -> Any:
+    """The same, awaited: the event loop keeps running while the request does."""
+    loop = asyncio.get_running_loop()
+    future: "asyncio.Future[Any]" = loop.create_future()
+
+    def settle(value: Any, error: Optional[BaseException]) -> None:
+        if future.done():
+            return
+        if error is not None:
+            future.set_exception(error)
+        else:
+            future.set_result(value)
+
+    def run() -> None:
+        try:
+            value, error = fn(), None
+        except BaseException as caught:
+            value, error = None, caught
+        try:
+            loop.call_soon_threadsafe(settle, value, error)
+        except RuntimeError:  # the loop closed while the request ran
+            pass
+
+    threading.Thread(target=run, name="integrable-firewall-request", daemon=True).start()
+    try:
+        return await asyncio.wait_for(future, timeout)
+    except asyncio.TimeoutError:
+        raise _Timeout() from None
+
+
+# ---------------------------------------------------------------------- values
+
+
+def new_session_id() -> str:
+    """A random session id, for a run the framework gives no conversation id."""
+    return uuid.uuid4().hex
+
+
+def as_object(value: Any) -> Dict[str, Any]:
+    """A tool's arguments as a JSON object; anything else is ``{"input": value}``."""
+    if isinstance(value, Mapping):
+        return {str(k): jsonable(v) for k, v in value.items()}
+    converted = jsonable(value)
+    if isinstance(converted, dict):
+        return converted
+    return {"input": converted}
+
+
+def jsonable(value: Any, _depth: int = 0) -> Any:
+    """``value`` as JSON: a string stays a string, an object that cannot be
+    serialised is sent as its string form."""
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        return value if math.isfinite(value) else str(value)
+    if _depth > 64:
+        return str(value)
+    if isinstance(value, Mapping):
+        return {str(k): jsonable(v, _depth + 1) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [jsonable(v, _depth + 1) for v in value]
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value).decode("utf-8", errors="replace")
+    dump = getattr(value, "model_dump", None)  # pydantic v2 models
+    if callable(dump) and not isinstance(value, type):
+        try:
+            return jsonable(dump(mode="json"), _depth + 1)
+        except Exception:
+            pass
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        try:
+            return jsonable(dataclasses.asdict(value), _depth + 1)
+        except Exception:
+            pass
+    return str(value)
+
+
+def value_text(value: Any) -> str:
+    """A replacement result as the text a model reads: a string as is, anything else as JSON."""
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(jsonable(value), ensure_ascii=False, allow_nan=False)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def to_text(value: Any) -> str:
+    """Text for a prompt or a model-visible result: parts joined with newlines."""
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)):
+        parts = [_part_text(part) for part in value]
+        return "\n".join(part for part in parts if part)
+    try:
+        return json.dumps(jsonable(value), ensure_ascii=False, allow_nan=False)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _part_text(part: Any) -> str:
+    if isinstance(part, str):
+        return part
+    if isinstance(part, Mapping):
+        text = part.get("text")
+        return text if isinstance(text, str) else ""
+    text = getattr(part, "text", None)
+    return text if isinstance(text, str) else ""

integrable_firewall/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"