toolwall 0.2.0__tar.gz

toolwall-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+# Environment
+.env
+.env.local
+
+# Python
+.pytest_cache/
+.coverage
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+
+# Benchmark results (keep structure, ignore data)
+toap-bench/results/*.json
+toap-bench/results/*.csv
+!toap-bench/results/.gitkeep
+
+# Local working docs / pitch (not published to GitHub)
+memory.md
+agents.md
+AGENTS.md
+decisions.md
+prd.md
+plan.md
+SHARE.md
+OUTREACH.md
+EXECUTION_FLOW.md
+PARTNER_INSERT.md
+critiques/
+toap_architecture_strategy.pdf
+toap_executive_pitch.pdf
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db

toolwall-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Safwan Athar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolwall-0.2.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: toolwall
+Version: 0.2.0
+Summary: Fail-closed firewall for AI agent tool calls: schema + policy gate before any tool executes
+Project-URL: Homepage, https://github.com/Dev-Saif-Ops/Project_TOAP
+Author: Mohammad Safwan Athar
+License: MIT
+Keywords: agents,ai,guardrails,llm,mcp,security,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# toolwall (package)
+
+Fail-closed firewall for AI agent tool calls. See the [repo README](../README.md) for the full story.
+
+```bash
+pip install -e .
+python examples/quickstart.py   # no API key needed
+pytest                          # run the suite
+```
+
+## Modules
+
+| Module | Role |
+|---|---|
+| `intake.py` | Normalize OpenAI / Anthropic / Gemini / plain-dict tool calls |
+| `gate.py` | Fail-closed check → verdict → (optional) execute |
+| `schema.py` | Required args + type validation before `tool(**args)` |
+| `meter.py` | Audit events, token/cost accounting, JSON/CSV export |
+| `cli.py` | `toolwall report <audit.json>` |

toolwall-0.2.0/README.md

@@ -0,0 +1,19 @@
+# toolwall (package)
+
+Fail-closed firewall for AI agent tool calls. See the [repo README](../README.md) for the full story.
+
+```bash
+pip install -e .
+python examples/quickstart.py   # no API key needed
+pytest                          # run the suite
+```
+
+## Modules
+
+| Module | Role |
+|---|---|
+| `intake.py` | Normalize OpenAI / Anthropic / Gemini / plain-dict tool calls |
+| `gate.py` | Fail-closed check → verdict → (optional) execute |
+| `schema.py` | Required args + type validation before `tool(**args)` |
+| `meter.py` | Audit events, token/cost accounting, JSON/CSV export |
+| `cli.py` | `toolwall report <audit.json>` |

toolwall-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+# Pin hatchling below the release that emits Metadata-Version 2.4/2.5.
+# PyPI's upload endpoint accepts up to 2.3; newer metadata is rejected with a 400.
+requires = ["hatchling<1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "toolwall"
+version = "0.2.0"
+description = "Fail-closed firewall for AI agent tool calls: schema + policy gate before any tool executes"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Mohammad Safwan Athar" }]
+keywords = ["ai", "agents", "llm", "tool-calling", "guardrails", "security", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Security",
+]
+dependencies = []
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0.0"]
+dev = ["pytest>=8.0", "pytest-cov>=4.0"]
+
+[project.scripts]
+toolwall = "toolwall.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Dev-Saif-Ops/Project_TOAP"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/toolwall"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/toolwall", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

toolwall-0.2.0/src/toolwall/__init__.py

@@ -0,0 +1,56 @@
+"""toolwall: fail-closed firewall for AI agent tool calls.
+
+Structured outputs guarantee your agent's tool calls are well-formed.
+toolwall guarantees they're allowed.
+"""
+
+from toolwall.gate import Gate, GateResult, ToolRegistry, Verdict
+from toolwall.intake import IntakeError, ToolCall, parse_tool_calls
+from toolwall.meter import Meter, RunEvent, RunReport, extract_usage
+from toolwall.policy import (
+    Policy,
+    ends_with,
+    in_range,
+    matches,
+    max_len,
+    not_empty,
+    one_of,
+    starts_with,
+)
+from toolwall.schema import ToolSchema, schema_from_signature
+from toolwall.shield import Finding, Shield
+from toolwall.suggest import suggest_policies
+from toolwall.mcp_guard import GuardedCall, MCPGuard, to_mcp_error
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Gate",
+    "GateResult",
+    "Verdict",
+    "ToolRegistry",
+    "ToolCall",
+    "IntakeError",
+    "parse_tool_calls",
+    "Meter",
+    "RunEvent",
+    "RunReport",
+    "extract_usage",
+    "Policy",
+    "in_range",
+    "one_of",
+    "matches",
+    "max_len",
+    "ends_with",
+    "starts_with",
+    "not_empty",
+    "ToolSchema",
+    "schema_from_signature",
+    "Shield",
+    "Finding",
+    "suggest_policies",
+    "MCPGuard",
+    "GuardedCall",
+    "to_mcp_error",
+    "__version__",
+]

toolwall-0.2.0/src/toolwall/cli.py

@@ -0,0 +1,44 @@
+"""toolwall CLI — inspect meter/audit exports."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    data = json.loads(Path(args.file).read_text(encoding="utf-8"))
+    summary = data.get("summary") or {}
+    print(f"Model:  {data.get('model', 'unknown')}")
+    print(f"Events: {summary.get('event_count', len(data.get('events', [])))}")
+    for lane, stats in (summary.get("lanes") or {}).items():
+        print(f"\n[{lane}]")
+        for key in (
+            "prompt_tokens",
+            "completion_tokens",
+            "total_tokens",
+            "estimated_cost_usd",
+            "intercept_success_rate",
+        ):
+            print(f"  {key}: {stats.get(key)}")
+    if summary.get("note"):
+        print(f"\nNote: {summary['note']}")
+    return 0
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(prog="toolwall", description="toolwall dev tools")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    report = sub.add_parser("report", help="Print summary from a Meter JSON export")
+    report.add_argument("file", help="Path to meter/audit JSON")
+    report.set_defaults(func=cmd_report)
+
+    args = ap.parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

toolwall-0.2.0/src/toolwall/gate.py

@@ -0,0 +1,381 @@
+"""toolwall: fail-closed checkpoint between LLM tool calls and execution.
+
+    gate = Gate(default="deny", meter=meter, shield=Shield(mode="block"))
+    gate.register("db_query", db_query,
+                  schema=ToolSchema(required=["q"]),
+                  policy=Policy(constraints={"limit": in_range(1, 100)}))
+    gate.budget(max_calls=20)
+    result = gate.run(openai_response)   # check + execute only if allowed
+
+Check order (first failure blocks, fail-closed):
+  intake -> known tool -> budget -> schema -> policy -> shield -> approval
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+from toolwall.intake import IntakeError, ToolCall, parse_tool_calls
+from toolwall.meter import Meter, RunEvent
+from toolwall.policy import Policy
+from toolwall.schema import ToolSchema, schema_from_signature
+from toolwall.shield import Finding, Shield
+
+ToolFn = Callable[..., Any]
+DefaultMode = Literal["deny", "allow"]
+ApprovalHandler = Callable[["GateResult"], bool]
+
+
+class Verdict(str, Enum):
+    ALLOW = "allow"
+    BLOCK = "block"
+    NEEDS_APPROVAL = "needs_approval"
+
+
+@dataclass
+class ToolRegistry:
+    """Maps tool names to callables (+ optional schema and policy).
+
+    Registration is the allowlist: unregistered tools always block.
+    """
+
+    _tools: dict[str, ToolFn] = field(default_factory=dict)
+    _schemas: dict[str, ToolSchema] = field(default_factory=dict)
+    _policies: dict[str, Policy] = field(default_factory=dict)
+
+    def register(
+        self,
+        name: str,
+        fn: ToolFn,
+        schema: ToolSchema | None = None,
+        *,
+        policy: Policy | None = None,
+        infer_schema: bool = False,
+    ) -> None:
+        self._tools[name] = fn
+        if schema is not None:
+            self._schemas[name] = schema
+        elif infer_schema:
+            self._schemas[name] = schema_from_signature(fn)
+        if policy is not None:
+            self._policies[name] = policy
+
+    def get(self, name: str) -> ToolFn | None:
+        return self._tools.get(name)
+
+    def get_schema(self, name: str) -> ToolSchema | None:
+        return self._schemas.get(name)
+
+    def get_policy(self, name: str) -> Policy | None:
+        return self._policies.get(name)
+
+    def names(self) -> list[str]:
+        return list(self._tools.keys())
+
+
+@dataclass
+class GateResult:
+    verdict: Verdict
+    call: ToolCall | None = None
+    reasons: list[str] = field(default_factory=list)
+    executed: bool = False
+    return_value: Any = None
+    error: str | None = None
+    findings: list[Finding] = field(default_factory=list)  # shield hits (value-free)
+    dry_run: bool = False  # True when the gate simulated execution
+
+    @property
+    def allowed(self) -> bool:
+        return self.verdict is Verdict.ALLOW
+
+
+class Gate:
+    """Fail-closed gate.
+
+    default="deny"  -> a registered tool with NO schema is still blocked
+    default="allow" -> schema optional; registered tool without schema passes
+
+    approval: optional handler called by run()/run_all() when a policy demands
+    approval. Returns True to execute. Without a handler, NEEDS_APPROVAL calls
+    are never executed (fail closed).
+    """
+
+    def __init__(
+        self,
+        registry: ToolRegistry | None = None,
+        *,
+        default: DefaultMode = "deny",
+        meter: Meter | None = None,
+        shield: Shield | None = None,
+        approval: ApprovalHandler | None = None,
+        dry_run: bool = False,
+        lane: str = "gate",
+    ):
+        if default not in ("deny", "allow"):
+            raise ValueError(f"default must be 'deny' or 'allow', got {default!r}")
+        self.registry = registry or ToolRegistry()
+        self.default = default
+        self.meter = meter
+        self.shield = shield
+        self.approval = approval
+        self.dry_run = dry_run
+        self.lane = lane
+        self.history: list[GateResult] = []  # every checked result, for reports/suggest
+        self._budget: dict[str, Any] = {}
+        self._executed_calls = 0
+        self._executed_per_tool: dict[str, int] = {}
+
+    def register(
+        self,
+        name: str,
+        fn: ToolFn,
+        schema: ToolSchema | None = None,
+        *,
+        policy: Policy | None = None,
+        infer_schema: bool = False,
+    ) -> None:
+        self.registry.register(name, fn, schema, policy=policy, infer_schema=infer_schema)
+
+    # -- budget ---------------------------------------------------------------
+
+    def budget(
+        self,
+        *,
+        max_calls: int | None = None,
+        max_calls_per_tool: int | None = None,
+        max_usd: float | None = None,
+    ) -> None:
+        if max_usd is not None and self.meter is None:
+            raise ValueError("max_usd budget requires a meter (cost is meter-derived)")
+        self._budget = {
+            "max_calls": max_calls,
+            "max_calls_per_tool": max_calls_per_tool,
+            "max_usd": max_usd,
+        }
+
+    def _budget_violation(self, call: ToolCall) -> str | None:
+        if not self._budget:
+            return None
+        max_calls = self._budget.get("max_calls")
+        if max_calls is not None and self._executed_calls >= max_calls:
+            return f"budget exceeded: max_calls={max_calls} already executed"
+        per_tool = self._budget.get("max_calls_per_tool")
+        if per_tool is not None and self._executed_per_tool.get(call.name, 0) >= per_tool:
+            return f"budget exceeded: max_calls_per_tool={per_tool} for {call.name!r}"
+        max_usd = self._budget.get("max_usd")
+        if max_usd is not None and self.meter is not None:
+            spent = self.meter.report.estimate_cost_usd(self.lane)
+            if spent >= max_usd:
+                return f"budget exceeded: estimated ${spent:.4f} >= max_usd={max_usd}"
+        return None
+
+    # -- checking ---------------------------------------------------------------
+
+    def check_all(self, payload: Any) -> list[GateResult]:
+        try:
+            calls = parse_tool_calls(payload)
+        except IntakeError as exc:
+            return [self._record(GateResult(Verdict.BLOCK, reasons=[f"intake: {exc}"]))]
+        if not calls:
+            return [self._record(GateResult(Verdict.BLOCK, reasons=["intake: no tool calls in payload"]))]
+        return [self._check_one(call) for call in calls]
+
+    def check(self, payload: Any) -> GateResult:
+        results = self.check_all(payload)
+        if len(results) != 1:
+            raise ValueError(f"expected exactly 1 tool call, got {len(results)}; use check_all()")
+        return results[0]
+
+    def _check_one(self, call: ToolCall) -> GateResult:
+        if self.registry.get(call.name) is None:
+            return self._record(GateResult(Verdict.BLOCK, call, [f"unknown tool: {call.name!r}"]))
+
+        budget_reason = self._budget_violation(call)
+        if budget_reason is not None:
+            return self._record(GateResult(Verdict.BLOCK, call, [budget_reason]))
+
+        schema = self.registry.get_schema(call.name)
+        if schema is None:
+            if self.default == "deny":
+                return self._record(
+                    GateResult(
+                        Verdict.BLOCK,
+                        call,
+                        [f"no schema registered for {call.name!r} and gate default is deny"],
+                    )
+                )
+        else:
+            errors = schema.validate(call.args)
+            if errors:
+                return self._record(GateResult(Verdict.BLOCK, call, errors))
+
+        policy = self.registry.get_policy(call.name)
+        if policy is not None:
+            errors = policy.validate(call.args)
+            if errors:
+                return self._record(GateResult(Verdict.BLOCK, call, errors))
+
+        findings: list[Finding] = []
+        if self.shield is not None:
+            if self.shield.mode == "redact":
+                call.args, findings = self.shield.redact_args(call.args)
+            else:
+                findings = self.shield.scan_args(call.args)
+                if findings and self.shield.mode == "block":
+                    reasons = [
+                        f"secret detected ({f.kind}) in arg {f.arg!r}" for f in findings
+                    ]
+                    return self._record(
+                        GateResult(Verdict.BLOCK, call, reasons, findings=findings)
+                    )
+
+        if policy is not None and policy.require_approval:
+            return self._record(
+                GateResult(
+                    Verdict.NEEDS_APPROVAL,
+                    call,
+                    [f"approval required for {call.name!r}"],
+                    findings=findings,
+                )
+            )
+
+        return self._record(GateResult(Verdict.ALLOW, call, findings=findings))
+
+    # -- execution ----------------------------------------------------------------
+
+    def execute(self, result: GateResult) -> GateResult:
+        if not result.allowed or result.call is None:
+            joined = "; ".join(result.reasons) or "no call"
+            raise PermissionError(f"refusing to execute a {result.verdict.value} result: {joined}")
+        self._executed_calls += 1
+        self._executed_per_tool[result.call.name] = (
+            self._executed_per_tool.get(result.call.name, 0) + 1
+        )
+        if self.dry_run:
+            result.dry_run = True
+            if self.meter is not None:
+                self.meter.record(
+                    RunEvent(
+                        lane=self.lane,
+                        kind="tool",
+                        ok=True,
+                        namespace=result.call.name,
+                        meta={"dry_run": True, "would_execute": True},
+                    )
+                )
+            return result
+        tool = self.registry.get(result.call.name)
+        if tool is None:  # registry mutated between check and execute
+            result.error = f"unknown tool at execute time: {result.call.name!r}"
+        else:
+            try:
+                result.return_value = tool(**result.call.args)
+                result.executed = True
+            except Exception as exc:
+                result.error = f"{type(exc).__name__}: {exc}"
+        if self.meter is not None:
+            self.meter.record(
+                RunEvent(
+                    lane=self.lane,
+                    kind="tool",
+                    ok=result.executed,
+                    namespace=result.call.name,
+                    error=result.error,
+                )
+            )
+        return result
+
+    def _resolve_approval(self, result: GateResult) -> GateResult:
+        """Called by run/run_all on NEEDS_APPROVAL. Fail closed without a handler."""
+        if self.approval is None:
+            return result
+        try:
+            granted = bool(self.approval(result))
+        except Exception as exc:
+            result.verdict = Verdict.BLOCK
+            result.reasons.append(f"approval handler raised {type(exc).__name__}: fails closed")
+            return self._record_transition(result, "approval-error")
+        if granted:
+            result.verdict = Verdict.ALLOW
+            result.reasons = []
+            return self._record_transition(result, "approval-granted")
+        result.verdict = Verdict.BLOCK
+        result.reasons.append("approval denied")
+        return self._record_transition(result, "approval-denied")
+
+    def run(self, payload: Any) -> GateResult:
+        result = self.check(payload)
+        if result.verdict is Verdict.NEEDS_APPROVAL:
+            result = self._resolve_approval(result)
+        if result.allowed:
+            return self.execute(result)
+        return result
+
+    def run_all(self, payload: Any) -> list[GateResult]:
+        out: list[GateResult] = []
+        for result in self.check_all(payload):
+            if result.verdict is Verdict.NEEDS_APPROVAL:
+                result = self._resolve_approval(result)
+            out.append(self.execute(result) if result.allowed else result)
+        return out
+
+    # -- reporting ----------------------------------------------------------------
+
+    def report(self) -> dict[str, Any]:
+        """Summary of everything this gate has seen. Useful after a dry run."""
+        by_verdict: dict[str, int] = {}
+        by_tool: dict[str, dict[str, int]] = {}
+        blocked_reasons: list[str] = []
+        finding_kinds: dict[str, int] = {}
+        for r in self.history:
+            by_verdict[r.verdict.value] = by_verdict.get(r.verdict.value, 0) + 1
+            name = r.call.name if r.call else "(unparsed)"
+            tool_row = by_tool.setdefault(name, {"allow": 0, "block": 0, "needs_approval": 0})
+            tool_row[r.verdict.value] = tool_row.get(r.verdict.value, 0) + 1
+            if r.verdict is Verdict.BLOCK and r.reasons:
+                blocked_reasons.append(f"{name}: {r.reasons[0]}")
+            for f in r.findings:
+                finding_kinds[f.kind] = finding_kinds.get(f.kind, 0) + 1
+        return {
+            "dry_run": self.dry_run,
+            "calls_checked": len(self.history),
+            "verdicts": by_verdict,
+            "would_execute" if self.dry_run else "executed": self._executed_calls,
+            "by_tool": by_tool,
+            "blocked_reasons": blocked_reasons,
+            "secret_findings_by_kind": finding_kinds,
+        }
+
+    # -- internals -------------------------------------------------------------------
+
+    def _record(self, result: GateResult) -> GateResult:
+        self.history.append(result)
+        if self.meter is not None:
+            self.meter.record_intercept(
+                lane=self.lane,
+                ok=result.verdict is Verdict.ALLOW,
+                namespace=result.call.name if result.call else None,
+                error="; ".join(result.reasons) or None,
+                meta={
+                    "verdict": result.verdict.value,
+                    "default": self.default,
+                    "findings": [f.kind for f in result.findings],
+                },
+            )
+        return result
+
+    def _record_transition(self, result: GateResult, event: str) -> GateResult:
+        if self.meter is not None:
+            self.meter.record(
+                RunEvent(
+                    lane=self.lane,
+                    kind="note",
+                    ok=result.verdict is Verdict.ALLOW,
+                    namespace=result.call.name if result.call else None,
+                    meta={"approval": event},
+                )
+            )
+        return result