toolbound 0.2.0__py3-none-any.whl

toolbound/core/pyschema.py

@@ -0,0 +1,119 @@
+"""Infer a JSON Schema from a Python handler's signature (for PythonTool)."""
+
+from __future__ import annotations
+
+import enum
+import inspect
+import json
+import types
+import typing
+from collections.abc import Callable, Iterable
+from typing import Any, Literal, Union, get_args, get_origin
+
+from .errors import ConfigurationError
+
+_SIMPLE: dict[type, dict[str, Any]] = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    bool: {"type": "boolean"},
+    # A bare ``dict`` hint is a deliberate free-form object: say so explicitly.
+    dict: {"type": "object", "additionalProperties": True},
+}
+
+
+def handler_parameters(fn: Callable[..., Any]) -> tuple[set[str], bool, bool]:
+    """Return (named parameters, accepts **kwargs, accepts ctx)."""
+    sig = inspect.signature(fn)
+    names: set[str] = set()
+    var_kw = False
+    for name, param in sig.parameters.items():
+        if param.kind is inspect.Parameter.VAR_KEYWORD:
+            var_kw = True
+        elif param.kind in (
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            names.add(name)
+    return names - {"ctx"}, var_kw, "ctx" in sig.parameters
+
+
+def infer_input_schema(fn: Callable[..., Any], *, exclude: Iterable[str] = ()) -> dict[str, Any]:
+    """Build an input schema from type hints. Raises ConfigurationError if unsupported."""
+    skip = set(exclude) | {"ctx"}
+    sig = inspect.signature(fn)
+    try:
+        hints = typing.get_type_hints(fn, include_extras=True)
+    except Exception as exc:
+        raise ConfigurationError(f"cannot read type hints of {fn!r}: {exc}") from exc
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for name, param in sig.parameters.items():
+        if name in skip or param.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            continue
+        if param.kind is inspect.Parameter.POSITIONAL_ONLY:
+            raise ConfigurationError(f"{fn.__name__}: positional-only parameters are not supported")
+        if name not in hints:
+            raise ConfigurationError(
+                f"{fn.__name__}: parameter {name!r} needs a type hint (or pass input= explicitly)"
+            )
+        schema = _schema_for(hints[name], fn.__name__, name)
+        if param.default is inspect.Parameter.empty:
+            required.append(name)
+        else:
+            try:
+                json.dumps(param.default)
+            except TypeError as exc:
+                raise ConfigurationError(
+                    f"{fn.__name__}: default of {name!r} is not JSON-serializable"
+                ) from exc
+            schema["default"] = param.default
+        properties[name] = schema
+    return {"type": "object", "properties": properties, "required": required}
+
+
+def _schema_for(tp: Any, fn: str, name: str) -> dict[str, Any]:
+    origin = get_origin(tp)
+    if origin is typing.Annotated:
+        base, *meta = get_args(tp)
+        schema = _schema_for(base, fn, name)
+        for item in meta:
+            if isinstance(item, str):
+                schema["description"] = item
+            elif isinstance(item, dict):
+                schema.update(item)
+        return schema
+    if tp in _SIMPLE:
+        return dict(_SIMPLE[tp])
+    if origin is Literal:
+        return {"enum": list(get_args(tp))}
+    if isinstance(tp, type) and issubclass(tp, enum.Enum):
+        return {"enum": [m.value for m in tp]}
+    if origin in (list, tuple, set, frozenset) or tp in (list, tuple):
+        args = get_args(tp)
+        array: dict[str, Any] = {"type": "array"}
+        if args and args[0] is not Ellipsis:
+            array["items"] = _schema_for(args[0], fn, name)
+        if origin in (set, frozenset):
+            array["uniqueItems"] = True
+        return array
+    if origin is dict:
+        args = get_args(tp)
+        values = _schema_for(args[1], fn, name) if len(args) == 2 else True
+        return {"type": "object", "additionalProperties": values}
+    if origin in (Union, types.UnionType):
+        members = [a for a in get_args(tp) if a is not type(None)]
+        nullable = len(members) != len(get_args(tp))
+        if len(members) == 1:
+            inner = _schema_for(members[0], fn, name)
+            return {"anyOf": [inner, {"type": "null"}]} if nullable else inner
+        options = [_schema_for(m, fn, name) for m in members]
+        if nullable:
+            options.append({"type": "null"})
+        return {"anyOf": options}
+    raise ConfigurationError(
+        f"{fn}: cannot infer a schema for parameter {name!r} ({tp!r}); pass input= explicitly"
+    )

toolbound/core/ratelimit.py

@@ -0,0 +1,65 @@
+"""In-memory sliding-window rate limiting (per process, thread-safe)."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from collections import deque
+
+from .context import ExecutionContext
+from .contracts import RateLimit
+from .errors import ErrorCode, ToolFailure
+
+_SWEEP_EVERY = 1024
+
+
+class RateLimiter:
+    """Sliding windows keyed by tool and actor/tenant.
+
+    Idle windows are removed, so memory stays proportional to the number of
+    recently active callers rather than growing forever.
+    """
+
+    def __init__(self) -> None:
+        self._windows: dict[str, tuple[float, deque[float]]] = {}
+        self._lock = threading.Lock()
+        self._checks = 0
+
+    def __len__(self) -> int:
+        return len(self._windows)
+
+    def check(self, tool: str, limit: RateLimit, ctx: ExecutionContext) -> None:
+        # JSON keeps None and "None" apart, and actors are qualified by tenant.
+        if limit.scope == "actor":
+            scope = "a:" + json.dumps([ctx.tenant, ctx.actor])
+        elif limit.scope == "tenant":
+            scope = "t:" + json.dumps(ctx.tenant)
+        else:
+            scope = "g"
+        key = f"{tool}|{scope}"
+        now = time.monotonic()
+        with self._lock:
+            self._checks += 1
+            if self._checks % _SWEEP_EVERY == 0:
+                self._sweep(now)
+            entry = self._windows.get(key)
+            window = entry[1] if entry is not None else deque()
+            while window and window[0] <= now - limit.per_seconds:
+                window.popleft()
+            if len(window) >= limit.calls:
+                retry_after = max(0.0, window[0] + limit.per_seconds - now)
+                raise ToolFailure(
+                    ErrorCode.RATE_LIMITED,
+                    f"rate limit reached for this tool ({limit.calls} calls per "
+                    f"{limit.per_seconds:g}s)",
+                    retry_after=retry_after,
+                    request_sent=False,
+                )
+            window.append(now)
+            self._windows[key] = (limit.per_seconds, window)
+
+    def _sweep(self, now: float) -> None:
+        idle = [k for k, (period, w) in self._windows.items() if not w or w[-1] <= now - period]
+        for key in idle:
+            del self._windows[key]

toolbound/core/result.py

@@ -0,0 +1,100 @@
+"""Tool results.
+
+A :class:`ToolResult` has two audiences:
+
+* **Host code** can read every attribute, including ``approval`` (a
+  :class:`PendingApproval` to show a human) and diagnostics such as
+  ``http_status`` and ``duration_ms``.
+* **The model** only ever receives :meth:`ToolResult.to_model` (or
+  :meth:`ToolResult.to_json`): the shaped data, transparent metadata about what
+  was left out, and a safe error message.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .approval import PendingApproval
+from .budget import to_json
+from .errors import ErrorCode
+from .shaping import Omission
+
+
+@dataclass(frozen=True, slots=True)
+class ToolError:
+    code: ErrorCode
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+    retry_after: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"code": self.code.value, "message": self.message}
+        if self.retryable:
+            out["retryable"] = True
+        if self.retry_after is not None:
+            out["retry_after_seconds"] = round(self.retry_after, 1)
+        out.update(self.details)
+        return out
+
+
+@dataclass(frozen=True, slots=True)
+class ResultMeta:
+    truncated: bool = False
+    omitted: tuple[Omission, ...] = ()
+    redacted: int = 0
+    warnings: tuple[str, ...] = ()
+    next_cursor: str | None = None
+    items_returned: int | None = None
+    items_total: int | None = None
+    estimated_tokens: int | None = None
+    source: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"truncated": self.truncated}
+        if self.omitted:
+            out["omitted"] = [o.to_dict() for o in self.omitted]
+        if self.redacted:
+            out["redacted"] = self.redacted
+        if self.warnings:
+            out["warnings"] = list(self.warnings)
+        if self.items_returned is not None:
+            out["items_returned"] = self.items_returned
+        if self.items_total is not None:
+            out["items_in_upstream_page"] = self.items_total
+        if self.next_cursor is not None:
+            out["next_cursor"] = self.next_cursor
+        if self.source:
+            out["source"] = self.source
+        return out
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResult:
+    """Outcome of one tool call."""
+
+    ok: bool
+    tool: str
+    data: Any = None
+    meta: ResultMeta = field(default_factory=ResultMeta)
+    error: ToolError | None = None
+    approval: PendingApproval | None = None
+    http_status: int | None = None
+    duration_ms: float | None = None
+    call_id: str | None = None
+
+    def to_model(self) -> dict[str, Any]:
+        """The model-visible envelope. Contains no credentials or host-only data."""
+        if self.ok:
+            return {"ok": True, "data": self.data, "meta": self.meta.to_dict()}
+        assert self.error is not None
+        return {"ok": False, "error": self.error.to_dict()}
+
+    def to_json(self) -> str:
+        """Compact JSON of :meth:`to_model`, ready for a tool-result message."""
+        return to_json(self.to_model())
+
+    @property
+    def needs_approval(self) -> bool:
+        return self.approval is not None

toolbound/core/schema.py

@@ -0,0 +1,201 @@
+"""Input schema normalization and validation (structural validation only).
+
+Structural validation proves that arguments have the expected shape. It says
+nothing about whether the caller may act (authorization) or whether data is
+true (factual verification).
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import warnings
+from collections.abc import Mapping
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import SchemaError, ValidationError
+
+from .errors import ConfigurationError, ErrorCode, ToolboundWarning, ToolFailure
+
+_CHECKED_FORMATS = frozenset(FormatChecker().checkers)
+
+_MAX_SCHEMA_DEPTH = 16
+_MAX_SCHEMA_BYTES = 64 * 1024
+_MAX_MESSAGE = 240
+
+RESERVED_ARGUMENTS = frozenset({"fields", "cursor"})
+
+
+def normalize_input_schema(tool_name: str, spec: Mapping[str, Any]) -> dict[str, Any]:
+    """Turn a developer input spec into a closed, checked JSON Schema object.
+
+    ``spec`` is either a full JSON Schema with ``"type": "object"`` or a
+    shorthand mapping of property name to property schema. In shorthand, every
+    property without a ``default`` is required.
+    """
+    raw: dict[str, Any] = copy.deepcopy(dict(spec))
+    schema: dict[str, Any]
+    if "type" in raw:
+        if raw.get("type") != "object":
+            raise ConfigurationError(f"tool {tool_name}: input schema must be type 'object'")
+        schema = raw
+        schema.setdefault("properties", {})
+    else:
+        required = [k for k, v in raw.items() if not (isinstance(v, Mapping) and "default" in v)]
+        schema = {"type": "object", "properties": raw, "required": required}
+
+    if schema.get("additionalProperties", False) is not False:
+        raise ConfigurationError(
+            f"tool {tool_name}: top-level additionalProperties must be false; unknown "
+            "arguments are always rejected"
+        )
+    schema["additionalProperties"] = False
+    _close_nested_objects(schema, depth=0, tool_name=tool_name)
+    _reject_remote_refs(schema, tool_name)
+    try:
+        Draft202012Validator.check_schema(schema)
+    except SchemaError as exc:
+        raise ConfigurationError(f"tool {tool_name}: invalid input schema: {exc.message}") from exc
+    if len(json.dumps(schema)) > _MAX_SCHEMA_BYTES:
+        raise ConfigurationError(f"tool {tool_name}: input schema is too large")
+    unchecked = sorted(_formats(schema) - _CHECKED_FORMATS)
+    if unchecked:
+        warnings.warn(
+            f"tool {tool_name}: JSON Schema format(s) {unchecked} are not enforced in this "
+            "environment (jsonschema needs optional packages for them). Use 'pattern', "
+            "'enum' or limits for anything security-relevant.",
+            ToolboundWarning,
+            stacklevel=4,
+        )
+    return schema
+
+
+def _formats(node: Any) -> set[str]:
+    found: set[str] = set()
+    if isinstance(node, dict):
+        value = node.get("format")
+        if isinstance(value, str):
+            found.add(value)
+        for child in node.values():
+            found |= _formats(child)
+    elif isinstance(node, list):
+        for child in node:
+            found |= _formats(child)
+    return found
+
+
+def _close_nested_objects(node: Any, *, depth: int, tool_name: str, where: str = "") -> None:
+    """Close every nested object schema that lists ``properties``.
+
+    Unknown keys are rejected unless the contract sets ``additionalProperties``
+    explicitly. A schema counts as an object schema when it has ``properties``,
+    whatever its ``type`` says (``["object", "null"]``, or no ``type`` at all). An
+    object schema *without* ``properties`` and without an explicit
+    ``additionalProperties`` accepts any keys; that is allowed but warned about.
+    """
+    if depth > _MAX_SCHEMA_DEPTH:
+        raise ConfigurationError(f"tool {tool_name}: input schema nests too deeply")
+    if isinstance(node, dict):
+        if depth > 0 and _is_object_schema(node):
+            if "properties" in node:
+                node.setdefault("additionalProperties", False)
+            elif "additionalProperties" not in node and "patternProperties" not in node:
+                warnings.warn(
+                    f"tool {tool_name}: object at {where or '$'} accepts any keys. Add "
+                    "'properties' (unknown keys are then rejected) or set "
+                    "'additionalProperties' explicitly.",
+                    ToolboundWarning,
+                    stacklevel=5,
+                )
+        for key, value in node.items():
+            if key in ("properties", "$defs", "definitions", "patternProperties"):
+                if isinstance(value, dict):
+                    for name, sub in value.items():
+                        _close_nested_objects(
+                            sub, depth=depth + 1, tool_name=tool_name, where=f"{where}.{name}"
+                        )
+            elif isinstance(value, dict | list):
+                _close_nested_objects(value, depth=depth + 1, tool_name=tool_name, where=where)
+    elif isinstance(node, list):
+        for item in node:
+            _close_nested_objects(item, depth=depth + 1, tool_name=tool_name, where=where)
+
+
+def _is_object_schema(node: dict[str, Any]) -> bool:
+    kind = node.get("type")
+    if "properties" in node:
+        return True
+    return kind == "object" or (isinstance(kind, list) and "object" in kind)
+
+
+def _reject_remote_refs(node: Any, tool_name: str) -> None:
+    if isinstance(node, dict):
+        for key, value in node.items():
+            if key in ("$ref", "$dynamicRef") and not (
+                isinstance(value, str) and value.startswith("#")
+            ):
+                raise ConfigurationError(f"tool {tool_name}: only local '#/...' $ref is allowed")
+            if key == "$id":
+                raise ConfigurationError(f"tool {tool_name}: $id is not allowed in input schemas")
+            _reject_remote_refs(value, tool_name)
+    elif isinstance(node, list):
+        for item in node:
+            _reject_remote_refs(item, tool_name)
+
+
+class ArgumentValidator:
+    """Compiled validator for one tool's arguments."""
+
+    def __init__(self, schema: dict[str, Any], *, max_argument_bytes: int) -> None:
+        self.schema = schema
+        self._validator = Draft202012Validator(schema, format_checker=FormatChecker())
+        self._defaults = {
+            name: prop["default"]
+            for name, prop in schema.get("properties", {}).items()
+            if isinstance(prop, dict) and "default" in prop
+        }
+        self._max_bytes = max_argument_bytes
+
+    def validate(self, arguments: Any) -> dict[str, Any]:
+        """Return validated arguments (with top-level defaults) or raise ToolFailure."""
+        if not isinstance(arguments, dict):
+            raise ToolFailure(ErrorCode.INVALID_ARGUMENTS, "arguments must be a JSON object")
+        try:
+            size = len(json.dumps(arguments, ensure_ascii=False).encode())
+        except (TypeError, ValueError) as exc:
+            raise ToolFailure(
+                ErrorCode.INVALID_ARGUMENTS, "arguments must be JSON-serializable"
+            ) from exc
+        if size > self._max_bytes:
+            raise ToolFailure(
+                ErrorCode.INVALID_ARGUMENTS,
+                f"arguments are too large ({size} bytes, limit {self._max_bytes})",
+            )
+        errors = sorted(self._validator.iter_errors(arguments), key=_error_sort_key)
+        if errors:
+            raise ToolFailure(
+                ErrorCode.INVALID_ARGUMENTS,
+                "; ".join(_describe(e) for e in errors[:3]),
+                details={"allowed_arguments": sorted(self.schema.get("properties", {}))},
+            )
+        result = dict(arguments)
+        for name, value in self._defaults.items():
+            result.setdefault(name, copy.deepcopy(value))
+        return result
+
+
+def _error_sort_key(error: ValidationError) -> tuple[int, str]:
+    return (len(error.absolute_path), str(list(error.absolute_path)))
+
+
+def _describe(error: ValidationError) -> str:
+    location = ".".join(str(p) for p in error.absolute_path) or "arguments"
+    if error.validator == "additionalProperties":
+        props = error.schema.get("properties", {}) if isinstance(error.schema, dict) else {}
+        extra = sorted(set(error.instance) - set(props)) if isinstance(error.instance, dict) else []
+        message = f"unknown argument(s) {extra}" if extra else error.message
+    else:
+        message = error.message
+    text = f"{location}: {message}"
+    return text if len(text) <= _MAX_MESSAGE else text[: _MAX_MESSAGE - 1] + "…"