toolbound 0.2.0__py3-none-any.whl

toolbound/__init__.py

@@ -0,0 +1,123 @@
+"""Toolbound: contract-first, secure-by-default tools for AI agents."""
+
+from toolbound.core.approval import PendingApproval
+from toolbound.core.budget import ByteEstimator
+from toolbound.core.context import ExecutionContext
+from toolbound.core.contracts import (
+    ApiKeyAuth,
+    BasicAuth,
+    BearerAuth,
+    Const,
+    Effect,
+    Field,
+    FromContext,
+    Limits,
+    NetworkPolicy,
+    NoAuth,
+    Operation,
+    Output,
+    Pagination,
+    PythonTool,
+    RateLimit,
+    RetryPolicy,
+    Service,
+    Tool,
+    ToolSpec,
+    from_ctx,
+)
+from toolbound.core.credentials import EnvCredentials, StaticCredentials
+from toolbound.core.errors import (
+    ApprovalInvalid,
+    ConfigurationError,
+    ErrorCode,
+    NetworkBlocked,
+    StateStoreError,
+    ToolboundError,
+    ToolboundWarning,
+    ToolFailure,
+)
+from toolbound.core.exposure import ToolDefinition
+from toolbound.core.gateway import Gateway, allow_all, deny_all
+from toolbound.core.observe import Event, LoggingObserver
+from toolbound.core.ports import (
+    AuthorizationRequest,
+    Decision,
+    HttpRequest,
+    HttpResponse,
+    StateStore,
+    TokenEstimator,
+    Transport,
+)
+from toolbound.core.result import ResultMeta, ToolError, ToolResult
+from toolbound.core.shaping import Omission
+from toolbound.core.state import MemoryStateStore
+from toolbound.transport.mock import MockResponse, MockTransport
+
+__version__ = "0.2.0"
+
+
+def __getattr__(name: str) -> object:
+    if name == "SecureTransport":
+        from toolbound.transport.http import SecureTransport
+
+        return SecureTransport
+    raise AttributeError(name)
+
+
+__all__ = [
+    "ApiKeyAuth",
+    "ApprovalInvalid",
+    "AuthorizationRequest",
+    "BasicAuth",
+    "BearerAuth",
+    "ByteEstimator",
+    "ConfigurationError",
+    "Const",
+    "Decision",
+    "Effect",
+    "EnvCredentials",
+    "ErrorCode",
+    "Event",
+    "ExecutionContext",
+    "Field",
+    "FromContext",
+    "Gateway",
+    "HttpRequest",
+    "HttpResponse",
+    "Limits",
+    "LoggingObserver",
+    "MemoryStateStore",
+    "MockResponse",
+    "MockTransport",
+    "NetworkBlocked",
+    "NetworkPolicy",
+    "NoAuth",
+    "Omission",
+    "Operation",
+    "Output",
+    "Pagination",
+    "PendingApproval",
+    "PythonTool",
+    "RateLimit",
+    "ResultMeta",
+    "RetryPolicy",
+    "SecureTransport",
+    "Service",
+    "StateStore",
+    "StateStoreError",
+    "StaticCredentials",
+    "TokenEstimator",
+    "Tool",
+    "ToolDefinition",
+    "ToolError",
+    "ToolFailure",
+    "ToolResult",
+    "ToolSpec",
+    "ToolboundError",
+    "ToolboundWarning",
+    "Transport",
+    "__version__",
+    "allow_all",
+    "deny_all",
+    "from_ctx",
+]

toolbound/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Optional provider adapters.
+
+Each adapter converts Toolbound definitions to a provider's tool format and runs
+the provider's tool calls through the Gateway. None of them import a provider
+SDK, and none contain security logic: everything is enforced by the core.
+
+* :mod:`toolbound.adapters.anthropic` - Anthropic Messages API
+* :mod:`toolbound.adapters.openai` - OpenAI Chat Completions and Responses APIs
+"""

toolbound/adapters/_common.py

@@ -0,0 +1,84 @@
+"""Shared helpers for provider adapters (no third-party imports)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from toolbound.core.approval import PendingApproval
+from toolbound.core.context import ExecutionContext
+from toolbound.core.errors import ErrorCode
+from toolbound.core.gateway import Gateway
+from toolbound.core.result import ToolError, ToolResult
+
+
+def get(obj: Any, key: str, default: Any = None) -> Any:
+    """Read ``key`` from a dict or an SDK object."""
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)
+
+
+def optional_id(value: Any) -> str | None:
+    """A provider tool-call id, or None when missing (never the string "None",
+    which would make every id-less call look like a duplicate of the first)."""
+    return None if value is None or value == "" else str(value)
+
+
+@dataclass(slots=True)
+class Call:
+    id: str | None
+    name: str
+    arguments: Any
+    parse_error: str | None = None
+
+
+def parse_json_arguments(raw: Any) -> tuple[Any, str | None]:
+    if isinstance(raw, dict):
+        return raw, None
+    if raw is None or raw == "":
+        return {}, None
+    if isinstance(raw, str):
+        try:
+            return json.loads(raw), None
+        except ValueError:
+            return None, "tool arguments were not valid JSON"
+    return None, "tool arguments must be a JSON object"
+
+
+@dataclass(slots=True)
+class ToolCallBatch:
+    """Results of executing one model turn's tool calls.
+
+    ``messages`` (or ``blocks``) are ready to append to the conversation.
+    ``results`` holds the full :class:`ToolResult` objects for host code, and
+    ``pending_approvals`` lists calls waiting for a human decision.
+    """
+
+    results: list[ToolResult] = field(default_factory=list)
+    blocks: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def pending_approvals(self) -> list[PendingApproval]:
+        return [r.approval for r in self.results if r.approval is not None]
+
+
+async def execute_calls(
+    gateway: Gateway, calls: Sequence[Call], ctx: ExecutionContext, *, parallel: bool
+) -> list[ToolResult]:
+    async def one(call: Call) -> ToolResult:
+        if call.parse_error is not None:
+            return ToolResult(
+                ok=False,
+                tool=call.name,
+                error=ToolError(ErrorCode.INVALID_ARGUMENTS, call.parse_error),
+                call_id=call.id,
+            )
+        return await gateway.call(call.name, call.arguments, ctx=ctx, call_id=call.id)
+
+    if parallel:
+        return list(await asyncio.gather(*(one(c) for c in calls)))
+    return [await one(c) for c in calls]

toolbound/adapters/anthropic.py

@@ -0,0 +1,81 @@
+"""Anthropic Messages API adapter. Does not import the ``anthropic`` package.
+
+```python
+from toolbound.adapters import anthropic as tb
+
+tools = tb.tools(gateway, ctx)
+response = client.messages.create(model=..., tools=tools, messages=messages, max_tokens=...)
+batch = await tb.run_tool_calls(gateway, response, ctx)
+messages.append({"role": "assistant", "content": response.content})
+messages.append(batch.message)
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from toolbound.core.context import ExecutionContext
+from toolbound.core.exposure import Strategy
+from toolbound.core.gateway import Gateway
+
+from ._common import Call, ToolCallBatch, execute_calls, get, optional_id, parse_json_arguments
+
+__all__ = ["AnthropicToolCallBatch", "run_tool_calls", "tool_calls", "tools"]
+
+
+def tools(
+    gateway: Gateway,
+    ctx: ExecutionContext,
+    *,
+    tags: Iterable[str] | None = None,
+    names: Iterable[str] | None = None,
+    strategy: Strategy = "direct",
+) -> list[dict[str, Any]]:
+    """Tool definitions in Anthropic format, filtered for ``ctx``."""
+    return [
+        {"name": d.name, "description": d.description, "input_schema": d.input_schema}
+        for d in gateway.definitions(ctx, tags=tags, names=names, strategy=strategy)
+    ]
+
+
+def tool_calls(message: Any) -> list[Call]:
+    """Extract ``tool_use`` blocks from a Message, a content list, or dicts."""
+    content = get(message, "content", message)
+    calls: list[Call] = []
+    for block in content or []:
+        if get(block, "type") != "tool_use":
+            continue
+        arguments, error = parse_json_arguments(get(block, "input"))
+        calls.append(Call(optional_id(get(block, "id")), str(get(block, "name")), arguments, error))
+    return calls
+
+
+class AnthropicToolCallBatch(ToolCallBatch):
+    @property
+    def message(self) -> dict[str, Any]:
+        """A ``user`` message containing every ``tool_result`` block."""
+        return {"role": "user", "content": list(self.blocks)}
+
+
+async def run_tool_calls(
+    gateway: Gateway, message: Any, ctx: ExecutionContext, *, parallel: bool = False
+) -> AnthropicToolCallBatch:
+    """Execute every ``tool_use`` block and build matching ``tool_result`` blocks.
+
+    All results belong in a single user message (see :attr:`message`).
+    """
+    calls = tool_calls(message)
+    results = await execute_calls(gateway, calls, ctx, parallel=parallel)
+    batch = AnthropicToolCallBatch(results=results)
+    for call, result in zip(calls, results, strict=True):
+        block: dict[str, Any] = {
+            "type": "tool_result",
+            "tool_use_id": call.id,
+            "content": result.to_json(),
+        }
+        if not result.ok:
+            block["is_error"] = True
+        batch.blocks.append(block)
+    return batch

toolbound/adapters/openai.py

@@ -0,0 +1,115 @@
+"""OpenAI adapter (Chat Completions and Responses APIs). Does not import ``openai``.
+
+```python
+from toolbound.adapters import openai as tb
+
+# Chat Completions
+tools = tb.tools(gateway, ctx)
+completion = client.chat.completions.create(model=..., messages=messages, tools=tools)
+message = completion.choices[0].message
+batch = await tb.run_tool_calls(gateway, message, ctx)
+messages.append(message)
+messages.extend(batch.blocks)          # role="tool" messages
+
+# Responses API
+tools = tb.tools(gateway, ctx, api="responses")
+response = client.responses.create(model=..., input=items, tools=tools)
+batch = await tb.run_tool_calls(gateway, response, ctx)
+items.extend(response.output)
+items.extend(batch.blocks)             # function_call_output items
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Literal
+
+from toolbound.core.context import ExecutionContext
+from toolbound.core.exposure import Strategy
+from toolbound.core.gateway import Gateway
+
+from ._common import Call, ToolCallBatch, execute_calls, get, optional_id, parse_json_arguments
+
+__all__ = ["run_tool_calls", "tool_calls", "tools"]
+
+Api = Literal["chat", "responses"]
+
+
+def tools(
+    gateway: Gateway,
+    ctx: ExecutionContext,
+    *,
+    api: Api = "chat",
+    tags: Iterable[str] | None = None,
+    names: Iterable[str] | None = None,
+    strategy: Strategy = "direct",
+) -> list[dict[str, Any]]:
+    """Function-tool definitions for Chat Completions (default) or Responses."""
+    out: list[dict[str, Any]] = []
+    for d in gateway.definitions(ctx, tags=tags, names=names, strategy=strategy):
+        if api == "responses":
+            out.append(
+                {
+                    "type": "function",
+                    "name": d.name,
+                    "description": d.description,
+                    "parameters": d.input_schema,
+                }
+            )
+        else:
+            out.append(
+                {
+                    "type": "function",
+                    "function": {
+                        "name": d.name,
+                        "description": d.description,
+                        "parameters": d.input_schema,
+                    },
+                }
+            )
+    return out
+
+
+def tool_calls(obj: Any) -> tuple[list[Call], Api]:
+    """Extract calls from a chat message/completion or a Responses API response."""
+    output = get(obj, "output")
+    if isinstance(output, list):
+        calls = []
+        for item in output:
+            if get(item, "type") != "function_call":
+                continue
+            arguments, error = parse_json_arguments(get(item, "arguments"))
+            calls.append(
+                Call(optional_id(get(item, "call_id")), str(get(item, "name")), arguments, error)
+            )
+        return calls, "responses"
+    choices = get(obj, "choices")
+    message = get(choices[0], "message") if choices else obj
+    calls = []
+    for item in get(message, "tool_calls") or []:
+        function = get(item, "function")
+        arguments, error = parse_json_arguments(get(function, "arguments"))
+        calls.append(
+            Call(optional_id(get(item, "id")), str(get(function, "name")), arguments, error)
+        )
+    return calls, "chat"
+
+
+async def run_tool_calls(
+    gateway: Gateway, obj: Any, ctx: ExecutionContext, *, parallel: bool = False
+) -> ToolCallBatch:
+    """Execute every function call and build the matching result items."""
+    calls, api = tool_calls(obj)
+    results = await execute_calls(gateway, calls, ctx, parallel=parallel)
+    batch = ToolCallBatch(results=results)
+    for call, result in zip(calls, results, strict=True):
+        if api == "responses":
+            batch.blocks.append(
+                {"type": "function_call_output", "call_id": call.id, "output": result.to_json()}
+            )
+        else:
+            batch.blocks.append(
+                {"role": "tool", "tool_call_id": call.id, "content": result.to_json()}
+            )
+    return batch

toolbound/cli.py

@@ -0,0 +1,69 @@
+"""``toolbound`` command line: validate contracts and preview tool definitions."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from toolbound.core.budget import ByteEstimator
+from toolbound.core.context import ExecutionContext
+from toolbound.core.errors import ConfigurationError
+from toolbound.core.gateway import Gateway, allow_all
+from toolbound.loaders import CONTRACT_SCHEMA
+
+
+def _gateway(path: str) -> Gateway:
+    return Gateway(authorize=allow_all).load(path)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="toolbound", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    validate = sub.add_parser("validate", help="validate contract files")
+    validate.add_argument("path")
+    show = sub.add_parser("tools", help="print model-visible tool definitions")
+    show.add_argument("path")
+    show.add_argument("--format", choices=["anthropic", "openai", "neutral"], default="neutral")
+    show.add_argument("--strategy", choices=["direct", "grouped"], default="direct")
+    show.add_argument(
+        "--scope",
+        action="append",
+        default=[],
+        help="treat the viewer as having this scope (repeatable)",
+    )
+    sub.add_parser("schema", help="print the JSON Schema of contract files")
+    args = parser.parse_args(argv)
+
+    if args.command == "schema":
+        print(json.dumps(CONTRACT_SCHEMA, indent=2))
+        return 0
+    try:
+        gateway = _gateway(args.path)
+    except (ConfigurationError, OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if args.command == "validate":
+        print(f"ok: {len(gateway.tool_names)} tool(s): {', '.join(gateway.tool_names)}")
+        return 0
+    ctx = ExecutionContext(actor="cli", scopes=frozenset(args.scope))
+    if args.format == "anthropic":
+        from toolbound.adapters import anthropic
+
+        payload: object = anthropic.tools(gateway, ctx, strategy=args.strategy)
+    elif args.format == "openai":
+        from toolbound.adapters import openai
+
+        payload = openai.tools(gateway, ctx, strategy=args.strategy)
+    else:
+        payload = [d.to_dict() for d in gateway.definitions(ctx, strategy=args.strategy)]
+    text = json.dumps(payload, indent=2, ensure_ascii=False)
+    print(text)
+    compact = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+    print(f"# ~{ByteEstimator().count(compact)} tokens (byte estimate)", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

toolbound/core/__init__.py

@@ -0,0 +1,4 @@
+"""Framework-neutral core. Imports nothing from HTTP clients or AI frameworks.
+
+An architecture test (``tests/test_architecture.py``) enforces this.
+"""