sovest-firewall 0.1.0__tar.gz

sovest_firewall-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: sovest-firewall
+Version: 0.1.0
+Summary: Stdlib-only Python client for the Sovest Agent Honesty Firewall HTTP surface (claim <= evidence, action <= authority).
+Author: Sovest
+License: Proprietary
+Project-URL: API contract, https://example.invalid/AGENT_FIREWALL_API_v1
+Keywords: agent,firewall,honesty,claim-ceiling,guardrail
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# sovest-firewall (Python SDK)
+
+Stdlib-only Python client for the **Sovest Agent Honesty Firewall** HTTP surface.
+It calls one pre-action gate before your agent does anything consequential.
+
+> Honest claim ceiling: the firewall enforces a **policy** — claim ≤ evidence, action ≤ authority.
+> It does **not** make an agent correct, safe, or aligned, and it is not a guarantee of safe outcomes.
+> It blocks unsupported claims from becoming actions and makes admitted ones scoped, verifiable,
+> disputable, and correctable.
+
+**Status:** v0.1.0. Not yet published to PyPI. Dependency-free (uses `urllib` from the standard library).
+Requires Python >= 3.9.
+
+## Install
+
+From this directory (editable install):
+
+```bash
+pip install -e .
+```
+
+That exposes the `sovest_firewall` package importably. No third-party packages are pulled in.
+
+## Usage
+
+```python
+from sovest_firewall import FirewallClient, NotAdmitted, guard
+
+fw = FirewallClient("http://127.0.0.1:8787")
+
+# 1. Get a verdict (never raises on a refusal — the refusal IS the answer):
+v = fw.check(
+    claim_text="Refund approved for order 4821",
+    claim_type="LIVE_PROCESS",
+    scope="refunds:order_4821",
+    requested_action="REFUND_APPROVE",
+    action_impact="consequential",
+    evidence_refs=["sha256:order_record", "sha256:customer_chatlog"],
+    authority_refs=["refund_policy_v2"],
+)
+print(v["verdict"], v["admitted"])
+
+# 2. Admit + record (returns the receipt, raises NotAdmitted on refusal):
+try:
+    receipt = fw.admit(
+        claim_text="Refund approved for order 4821",
+        scope="refunds:order_4821",
+        requested_action="REFUND_APPROVE",
+        action_impact="consequential",
+        evidence_refs=["sha256:order_record"],
+        authority_refs=["refund_policy_v2"],
+    )
+    print(receipt["admissibility_id"])
+except NotAdmitted as e:
+    print("refused:", e.verdict["reason"])
+
+# 3. Guard a callable — runs it ONLY if the firewall admits the action:
+def do_refund():
+    ...  # the real side effect
+result = guard(
+    do_refund, fw,
+    claim_text="Refund approved for order 4821",
+    scope="refunds:order_4821",
+    requested_action="REFUND_APPROVE",
+    evidence_refs=["sha256:order_record"],
+    authority_refs=["refund_policy_v2"],
+)
+```
+
+## API surface (stable for v0.1.0)
+
+| symbol | purpose |
+|---|---|
+| `FirewallClient(base_url, timeout)` | client bound to a firewall server |
+| `.check(**fields) -> dict` | get a verdict; does not raise on refusal |
+| `.admit(**fields) -> dict` | admit + record; raises `NotAdmitted` on refusal |
+| `.build_request(path, fields)` | build the `urllib` request without sending (offline tests) |
+| `guard(action, client, **fields)` | run `action` only if admitted |
+| `NotAdmitted` | exception carrying the full refusal verdict (`.verdict`) |
+| `FirewallError` | transport / unexpected-status error |
+
+## Running the examples and checks
+
+- `examples/quickstart.py` — runnable end-to-end when a firewall server is up
+  (start `python3 ../../server.py` first), prints the verdict.
+- `tests/test_offline.py` — offline check; constructs a client and validates request
+  serialization (URL, method, headers, JSON body) with no network call.
+
+See `SDK_PY_CHECK.txt` for captured proof of the import + offline checks.

sovest_firewall-0.1.0/README.md

@@ -0,0 +1,89 @@
+# sovest-firewall (Python SDK)
+
+Stdlib-only Python client for the **Sovest Agent Honesty Firewall** HTTP surface.
+It calls one pre-action gate before your agent does anything consequential.
+
+> Honest claim ceiling: the firewall enforces a **policy** — claim ≤ evidence, action ≤ authority.
+> It does **not** make an agent correct, safe, or aligned, and it is not a guarantee of safe outcomes.
+> It blocks unsupported claims from becoming actions and makes admitted ones scoped, verifiable,
+> disputable, and correctable.
+
+**Status:** v0.1.0. Not yet published to PyPI. Dependency-free (uses `urllib` from the standard library).
+Requires Python >= 3.9.
+
+## Install
+
+From this directory (editable install):
+
+```bash
+pip install -e .
+```
+
+That exposes the `sovest_firewall` package importably. No third-party packages are pulled in.
+
+## Usage
+
+```python
+from sovest_firewall import FirewallClient, NotAdmitted, guard
+
+fw = FirewallClient("http://127.0.0.1:8787")
+
+# 1. Get a verdict (never raises on a refusal — the refusal IS the answer):
+v = fw.check(
+    claim_text="Refund approved for order 4821",
+    claim_type="LIVE_PROCESS",
+    scope="refunds:order_4821",
+    requested_action="REFUND_APPROVE",
+    action_impact="consequential",
+    evidence_refs=["sha256:order_record", "sha256:customer_chatlog"],
+    authority_refs=["refund_policy_v2"],
+)
+print(v["verdict"], v["admitted"])
+
+# 2. Admit + record (returns the receipt, raises NotAdmitted on refusal):
+try:
+    receipt = fw.admit(
+        claim_text="Refund approved for order 4821",
+        scope="refunds:order_4821",
+        requested_action="REFUND_APPROVE",
+        action_impact="consequential",
+        evidence_refs=["sha256:order_record"],
+        authority_refs=["refund_policy_v2"],
+    )
+    print(receipt["admissibility_id"])
+except NotAdmitted as e:
+    print("refused:", e.verdict["reason"])
+
+# 3. Guard a callable — runs it ONLY if the firewall admits the action:
+def do_refund():
+    ...  # the real side effect
+result = guard(
+    do_refund, fw,
+    claim_text="Refund approved for order 4821",
+    scope="refunds:order_4821",
+    requested_action="REFUND_APPROVE",
+    evidence_refs=["sha256:order_record"],
+    authority_refs=["refund_policy_v2"],
+)
+```
+
+## API surface (stable for v0.1.0)
+
+| symbol | purpose |
+|---|---|
+| `FirewallClient(base_url, timeout)` | client bound to a firewall server |
+| `.check(**fields) -> dict` | get a verdict; does not raise on refusal |
+| `.admit(**fields) -> dict` | admit + record; raises `NotAdmitted` on refusal |
+| `.build_request(path, fields)` | build the `urllib` request without sending (offline tests) |
+| `guard(action, client, **fields)` | run `action` only if admitted |
+| `NotAdmitted` | exception carrying the full refusal verdict (`.verdict`) |
+| `FirewallError` | transport / unexpected-status error |
+
+## Running the examples and checks
+
+- `examples/quickstart.py` — runnable end-to-end when a firewall server is up
+  (start `python3 ../../server.py` first), prints the verdict.
+- `tests/test_offline.py` — offline check; constructs a client and validates request
+  serialization (URL, method, headers, JSON body) with no network call.
+
+See `SDK_PY_CHECK.txt` for captured proof of the import + offline checks.

sovest_firewall-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sovest-firewall"
+version = "0.1.0"
+description = "Stdlib-only Python client for the Sovest Agent Honesty Firewall HTTP surface (claim <= evidence, action <= authority)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Sovest" }]
+keywords = ["agent", "firewall", "honesty", "claim-ceiling", "guardrail"]
+# Stdlib only (urllib) — no required runtime dependencies.
+dependencies = []
+
+[project.urls]
+"API contract" = "https://example.invalid/AGENT_FIREWALL_API_v1"
+
+[tool.setuptools]
+packages = ["sovest_firewall"]

sovest_firewall-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sovest_firewall-0.1.0/sovest_firewall/__init__.py

@@ -0,0 +1,21 @@
+"""Sovest Agent Honesty Firewall — Python client SDK (stdlib only).
+
+Public API surface (stable for v0.1.0):
+
+    from sovest_firewall import FirewallClient, NotAdmitted, FirewallError, guard
+
+See README.md for usage. This package is dependency-free (urllib).
+"""
+from __future__ import annotations
+
+from .client import FirewallClient, FirewallError, NotAdmitted, guard
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FirewallClient",
+    "FirewallError",
+    "NotAdmitted",
+    "guard",
+    "__version__",
+]

sovest_firewall-0.1.0/sovest_firewall/client.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Sovest Agent Honesty Firewall — tiny Python client SDK (stdlib only).
+
+Talks to the firewall HTTP server (server.py) using urllib. No external dependencies.
+
+Usage:
+
+    from sovest_firewall import FirewallClient, NotAdmitted, guard
+
+    fw = FirewallClient("http://127.0.0.1:8787")
+
+    # Get a verdict (never raises on a refusal — the refusal IS the answer):
+    v = fw.check(
+        claim_text="Refund approved for order 4821",
+        claim_type="LIVE_PROCESS",
+        scope="refunds:order_4821",
+        requested_action="REFUND_APPROVE",
+        evidence_refs=["sha256:order", "sha256:chatlog"],
+        authority_refs=["refund_policy_v2"],
+    )
+    print(v["verdict"])
+
+    # Admit + record (returns the receipt, raises NotAdmitted on refusal):
+    receipt = fw.admit(**fields)
+
+    # Guard a callable: run it ONLY if the firewall admits the action.
+    result = guard(do_refund, fw, claim_text=..., requested_action="REFUND_APPROVE", ...)
+
+Honest claim ceiling: this enforces a policy (claim <= evidence, action <= authority).
+It does NOT make an agent correct, safe, or aligned. It blocks unsupported claims from
+becoming actions and makes admitted ones scoped, verifiable, disputable, and correctable.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict
+
+
+class FirewallError(RuntimeError):
+    """Transport / server error talking to the firewall."""
+
+
+class NotAdmitted(Exception):
+    """Raised when an action was refused. Carries the full refusal verdict."""
+
+    def __init__(self, verdict: Dict[str, Any]):
+        self.verdict = verdict
+        msg = "%s: %s" % (verdict.get("verdict", "REFUSED"), verdict.get("reason", ""))
+        super().__init__(msg)
+
+
+class FirewallClient:
+    def __init__(self, base_url: str = "http://127.0.0.1:8787", timeout: float = 10.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ---- serialization (no network) ----
+    def build_request(self, path: str, fields: Dict[str, Any]) -> urllib.request.Request:
+        """Build the urllib Request for a call WITHOUT sending it.
+
+        Useful for offline tests that want to assert the URL, method, headers,
+        and JSON body the client would send. No network access happens here.
+        """
+        url = self.base_url + path
+        data = json.dumps(fields).encode("utf-8")
+        return urllib.request.Request(
+            url, data=data, method="POST",
+            headers={"Content-Type": "application/json"},
+        )
+
+    # ---- low-level POST ----
+    def _post(self, path: str, fields: Dict[str, Any]) -> tuple[int, Dict[str, Any]]:
+        url = self.base_url + path
+        data = json.dumps(fields).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=data, method="POST",
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.status, json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            # 400 from /actions/admit carries the refusal verdict — read and return it.
+            body = e.read().decode("utf-8")
+            try:
+                parsed = json.loads(body)
+            except json.JSONDecodeError:
+                raise FirewallError("HTTP %s: %s" % (e.code, body)) from e
+            return e.code, parsed
+        except urllib.error.URLError as e:
+            raise FirewallError("cannot reach firewall at %s: %s" % (url, e)) from e
+
+    # ---- public API ----
+    def check(self, **fields: Any) -> Dict[str, Any]:
+        """Return the verdict dict. Does not raise on a refusal (the refusal is the answer)."""
+        status, body = self._post("/claims/check", fields)
+        if status != 200:
+            raise FirewallError("unexpected status %s from /claims/check: %s" % (status, body))
+        return body
+
+    def admit(self, **fields: Any) -> Dict[str, Any]:
+        """Admit + record the action; return the admissibility receipt.
+
+        Raises NotAdmitted (carrying the refusal verdict) if the action was refused.
+        """
+        status, body = self._post("/actions/admit", fields)
+        if status == 200:
+            return body  # admissibility receipt
+        if status == 400:
+            raise NotAdmitted(body)
+        raise FirewallError("unexpected status %s from /actions/admit: %s" % (status, body))
+
+
+def guard(action: Callable[..., Any], client: FirewallClient, *,
+          action_args: tuple = (), action_kwargs: Dict[str, Any] | None = None,
+          **fields: Any) -> Any:
+    """Run `action(*action_args, **action_kwargs)` ONLY if the firewall admits it.
+
+    The firewall claim fields are passed as keyword args (claim_text, requested_action, ...).
+    Raises NotAdmitted before the action runs if it is refused. On admission, the action runs
+    and its return value is returned (the receipt is available via client.admit if needed).
+    """
+    verdict = client.check(**fields)
+    if not verdict.get("admitted"):
+        raise NotAdmitted(verdict)
+    return action(*action_args, **(action_kwargs or {}))

sovest_firewall-0.1.0/sovest_firewall.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: sovest-firewall
+Version: 0.1.0
+Summary: Stdlib-only Python client for the Sovest Agent Honesty Firewall HTTP surface (claim <= evidence, action <= authority).
+Author: Sovest
+License: Proprietary
+Project-URL: API contract, https://example.invalid/AGENT_FIREWALL_API_v1
+Keywords: agent,firewall,honesty,claim-ceiling,guardrail
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# sovest-firewall (Python SDK)
+
+Stdlib-only Python client for the **Sovest Agent Honesty Firewall** HTTP surface.
+It calls one pre-action gate before your agent does anything consequential.
+
+> Honest claim ceiling: the firewall enforces a **policy** — claim ≤ evidence, action ≤ authority.
+> It does **not** make an agent correct, safe, or aligned, and it is not a guarantee of safe outcomes.
+> It blocks unsupported claims from becoming actions and makes admitted ones scoped, verifiable,
+> disputable, and correctable.
+
+**Status:** v0.1.0. Not yet published to PyPI. Dependency-free (uses `urllib` from the standard library).
+Requires Python >= 3.9.
+
+## Install
+
+From this directory (editable install):
+
+```bash
+pip install -e .
+```
+
+That exposes the `sovest_firewall` package importably. No third-party packages are pulled in.
+
+## Usage
+
+```python
+from sovest_firewall import FirewallClient, NotAdmitted, guard
+
+fw = FirewallClient("http://127.0.0.1:8787")
+
+# 1. Get a verdict (never raises on a refusal — the refusal IS the answer):
+v = fw.check(
+    claim_text="Refund approved for order 4821",
+    claim_type="LIVE_PROCESS",
+    scope="refunds:order_4821",
+    requested_action="REFUND_APPROVE",
+    action_impact="consequential",
+    evidence_refs=["sha256:order_record", "sha256:customer_chatlog"],
+    authority_refs=["refund_policy_v2"],
+)
+print(v["verdict"], v["admitted"])
+
+# 2. Admit + record (returns the receipt, raises NotAdmitted on refusal):
+try:
+    receipt = fw.admit(
+        claim_text="Refund approved for order 4821",
+        scope="refunds:order_4821",
+        requested_action="REFUND_APPROVE",
+        action_impact="consequential",
+        evidence_refs=["sha256:order_record"],
+        authority_refs=["refund_policy_v2"],
+    )
+    print(receipt["admissibility_id"])
+except NotAdmitted as e:
+    print("refused:", e.verdict["reason"])
+
+# 3. Guard a callable — runs it ONLY if the firewall admits the action:
+def do_refund():
+    ...  # the real side effect
+result = guard(
+    do_refund, fw,
+    claim_text="Refund approved for order 4821",
+    scope="refunds:order_4821",
+    requested_action="REFUND_APPROVE",
+    evidence_refs=["sha256:order_record"],
+    authority_refs=["refund_policy_v2"],
+)
+```
+
+## API surface (stable for v0.1.0)
+
+| symbol | purpose |
+|---|---|
+| `FirewallClient(base_url, timeout)` | client bound to a firewall server |
+| `.check(**fields) -> dict` | get a verdict; does not raise on refusal |
+| `.admit(**fields) -> dict` | admit + record; raises `NotAdmitted` on refusal |
+| `.build_request(path, fields)` | build the `urllib` request without sending (offline tests) |
+| `guard(action, client, **fields)` | run `action` only if admitted |
+| `NotAdmitted` | exception carrying the full refusal verdict (`.verdict`) |
+| `FirewallError` | transport / unexpected-status error |
+
+## Running the examples and checks
+
+- `examples/quickstart.py` — runnable end-to-end when a firewall server is up
+  (start `python3 ../../server.py` first), prints the verdict.
+- `tests/test_offline.py` — offline check; constructs a client and validates request
+  serialization (URL, method, headers, JSON body) with no network call.
+
+See `SDK_PY_CHECK.txt` for captured proof of the import + offline checks.

sovest_firewall-0.1.0/sovest_firewall.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+sovest_firewall/__init__.py
+sovest_firewall/client.py
+sovest_firewall.egg-info/PKG-INFO
+sovest_firewall.egg-info/SOURCES.txt
+sovest_firewall.egg-info/dependency_links.txt
+sovest_firewall.egg-info/top_level.txt
+tests/test_offline.py

sovest_firewall-0.1.0/sovest_firewall.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sovest_firewall-0.1.0/sovest_firewall.egg-info/top_level.txt

@@ -0,0 +1 @@
+sovest_firewall

sovest_firewall-0.1.0/tests/test_offline.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Offline unit check — no network access.
+
+Constructs a FirewallClient and validates that it serializes a request the way
+the firewall HTTP surface expects (URL, method, headers, JSON body). Uses the
+client's `build_request` helper, which builds the urllib Request without sending.
+
+Run directly:  python3 tests/test_offline.py
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from sovest_firewall import FirewallClient
+
+
+def test_serialization() -> None:
+    fw = FirewallClient("http://127.0.0.1:8787/")  # trailing slash should be stripped
+    assert fw.base_url == "http://127.0.0.1:8787", fw.base_url
+
+    fields = dict(
+        claim_text="Refund approved for order 4821",
+        claim_type="LIVE_PROCESS",
+        scope="refunds:order_4821",
+        requested_action="REFUND_APPROVE",
+        evidence_refs=["sha256:order_record"],
+        authority_refs=["refund_policy_v2"],
+    )
+
+    req = fw.build_request("/claims/check", fields)
+
+    assert req.full_url == "http://127.0.0.1:8787/claims/check", req.full_url
+    assert req.method == "POST", req.method
+    assert req.headers.get("Content-type") == "application/json", req.headers
+
+    body = json.loads(req.data.decode("utf-8"))
+    assert body == fields, body
+    # round-trips exactly: no fields dropped or renamed
+    assert body["requested_action"] == "REFUND_APPROVE"
+    assert body["evidence_refs"] == ["sha256:order_record"]
+
+
+def main() -> int:
+    test_serialization()
+    print("OK: offline serialization check passed (no network used)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())