composio-typesafe 0.22.0__py3-none-any.whl

composio_typesafe/__init__.py

@@ -0,0 +1,99 @@
+from composio_typesafe.decide import (
+    DEFAULT_MODEL,
+    DEFAULT_THRESHOLDS,
+    DESTRUCTIVE_ROUTING_THRESHOLD,
+    MAX_TOOLS,
+    REQUEST_BUDGET_TOKENS,
+)
+from composio_typesafe.provider import TypesafeProvider
+from composio_typesafe.types import (
+    TypesafeAbstainDecision,
+    TypesafeAbstainedDecisionError,
+    TypesafeApiError,
+    TypesafeApiErrorReason,
+    TypesafeArgumentQuestion,
+    TypesafeArrayArgument,
+    TypesafeBypassInfo,
+    TypesafeCallDecision,
+    TypesafeCandidate,
+    TypesafeChoiceArgument,
+    TypesafeChoiceQuestion,
+    TypesafeClientLike,
+    TypesafeConfirmationRequiredError,
+    TypesafeContextScope,
+    TypesafeDecision,
+    TypesafeDecisionMeta,
+    TypesafeDuplicateToolError,
+    TypesafeGateBlockedError,
+    TypesafeGateContext,
+    TypesafeGateUnavailableError,
+    TypesafeGateVetoError,
+    TypesafeIncompleteDecisionError,
+    TypesafeInvalidOptionsError,
+    TypesafeJudgement,
+    TypesafeLimitError,
+    TypesafeMalformedDecisionError,
+    TypesafeMalformedResponseError,
+    TypesafeMissingApiKeyError,
+    TypesafeNoulQuestion,
+    TypesafeOption,
+    TypesafePartialDecision,
+    TypesafeProviderError,
+    TypesafeQuestion,
+    TypesafeRequestState,
+    TypesafeShortlist,
+    TypesafeState,
+    TypesafeThresholds,
+    TypesafeToolQuestions,
+    TypesafeToolSet,
+    parse_decision,
+)
+
+__all__ = (
+    "DEFAULT_MODEL",
+    "DEFAULT_THRESHOLDS",
+    "DESTRUCTIVE_ROUTING_THRESHOLD",
+    "MAX_TOOLS",
+    "REQUEST_BUDGET_TOKENS",
+    "TypesafeAbstainDecision",
+    "TypesafeAbstainedDecisionError",
+    "TypesafeApiError",
+    "TypesafeApiErrorReason",
+    "TypesafeArgumentQuestion",
+    "TypesafeArrayArgument",
+    "TypesafeBypassInfo",
+    "TypesafeCallDecision",
+    "TypesafeCandidate",
+    "TypesafeChoiceArgument",
+    "TypesafeChoiceQuestion",
+    "TypesafeClientLike",
+    "TypesafeConfirmationRequiredError",
+    "TypesafeContextScope",
+    "TypesafeDecision",
+    "TypesafeDecisionMeta",
+    "TypesafeDuplicateToolError",
+    "TypesafeGateBlockedError",
+    "TypesafeGateContext",
+    "TypesafeGateUnavailableError",
+    "TypesafeGateVetoError",
+    "TypesafeIncompleteDecisionError",
+    "TypesafeInvalidOptionsError",
+    "TypesafeJudgement",
+    "TypesafeLimitError",
+    "TypesafeMalformedDecisionError",
+    "TypesafeMalformedResponseError",
+    "TypesafeMissingApiKeyError",
+    "TypesafeNoulQuestion",
+    "TypesafeOption",
+    "TypesafePartialDecision",
+    "TypesafeProvider",
+    "TypesafeProviderError",
+    "TypesafeQuestion",
+    "TypesafeRequestState",
+    "TypesafeShortlist",
+    "TypesafeState",
+    "TypesafeThresholds",
+    "TypesafeToolQuestions",
+    "TypesafeToolSet",
+    "parse_decision",
+)

composio_typesafe/classify.py

@@ -0,0 +1,229 @@
+"""Classifies one tool argument as a closed set Jev can bind, or as open-ended."""
+
+from __future__ import annotations
+
+import typing as t
+
+import typing_extensions as te
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    StrictBool,
+    StrictStr,
+    model_validator,
+)
+from pydantic import ValidationError as PydanticValidationError
+
+from .keys import MAX_CHOICE_OPTIONS
+from .types import _json_number
+
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+_JsonSchemaType = t.Literal[
+    "string", "number", "integer", "boolean", "object", "array", "null"
+]
+# A JSON number: an integer on the wire is as valid as a float. `bool` is an `int`
+# subclass, so `_json_number` rejects it, and strings never reach the float.
+_Number = te.Annotated[float, BeforeValidator(_json_number)]
+
+
+class JsonSchemaProperty(BaseModel):
+    """
+    The keywords of a JSON Schema property that classification reads, typed as the
+    TypeScript SDK types them (`JSONSchemaPropertySchema` in `@composio/core`). A property
+    that fails this parse is open-ended.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: t.Optional[t.Union[_JsonSchemaType, t.List[_JsonSchemaType]]] = None
+    description: t.Optional[StrictStr] = None
+    anyOf: t.Optional[t.List["JsonSchemaProperty"]] = None
+    oneOf: t.Optional[t.List["JsonSchemaProperty"]] = None
+    nullable: t.Optional[StrictBool] = None
+    items: t.Optional[t.Union["JsonSchemaProperty", t.List["JsonSchemaProperty"]]] = (
+        None
+    )
+    enum: t.Optional[t.List[t.Any]] = None
+    const: t.Any = None
+    maxItems: t.Optional[_Number] = None
+    minItems: t.Optional[_Number] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_null(cls, data: t.Any) -> t.Any:
+        # A keyword may be absent, but only `const` may be JSON `null`.
+        if isinstance(data, dict):
+            for keyword, value in data.items():
+                if value is None and keyword in _NON_NULLABLE_KEYWORDS:
+                    raise ValueError("null keyword")
+        return data
+
+
+_NON_NULLABLE_KEYWORDS = frozenset(
+    field.alias or name
+    for name, field in JsonSchemaProperty.model_fields.items()
+    if name != "const"
+)
+
+
+def parse_property(schema: t.Any) -> t.Optional[t.Dict[str, t.Any]]:
+    """Returns the property when it has the accepted shape, else `None`."""
+    if not isinstance(schema, dict):
+        return None
+    try:
+        JsonSchemaProperty.model_validate(schema)
+    except (PydanticValidationError, RecursionError):
+        return None
+    return schema
+
+
+class EnumClass(te.TypedDict):
+    kind: t.Literal["enum"]
+    values: t.List[t.Union[str, int]]
+    nullable: bool
+
+
+class BooleanClass(te.TypedDict):
+    kind: t.Literal["boolean"]
+    nullable: bool
+
+
+class EnumArrayClass(te.TypedDict):
+    kind: t.Literal["enum_array"]
+    values: t.List[t.Union[str, int]]
+    maxItems: te.NotRequired[t.Union[int, float]]
+    minItems: te.NotRequired[t.Union[int, float]]
+
+
+class OpenClass(te.TypedDict):
+    kind: t.Literal["open"]
+
+
+ArgumentClass: te.TypeAlias = t.Union[
+    EnumClass, BooleanClass, EnumArrayClass, OpenClass
+]
+
+_OPEN: OpenClass = {"kind": "open"}
+
+
+def _types_of(schema: t.Mapping[str, t.Any]) -> t.List[str]:
+    declared = schema.get("type")
+    if declared is None:
+        return []
+    return list(declared) if isinstance(declared, list) else [declared]
+
+
+def _literal_members(schema: t.Mapping[str, t.Any]) -> t.Optional[t.List[t.Any]]:
+    """
+    Collects the literal members a property allows, or `None` when any branch is free-form.
+    `anyOf`/`oneOf` branches must each be a `const`, an `enum`, or `{"type": "null"}`.
+    """
+    if "enum" in schema:
+        return list(schema["enum"])
+    if "const" in schema:
+        return [schema["const"]]
+    branches = schema["anyOf"] if "anyOf" in schema else schema.get("oneOf")
+    if not branches:
+        return None
+    members: t.List[t.Any] = []
+    for branch in branches:
+        if _types_of(branch) == ["null"] and "enum" not in branch:
+            members.append(None)
+            continue
+        if "enum" not in branch and "const" not in branch:
+            return None
+        nested = _literal_members(branch)
+        if nested is None:
+            return None
+        members.extend(nested)
+    return members
+
+
+def _normalize_number(member: t.Any) -> t.Any:
+    # JSON `1.0` is the integer 1 in JavaScript. `bool` is an `int` subclass, so it is excluded.
+    if isinstance(member, float) and member.is_integer():
+        return int(member)
+    return member
+
+
+def _classify_members(members: t.List[t.Any], nullable_hint: bool) -> ArgumentClass:
+    nullable = nullable_hint or any(member is None for member in members)
+    values: t.List[t.Any] = []
+    seen: t.Set[t.Tuple[str, t.Any]] = set()
+    for member in members:
+        if member is None:
+            continue
+        value = _normalize_number(member)
+        # `1`, `True`, and `"1"` are three different members.
+        identity = (
+            (type(value).__name__, value)
+            if isinstance(value, (bool, int, float, str))
+            else ("object", id(member))
+        )
+        if identity not in seen:
+            seen.add(identity)
+            values.append(value)
+    if not values:
+        return _OPEN
+    if all(isinstance(value, bool) for value in values):
+        # The boolean Choice offers both values, so a set that allows only one is open-ended.
+        if len(values) != 2:
+            return _OPEN
+        return {"kind": "boolean", "nullable": nullable}
+    strings = [value for value in values if isinstance(value, str)]
+    integers = [
+        value
+        for value in values
+        if isinstance(value, int)
+        and not isinstance(value, bool)
+        and abs(value) <= _MAX_SAFE_INTEGER
+    ]
+    # Mixed-type enums are open-ended: `1` and `"1"` cannot both be told apart by Jev.
+    homogeneous: t.List[t.Union[str, int]] = (
+        list(strings) if len(strings) == len(values) else list(integers)
+    )
+    if len(homogeneous) != len(values):
+        return _OPEN
+    # One slot is taken by "not stated", and one more by `null` when nullable.
+    if len(homogeneous) + (2 if nullable else 1) > MAX_CHOICE_OPTIONS:
+        return _OPEN
+    return {"kind": "enum", "values": homogeneous, "nullable": nullable}
+
+
+def classify_property(parsed: t.Mapping[str, t.Any]) -> ArgumentClass:
+    """
+    Classifies one dereferenced property that `parse_property` accepted. Anything that is
+    not a closed set is open-ended.
+    """
+    types = _types_of(parsed)
+    nullable_hint = parsed.get("nullable") is True or "null" in types
+    value_types = [declared for declared in types if declared != "null"]
+
+    if "object" in value_types:
+        return _OPEN
+
+    if "array" in value_types:
+        items = parsed.get("items")
+        if len(value_types) != 1 or not isinstance(items, dict):
+            return _OPEN
+        item_class = classify_property(items)
+        if item_class["kind"] != "enum" or item_class["nullable"]:
+            return _OPEN
+        array_class: EnumArrayClass = {
+            "kind": "enum_array",
+            "values": item_class["values"],
+        }
+        if "maxItems" in parsed:
+            array_class["maxItems"] = _normalize_number(parsed["maxItems"])
+        if "minItems" in parsed:
+            array_class["minItems"] = _normalize_number(parsed["minItems"])
+        return array_class
+
+    members = _literal_members(parsed)
+    if members is not None:
+        return _classify_members(members, nullable_hint)
+    if value_types == ["boolean"]:
+        return {"kind": "boolean", "nullable": nullable_hint}
+    return _OPEN

composio_typesafe/companion.py

@@ -0,0 +1,307 @@
+"""Companion helpers: `shortlist_tools` and `confidence_gate`. Both work with any provider."""
+
+from __future__ import annotations
+
+import copy
+import math
+import threading
+import typing as t
+
+from composio.client.types import Tool
+from composio.core.models._modifiers import ToolExecuteParams
+
+from .compile import ROUTING_QUESTION_ID, routing_description_of, routing_question
+from .decide import (
+    MAX_TOOLS,
+    REQUEST_BUDGET_TOKENS,
+    Ask,
+    Plan,
+    Questions,
+    estimate_tokens,
+    normalize_state,
+    stable,
+)
+from .types import (
+    TypesafeApiError,
+    TypesafeAvailabilityReason,
+    TypesafeBypassInfo,
+    TypesafeGateBlockedError,
+    TypesafeGateContext,
+    TypesafeGateUnavailableError,
+    TypesafeGateVetoError,
+    TypesafeInvalidOptionsError,
+    TypesafeJsonValue,
+    TypesafeLimitError,
+    TypesafeMalformedResponseError,
+    TypesafeNoulQuestion,
+    TypesafeProviderError,
+    TypesafeShortlist,
+    TypesafeState,
+)
+
+
+def _is_integer(value: t.Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def plan_shortlist(
+    tools: t.Sequence[Tool],
+    state: TypesafeState,
+    k: int,
+) -> Plan[TypesafeShortlist]:
+    """Ranks raw tools against a state. Routing sees `request` only, never `context`."""
+    if not _is_integer(k) or k < 0:
+        raise TypesafeInvalidOptionsError("`k` must be a non-negative integer.")
+    if len(tools) > MAX_TOOLS:
+        raise TypesafeLimitError("tools")
+    normalized = normalize_state(state)
+    if k == 0 or len(tools) == 0 or len(normalized.request.strip()) == 0:
+        return {"tools": [], "scores": []}
+
+    # Routing needs the slug and the routing text only, so the argument schemas stay unread.
+    routing = routing_question(
+        [
+            {"slug": tool.slug, "routingDescription": routing_description_of(tool)}
+            for tool in tools
+        ]
+    )
+    questions: Questions = {ROUTING_QUESTION_ID: routing["question"]}
+    if estimate_tokens(normalized.request_only, questions) > REQUEST_BUDGET_TOKENS:
+        raise TypesafeLimitError("request_budget")
+    answers = yield (normalized.request_only, questions)
+    route = answers.choices.get(ROUTING_QUESTION_ID)
+    if route is None:
+        raise TypesafeMalformedResponseError("missing_answer")
+
+    ranked = sorted(
+        (
+            (-route.probabilities.get(routing["keys"][index], 0.0), index)
+            for index in range(len(tools))
+        )
+    )[:k]
+    return {
+        "tools": [tools[index] for _, index in ranked],
+        "scores": [
+            {"slug": tools[index].slug, "score": -negated} for negated, index in ranked
+        ],
+    }
+
+
+GATE_QUESTION_ID = "gate"
+
+# Static text. The proposed call travels in state under `proposed_call`, so text an LLM
+# wrote into the arguments never sits inside the question.
+GATE_QUESTION: TypesafeNoulQuestion = {
+    "type": "noul",
+    "instructions": "Does running the tool in `proposed_call` with those arguments "
+    "carry out what `request` asks for?",
+    "criteria": {
+        "true": "The proposed call does what the user asked for in `request`.",
+        "false": "The proposed call does something the user did not ask for, or "
+        "contradicts `request`.",
+    },
+}
+
+
+_AVAILABILITY_REASONS: t.Tuple[TypesafeAvailabilityReason, ...] = (
+    "timeout",
+    "connection",
+    "server_error",
+    "rate_limit",
+)
+
+
+class GateModifier(t.Protocol):
+    def __call__(
+        self, tool: str, toolkit: str, params: ToolExecuteParams
+    ) -> ToolExecuteParams: ...
+
+
+def _stable_or_block(value: t.Any) -> TypesafeJsonValue:
+    """A value that is not JSON blocks the call. Nothing is dropped or rewritten."""
+    try:
+        return stable(value)
+    except TypesafeInvalidOptionsError:
+        pass
+    # Raised outside the `except` block, so the invalid-options error is not the context.
+    raise TypesafeGateBlockedError("check_failed")
+
+
+def _leaf_kind(value: t.Any) -> str:
+    # JSON scalar kinds. `bool` is checked first, because it is an `int` subclass.
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, (dict, list)):
+        # Containers are compared structurally by the recursion, never by kind, so a
+        # container at a scalar position (e.g. a redactor replacing a JSON null with
+        # an object) cannot pass as a null-to-null mask.
+        return "container"
+    return "null"
+
+
+def _assert_masking_only(original: t.Any, redacted: t.Any) -> None:
+    """
+    The redactor is a masker: the redacted arguments must have exactly the original's
+    JSON structure, meaning the same key sets and the same array lengths, and every leaf
+    replacement must keep the same scalar kind. Anything else blocks, because Jev would
+    approve a call that differs from the one that runs.
+    """
+    if isinstance(original, list):
+        if not isinstance(redacted, list) or len(redacted) != len(original):
+            raise TypesafeGateBlockedError("check_failed")
+        for entry, replacement in zip(original, redacted):
+            _assert_masking_only(entry, replacement)
+        return
+    if isinstance(original, dict):
+        if not isinstance(redacted, dict) or set(redacted) != set(original):
+            raise TypesafeGateBlockedError("check_failed")
+        for key, entry in original.items():
+            _assert_masking_only(entry, redacted[key])
+        return
+    if _leaf_kind(original) != _leaf_kind(redacted):
+        raise TypesafeGateBlockedError("check_failed")
+
+
+def confidence_gate(
+    *,
+    ask: Ask,
+    tools: t.Sequence[Tool],
+    get_request: t.Callable[[TypesafeGateContext], str],
+    get_context: t.Optional[
+        t.Callable[[TypesafeGateContext], TypesafeJsonValue]
+    ] = None,
+    threshold: float = 0.7,
+    on_unavailable: t.Literal["block", "allow"] = "block",
+    on_bypass: t.Optional[t.Callable[[TypesafeBypassInfo], None]] = None,
+    max_vetoes: int = 3,
+    redact_arguments: t.Optional[
+        t.Callable[[str, t.Dict[str, t.Any]], t.Dict[str, t.Any]]
+    ] = None,
+) -> GateModifier:
+    """
+    Builds a `before_execute` callable that asks Jev whether a proposed tool call matches
+    the user's request. Create one gate per agent run and reuse it across that run's retries.
+    """
+    if (
+        isinstance(threshold, bool)
+        or not isinstance(threshold, (int, float))
+        or math.isnan(threshold)
+        or not 0 <= threshold <= 1
+    ):
+        raise TypesafeInvalidOptionsError(
+            "The gate threshold must be a number from 0 to 1."
+        )
+    if not _is_integer(max_vetoes) or max_vetoes < 1:
+        raise TypesafeInvalidOptionsError("`max_vetoes` must be a positive integer.")
+    if on_unavailable not in ("block", "allow"):
+        # A typo'd mode must never fail open at check time.
+        raise TypesafeInvalidOptionsError(
+            "`on_unavailable` must be 'block' or 'allow'."
+        )
+    by_slug = {tool.slug: tool for tool in tools}
+    lock = threading.Lock()
+    vetoes = 0
+
+    def check(tool: str, toolkit: str, params: ToolExecuteParams) -> ToolExecuteParams:
+        nonlocal vetoes
+        # A hijacked LLM must not be able to vary arguments until one call passes.
+        if vetoes >= max_vetoes:
+            raise TypesafeGateBlockedError("max_vetoes")
+        raw_tool = by_slug.get(tool)
+        if raw_tool is None:
+            raise TypesafeGateBlockedError("unknown_tool")
+
+        context: TypesafeGateContext = {
+            "tool_slug": tool,
+            "toolkit_slug": toolkit,
+            "params": params,
+        }
+        request = get_request(context)
+        gate_context = None if get_context is None else get_context(context)
+        call_arguments: t.Any = dict(params.get("arguments") or {})
+        if redact_arguments is not None:
+            # The redactor works on a deep copy, so one that edits in place cannot alter
+            # the call that runs.
+            copied: t.Any = None
+            try:
+                copied = copy.deepcopy(call_arguments)
+            except Exception:
+                pass
+            if copied is None:
+                raise TypesafeGateBlockedError("check_failed")
+            # The originals are checked first: what the gate reads must be JSON in full.
+            original_arguments = _stable_or_block(call_arguments)
+            call_arguments = redact_arguments(raw_tool.slug, copied)
+            if not isinstance(call_arguments, dict) or not all(
+                isinstance(key, str) for key in call_arguments
+            ):
+                raise TypesafeGateBlockedError("check_failed")
+            # Jev evaluates what is sent, and the original arguments run. The redactor
+            # may only mask, so an approved call is exactly the call that executes.
+            _assert_masking_only(original_arguments, _stable_or_block(call_arguments))
+        description = getattr(raw_tool, "description", None)
+        # Only the slug and the arguments are copied out of the execution parameters.
+        # `user_id`, `connected_account_id`, and the custom auth fields never leave.
+        payload: t.Dict[str, t.Any] = {
+            "request": request,
+            "proposed_call": {
+                "tool": raw_tool.slug,
+                "description": raw_tool.name if description is None else description,
+                "arguments": call_arguments,
+            },
+        }
+        if gate_context is not None:
+            payload["context"] = gate_context
+        state: TypesafeJsonValue = None
+        try:
+            state = stable(payload)
+        except TypesafeInvalidOptionsError:
+            pass
+        # A call the gate cannot read in full is blocked, never sent with a value dropped.
+        if state is None:
+            raise TypesafeGateBlockedError("check_failed")
+        questions: Questions = {GATE_QUESTION_ID: GATE_QUESTION}
+        # Arguments are never truncated to fit.
+        if estimate_tokens(state, questions) > REQUEST_BUDGET_TOKENS:
+            raise TypesafeGateBlockedError("oversized_call")
+
+        probability: t.Optional[float] = None
+        failure: t.Optional[TypesafeProviderError] = None
+        try:
+            answer = ask(state, questions).nouls.get(GATE_QUESTION_ID)
+            probability = None if answer is None else answer.noul
+        except TypesafeProviderError as error:
+            failure = error
+        if failure is not None or probability is None:
+            reason = next(
+                (
+                    known
+                    for known in _AVAILABILITY_REASONS
+                    if isinstance(failure, TypesafeApiError) and failure.reason == known
+                ),
+                None,
+            )
+            if reason is None:
+                raise TypesafeGateBlockedError("check_failed")
+            if on_unavailable == "block":
+                raise TypesafeGateUnavailableError(reason)
+            if on_bypass is not None:
+                on_bypass({"tool_slug": raw_tool.slug, "reason": reason})
+            return params
+
+        if probability >= threshold:
+            return params
+        vetoes += 1
+        raise TypesafeGateVetoError(probability, threshold)
+
+    def gate(tool: str, toolkit: str, params: ToolExecuteParams) -> ToolExecuteParams:
+        # The lock spans the whole check, request included. Checks on one gate run one at
+        # a time, so a burst of parallel calls cannot get past the veto budget together.
+        with lock:
+            return check(tool, toolkit, params)
+
+    return gate