toolboundary 0.1.0__tar.gz

toolboundary-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev + langchain extras
+        run: pip install -e ".[dev,langchain]"
+
+      - name: Lint with ruff
+        run: ruff check src tests
+
+      - name: Run tests with coverage
+        run: pytest --cov=toolboundary --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check package with twine
+        run: twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

toolboundary-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses PyPI "Trusted Publishing" (OIDC) -- no API token stored in
+        # GitHub secrets required. Configure this repo/workflow as a
+        # trusted publisher at https://pypi.org/manage/project/toolboundary/settings/publishing/
+        # after your first manual upload, or use a PYPI_API_TOKEN secret
+        # instead if you prefer the classic token flow.

toolboundary-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+
+# AgentGuard runtime artifacts (audit logs from examples/local testing)
+*.jsonl
+agentguard-audit.jsonl

toolboundary-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to ToolBoundary
+
+Thanks for considering a contribution. ToolBoundary is intentionally small in
+scope — please read the "Known Limitations" section of the README before
+proposing a feature, to check it fits the project's design philosophy
+(no required infrastructure, fail-closed by default, framework-agnostic
+core with optional integrations).
+
+## Development setup
+
+```bash
+git clone https://github.com/Jaycubic/toolboundary.git
+cd toolboundary
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev,langchain]"
+```
+
+## Running tests
+
+```bash
+pytest                          # full suite with coverage report
+pytest tests/test_boundary.py   # a single file
+pytest -k kill_switch           # tests matching a keyword
+```
+
+All new code should include tests. We aim to keep coverage above 90%.
+
+## Linting
+
+```bash
+ruff check src tests
+mypy src
+```
+
+## Project structure
+
+```
+src/toolboundary/
+    __init__.py          # public API surface
+    boundary.py           # core Boundary decision engine
+    permissions.py        # ToolPermission
+    enums.py               # AutonomyLevel, AccessMode, etc.
+    exceptions.py          # BoundaryViolation, ApprovalRequired, etc.
+    audit.py                # AuditTrail and sinks (Logging, JSONL, Webhook)
+    tokens.py               # AuthorizationToken, TokenIssuer (network enforcement)
+    network.py              # NetworkEnforcer proxy (optional, stdlib-only)
+    _rate_limiter.py        # internal sliding-window rate limiter
+    decorators.py            # @guarded_tool
+    integrations/
+        langchain.py          # LangChain BaseTool wrapping
+```
+
+## Good first contributions
+
+These are scoped, valuable, and don't require redesigning anything:
+
+- **Redis-backed rate limiter / token store** — for multi-process
+  deployments. Implement the same interface as `SlidingWindowRateLimiter`
+  and `InMemoryTokenStore` and submit as an optional extra
+  (`toolboundary[redis]`).
+- **CrewAI / AutoGen / LangGraph integrations** — mirror the structure of
+  `integrations/langchain.py`: wrap the framework's actual tool-execution
+  call site, not just provide a decorator the user has to remember to apply.
+- **A minimal local dashboard** — a single-file script that tails a
+  `JSONLFileSink` log and renders a simple live view. Should have zero
+  required dependencies beyond the standard library, in keeping with the
+  project's "no infrastructure required" philosophy — a `flask`/`fastapi`-based
+  version is welcome too, but should be a clearly optional extra, not folded
+  into core.
+- **More policy hook examples** — e.g. a time-of-day hook, a
+  geo/IP-based hook, or an example calling out to an external policy
+  engine.
+
+## Pull request guidelines
+
+1. Open an issue first for anything beyond a small bugfix, so we can agree
+   on the approach before you invest time.
+2. Keep the core package (`toolboundary/__init__.py` and everything it
+   imports by default) dependency-free. New framework integrations belong
+   under `integrations/` with their own optional extra in `pyproject.toml`.
+3. Match the existing docstring style — every public class/function should
+   explain *why*, not just *what*, especially around security-relevant
+   decisions (fail-open vs fail-closed, what a check does and doesn't cover).
+4. Add tests that would fail without your change.
+
+## Reporting security issues
+
+Please do not open a public GitHub issue for a security vulnerability.
+See `SECURITY.md` for how to report privately.
+
+## Code of conduct
+
+Be respectful. Assume good faith. This is a small project maintained in
+someone's spare time — patience with review turnaround is appreciated.

toolboundary-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoffrey (Jaycubic)
+
+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.

toolboundary-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.5
+Name: toolboundary
+Version: 0.1.0
+Summary: Runtime boundary enforcement for AI agents -- as a library, not a service.
+Project-URL: Homepage, https://github.com/Jaycubic/toolboundary
+Project-URL: Repository, https://github.com/Jaycubic/toolboundary
+Project-URL: Issues, https://github.com/Jaycubic/toolboundary/issues
+Author-email: Jofrey John Joseph <jofreyjohnmrutu01@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent-security,ai-agents,ai-governance,guardrails,langchain,llm,tool-calling,zero-trust
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: network
+Description-Content-Type: text/markdown
+
+# ToolBoundary
+
+**Runtime boundary enforcement for AI agents — as a library, not a service.**
+
+[![PyPI](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/toolboundary/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+ToolBoundary answers one question, fast and locally, every time your agent tries to call a
+tool: **"is this exact call allowed, right now?"**
+
+No separate web app. No database to stand up. No dashboard to log into. No subscription.
+Your policy is plain Python, version-controlled with the rest of your code.
+
+```bash
+pip install toolboundary
+```
+
+## Why this exists
+
+Enterprise AI-governance platforms (agent registries, policy engines, approval
+dashboards) make sense when a large organization has dozens of AI agents built by
+different teams and needs a compliance layer to track all of them. That's real
+infrastructure for a real problem — but it's disproportionate for the much more common
+case: **one developer or a small team building one to a handful of agents**, who just
+need to make sure a tool-calling agent can't do something catastrophic.
+
+ToolBoundary is built for that second case. It costs nothing, requires no
+infrastructure, and takes minutes to add to an existing agent.
+
+## Quickstart
+
+```python
+from toolboundary import Boundary, ToolPermission, AutonomyLevel, AccessMode
+
+boundary = Boundary(
+    agent_name="support-agent",
+    autonomy=AutonomyLevel.LIMITED_AUTONOMOUS,
+    permissions=[
+        ToolPermission("read_ticket_db", access_mode=AccessMode.READ_ONLY),
+        ToolPermission(
+            "send_reply_email",
+            access_mode=AccessMode.EXECUTE,
+            max_calls_per_hour=30,
+        ),
+    ],
+    blocked_operations=frozenset({"delete_ticket"}),
+    max_actions_per_hour=100,
+    kill_switch_env="TOOLBOUNDARY_KILL_SWITCH",
+)
+
+# Somewhere in your agent's tool-calling code:
+boundary.check("read_ticket_db", access_mode=AccessMode.READ_ONLY)   # passes silently
+boundary.check("delete_ticket", operation="delete_ticket")           # raises BoundaryViolation
+```
+
+If a call is denied, `boundary.check(...)` raises `BoundaryViolation` (or a more
+specific subclass like `KillSwitchActive` or `RateLimitExceeded`). If a call needs a
+human before it can proceed, it raises `ApprovalRequired`. Every decision — allow,
+deny, or approval-required — is written to a structured audit log automatically.
+
+### Emergency stop
+
+```bash
+export TOOLBOUNDARY_KILL_SWITCH=1
+```
+
+Set the environment variable your `Boundary` was configured with, and every future
+call for that agent is denied immediately — no restart required, no code change,
+no separate dashboard to log into.
+
+## Two ways to enforce the boundary
+
+### 1. Decorator (plain Python functions)
+
+```python
+from toolboundary import guarded_tool, AccessMode
+
+@guarded_tool(boundary, access_mode=AccessMode.EXECUTE, value_arg="amount")
+def wire_transfer(account_id: str, amount: float) -> str:
+    return f"transferred {amount} to {account_id}"
+
+wire_transfer(account_id="acct_1", amount=250_000)
+# raises BoundaryViolation if 250_000 exceeds the permission's max_value —
+# the function body never executes.
+```
+
+Once a function is decorated, calling it *is* calling through ToolBoundary. There is no
+code path to the real implementation that skips the check.
+
+### 2. LangChain tools
+
+```python
+from toolboundary.integrations.langchain import guard_tools
+from toolboundary import AccessMode
+
+guarded_tools = guard_tools(
+    [read_db_tool, send_email_tool, wire_transfer_tool],
+    boundary,
+    default_access_mode=AccessMode.READ_ONLY,
+    overrides={
+        "send_email_tool": {"access_mode": AccessMode.EXECUTE},
+        "wire_transfer_tool": {"access_mode": AccessMode.EXECUTE, "value_arg": "amount"},
+    },
+)
+
+agent_executor = AgentExecutor(agent=agent, tools=guarded_tools)
+```
+
+This wraps the LangChain `BaseTool` objects themselves — the objects your
+`AgentExecutor` actually invokes when the LLM decides to call a tool — so the boundary
+check runs inside LangChain's own tool-execution path, not as a step the agent's
+reasoning loop has to remember to call.
+
+Install with the LangChain extra: `pip install toolboundary[langchain]`
+
+## What a `Boundary` can enforce
+
+| Control | Example |
+|---|---|
+| Which tools an agent may use at all | `permissions=[ToolPermission("read_db", ...)]` |
+| Operation-level allow/block lists | `blocked_operations=frozenset({"delete_customer"})` |
+| Access mode (READ_ONLY / WRITE / EXECUTE / ADMIN) | `access_mode=AccessMode.EXECUTE` |
+| Transaction value ceilings | `ToolPermission(..., max_value=500_000)` |
+| Record-count ceilings | `ToolPermission(..., max_records=100)` |
+| Rate limits (global or per-tool) | `max_actions_per_hour=60` |
+| Autonomy level | `AutonomyLevel.RECOMMEND_ONLY` / `HUMAN_APPROVAL_REQUIRED` / `LIMITED_AUTONOMOUS` / `AUTONOMOUS` / `QUARANTINED` |
+| Time-bounded validity | `valid_from=`, `valid_to=` |
+| Environment restriction | `allowed_environments=frozenset({"DEV", "TEST"})` |
+| Emergency kill switch | in-process flag or environment variable |
+| Custom policy logic | `policy_hooks=[my_custom_check]` |
+
+Full field reference: see [`docs/API.md`](docs/API.md).
+
+## Audit trail
+
+Every decision produces a structured event. By default it goes to Python's standard
+`logging` module under the logger name `toolboundary.audit`, so it flows into whatever
+logging pipeline you already have (stdout, a file, CloudWatch, Datadog, etc.) with zero
+extra code.
+
+```python
+from toolboundary.audit import AuditTrail, JSONLFileSink
+
+boundary = Boundary(
+    agent_name="support-agent",
+    ...,
+    audit=AuditTrail(sinks=[JSONLFileSink("toolboundary-audit.jsonl")]),
+)
+```
+
+A `WebhookSink` is also included if you want to forward events to a self-hosted
+dashboard or a centralized governance platform. Audit delivery is always best-effort —
+a network hiccup in your audit pipeline can never block or crash your agent, because
+the ALLOW/DENY decision has already been enforced locally before the sink is invoked.
+
+## Design philosophy
+
+- **Fail closed.** Anything ambiguous, misconfigured, or erroring is treated as denied
+  by default. See `fail_closed_on_hook_error` for the one place this is configurable.
+- **No infrastructure required.** No database, no server, no login. The whole thing is
+  a Python object you construct alongside your agent code.
+- **Version-controlled policy.** Your boundary is code, reviewed in the same pull
+  requests as everything else — not a setting buried in a web UI that drifts silently
+  out of sync with what the agent actually does.
+- **Loud by default.** Denials raise exceptions, not silent `False` returns that are
+  easy to accidentally ignore.
+- **Framework-agnostic core, framework-specific adapters.** The core `Boundary` has
+  zero dependencies. Framework integrations (LangChain today; more welcome via PR) are
+  optional extras.
+
+## Known limitations — please read this
+
+ToolBoundary is an **in-process, application-layer** library. Being explicit about what
+it does *not* do is more important than what it does:
+
+- **It cannot stop an agent that bypasses it entirely.** If your agent's code has any
+  path that calls a tool's real implementation directly — instead of through a
+  `@guarded_tool`-wrapped function or a `guard_tool`-wrapped LangChain tool — that call
+  is not evaluated. ToolBoundary governs the doors you route through it; it is not a
+  network firewall.
+- **It is not a substitute for credential scoping.** If the underlying API key or
+  database credential your tool uses has broader permissions than ToolBoundary's policy
+  allows, a determined attacker who obtains that credential directly bypasses
+  ToolBoundary entirely. Scope your actual credentials as tightly as you can — ToolBoundary
+  is a second layer, not a replacement for the first.
+- **It is not a compliance/audit system of record for large organizations.** If you
+  have dozens of agents across multiple teams and need human governance workflows,
+  cross-team registries, and formal approval routing, look at enterprise AI governance
+  platforms — ToolBoundary is intentionally not trying to be that.
+- **The in-memory rate limiter is per-process.** If you run multiple replicas of your
+  agent, each process has its own rate-limit counters unless you supply a shared
+  backing store (see `Boundary`'s internals / open an issue if you need this — a
+  Redis-backed limiter is a natural community contribution).
+
+If your threat model requires guaranteeing that a compromised agent *physically
+cannot* reach a tool's network endpoint except through an approved path, you need a
+network-layer control (a sidecar proxy, egress firewall rule, or service mesh policy)
+in addition to ToolBoundary, not instead of it.
+
+## Installation
+
+```bash
+pip install toolboundary                # core, zero dependencies
+pip install toolboundary[langchain]     # + LangChain integration
+```
+
+## Contributing
+
+Issues and PRs are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+Ideas that would make great first contributions:
+- Redis-backed rate limiter for multi-process deployments
+- CrewAI / AutoGen / LangGraph integrations (mirroring `integrations/langchain.py`)
+- A minimal read-only local dashboard that tails a `JSONLFileSink` log
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).