toolbound 0.2.0__py3-none-any.whl

toolbound/core/credentials.py

@@ -0,0 +1,41 @@
+"""Credential providers. Secrets stay in trusted code and never reach the model."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from .context import ExecutionContext
+
+
+class EnvCredentials:
+    """Read credentials from environment variables.
+
+    ``EnvCredentials({"github_token": "GITHUB_TOKEN"})`` maps names explicitly.
+    With no mapping, the name is upper-cased (``github_token`` -> ``GITHUB_TOKEN``),
+    optionally with a ``prefix``.
+    """
+
+    def __init__(self, mapping: Mapping[str, str] | None = None, *, prefix: str = "") -> None:
+        self._mapping = dict(mapping or {})
+        self._prefix = prefix
+
+    def get(self, name: str, ctx: ExecutionContext) -> str | None:
+        var = self._mapping.get(name) or (self._prefix + name.upper().replace(".", "_"))
+        return os.environ.get(var) or None
+
+    def __repr__(self) -> str:
+        return f"EnvCredentials(names={sorted(self._mapping)!r}, prefix={self._prefix!r})"
+
+
+class StaticCredentials:
+    """Credentials from an in-memory mapping (tests, or values from your vault)."""
+
+    def __init__(self, values: Mapping[str, str]) -> None:
+        self._values = dict(values)
+
+    def get(self, name: str, ctx: ExecutionContext) -> str | None:
+        return self._values.get(name)
+
+    def __repr__(self) -> str:  # never print secret values
+        return f"StaticCredentials(names={sorted(self._values)!r})"

toolbound/core/errors.py

@@ -0,0 +1,117 @@
+"""Error types.
+
+Two kinds of failure exist in Toolbound:
+
+* **Developer errors** (an invalid contract, a missing policy) raise
+  :class:`ConfigurationError` at registration time, so mistakes surface while
+  the application starts rather than in front of a model.
+* **Runtime failures** (invalid arguments, denied authorization, a blocked
+  network target, an upstream error) never raise from :meth:`Gateway.call`.
+  They are returned as a :class:`~toolbound.ToolResult` with ``ok=False`` and an
+  :class:`ErrorCode`, so the agent loop can hand a safe, structured error back
+  to the model.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ToolboundError(Exception):
+    """Base class for every exception raised by Toolbound."""
+
+
+class ToolboundWarning(UserWarning):
+    """A risky but legal configuration (for example an ephemeral signing key).
+
+    Turn these into errors in CI with ``-W error::toolbound.ToolboundWarning``.
+    """
+
+
+class StateStoreError(ToolboundError):
+    """A :class:`~toolbound.StateStore` could not record a claim.
+
+    Toolbound fails closed: the call is not executed.
+    """
+
+
+class ConfigurationError(ToolboundError):
+    """A contract, tool, or gateway setting is invalid. Raised to the developer."""
+
+
+class ErrorCode(StrEnum):
+    """Stable, machine-readable codes for failed tool calls."""
+
+    UNKNOWN_TOOL = "unknown_tool"
+    INVALID_ARGUMENTS = "invalid_arguments"
+    INVALID_CURSOR = "invalid_cursor"
+    FORBIDDEN = "forbidden"
+    APPROVAL_REQUIRED = "approval_required"
+    APPROVAL_DENIED = "approval_denied"
+    APPROVAL_INVALID = "approval_invalid"
+    DUPLICATE_CALL = "duplicate_call"
+    RATE_LIMITED = "rate_limited"
+    NETWORK_BLOCKED = "network_blocked"
+    TIMEOUT = "timeout"
+    UPSTREAM_UNAVAILABLE = "upstream_unavailable"
+    UPSTREAM_ERROR = "upstream_error"
+    UPSTREAM_SCHEMA_MISMATCH = "upstream_schema_mismatch"
+    UNSUPPORTED_CONTENT_TYPE = "unsupported_content_type"
+    RESPONSE_TOO_LARGE = "response_too_large"
+    RESULT_TOO_LARGE = "result_too_large"
+    OUTCOME_UNKNOWN = "outcome_unknown"
+    INTERNAL_ERROR = "internal_error"
+
+
+#: Codes where repeating the same call later may succeed.
+RETRYABLE_CODES = frozenset(
+    {ErrorCode.RATE_LIMITED, ErrorCode.TIMEOUT, ErrorCode.UPSTREAM_UNAVAILABLE}
+)
+
+
+class ToolFailure(ToolboundError):
+    """Internal signal used to stop the pipeline with a model-safe error.
+
+    The ``message`` must never contain secrets, credentials, raw upstream bodies,
+    or stack traces: it is shown to the model.
+    """
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: str,
+        *,
+        retryable: bool | None = None,
+        http_status: int | None = None,
+        details: dict[str, object] | None = None,
+        retry_after: float | None = None,
+        request_sent: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.retryable = code in RETRYABLE_CODES if retryable is None else retryable
+        self.http_status = http_status
+        self.details = details or {}
+        self.retry_after = retry_after
+        #: ``False`` when the request certainly never reached the upstream (DNS,
+        #: connect, policy). ``None`` means it may have been sent.
+        self.request_sent = request_sent
+
+
+class NetworkBlocked(ToolFailure):
+    """A request target violated the network policy."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(ErrorCode.NETWORK_BLOCKED, message, retryable=False, request_sent=False)
+
+
+class ApprovalInvalid(ToolFailure):
+    """An approval request or grant is forged, expired, reused, or for another call.
+
+    Raised by :meth:`Gateway.grant` (host code); :meth:`Gateway.call` returns it
+    as an ``approval_invalid`` result instead.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(ErrorCode.APPROVAL_INVALID, message, retryable=False)

toolbound/core/exposure.py

@@ -0,0 +1,68 @@
+"""Model-visible tool definitions, independent of any provider format."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+Strategy = Literal["direct", "grouped"]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolDefinition:
+    """Name, description and JSON Schema: everything a model is allowed to see."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": copy.deepcopy(self.input_schema),
+        }
+
+
+def _summarize(schema: dict[str, Any]) -> str:
+    """Compact one-line argument summary, e.g. ``id: string*, limit: integer 1..100``."""
+    required = set(schema.get("required", []))
+    parts = []
+    for name, prop in schema.get("properties", {}).items():
+        if not isinstance(prop, dict):
+            continue
+        if "enum" in prop:
+            kind = "|".join(str(v) for v in prop["enum"])
+        elif "const" in prop:
+            kind = f"={prop['const']}"
+        else:
+            kind = str(prop.get("type", "any"))
+            if "minimum" in prop or "maximum" in prop:
+                kind += f" {prop.get('minimum', '')}..{prop.get('maximum', '')}"
+        parts.append(f"{name}: {kind}{'*' if name in required else ''}")
+    return ", ".join(parts) or "none"
+
+
+def group_definitions(group: str, members: Sequence[ToolDefinition]) -> ToolDefinition:
+    """Combine several tools into one compact, ``action``-dispatched definition.
+
+    The model-facing schema for ``arguments`` is a plain object; each action's
+    arguments are summarized in the description (``*`` marks required). The full
+    per-action schema is still enforced by the gateway after dispatch.
+    """
+    lines = [f"Actions on {group}. Set `action`; put its arguments in `arguments` (* = required)."]
+    for d in members:
+        lines.append(f"- {d.name}: {d.description.strip()} Args: {_summarize(d.input_schema)}")
+    description = "\n".join(lines)
+    schema = {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string", "enum": [d.name for d in members]},
+            "arguments": {"type": "object"},
+        },
+        "required": ["action", "arguments"],
+        "additionalProperties": False,
+    }
+    return ToolDefinition(group, description, schema)