trustgate-sdk 0.1.0__py3-none-any.whl

trustgate/__init__.py

@@ -0,0 +1,95 @@
+"""TrustGate SDK - governed tools and models for agents.
+
+An admin creates the consumer and decides what it may reach; this package
+points an agent at it. What it adds on top of a plain HTTP call is the part
+that is easy to get wrong: which actor a call speaks as, whether the tools the
+agent was written around are still on its toolkit, and what to do when an
+upstream account is not connected.
+"""
+
+from .agent import Agent, EndUserAgent, Toolkit
+from .client import LLMEndpoint, TrustGate
+from .config import API_KEY_HEADER, END_USER_HEADER
+from .errors import (
+    AuthenticationError,
+    ConsentRequiredError,
+    InvalidRequestError,
+    MissingToolsError,
+    PlaneUnavailableError,
+    PolicyBlockedError,
+    RateLimitedError,
+    ServiceUnavailableError,
+    ToolNotFoundError,
+    TrustGateError,
+    TrustGateServerError,
+    UpstreamNotConnectedError,
+)
+from .formats import ConversionWarning, adapter_for, result_to_text
+from .mcp import MCPTransport
+from .schema import StrictResult, inline_refs, strip_injected_nulls, to_strict
+from .transport import Response, Transport, UrllibTransport
+from .types import (
+    Actor,
+    Connection,
+    ConnectLink,
+    Endpoint,
+    GatewayTool,
+    ToolCall,
+    ToolFormat,
+)
+from .whoami import (
+    KeyConsumer,
+    KeyIdentity,
+    KeyInfo,
+    KeyUpstream,
+    select_consumer,
+    who_am_i,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Actor",
+    "Agent",
+    "API_KEY_HEADER",
+    "AuthenticationError",
+    "ConnectLink",
+    "Connection",
+    "ConsentRequiredError",
+    "ConversionWarning",
+    "END_USER_HEADER",
+    "Endpoint",
+    "EndUserAgent",
+    "GatewayTool",
+    "KeyConsumer",
+    "KeyIdentity",
+    "KeyInfo",
+    "KeyUpstream",
+    "InvalidRequestError",
+    "LLMEndpoint",
+    "MCPTransport",
+    "MissingToolsError",
+    "PlaneUnavailableError",
+    "PolicyBlockedError",
+    "RateLimitedError",
+    "Response",
+    "ServiceUnavailableError",
+    "StrictResult",
+    "ToolCall",
+    "ToolFormat",
+    "ToolNotFoundError",
+    "Toolkit",
+    "Transport",
+    "TrustGate",
+    "TrustGateError",
+    "TrustGateServerError",
+    "UpstreamNotConnectedError",
+    "UrllibTransport",
+    "adapter_for",
+    "inline_refs",
+    "result_to_text",
+    "select_consumer",
+    "strip_injected_nulls",
+    "to_strict",
+    "who_am_i",
+]

trustgate/agent.py

@@ -0,0 +1,208 @@
+"""The handles `connect()` hands out, one per actor."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .config import END_USER_HEADER, Config
+from .connections import create_connect_link, list_connections, require_end_user
+from .formats import ConversionWarning, ToolResult, adapter_for, restore_arguments
+from .mcp import MCPTransport
+from .schema import Schema
+from .transport import Transport
+from .types import (
+    Actor,
+    Connection,
+    ConnectLink,
+    Endpoint,
+    GatewayTool,
+    ToolCall,
+    ToolFormat,
+    resolve_tool_name,
+)
+
+
+class Toolkit:
+    """A tool surface in one provider's dialect, with the executor that belongs to it.
+
+    They travel together because they are two halves of one translation: what
+    ``tools`` added on the way out, ``execute`` has to undo on the way back.
+    """
+
+    def __init__(
+        self,
+        tools: list[Any],
+        warnings: list[ConversionWarning],
+        tool_format: ToolFormat,
+        originals: dict[str, Schema],
+        transport: MCPTransport,
+    ) -> None:
+        #: Pass this straight to the provider's API.
+        self.tools = tools
+        #: Tools whose schema could not be expressed in the requested dialect.
+        self.warnings = warnings
+        self._format = tool_format
+        self._originals = originals
+        self._transport = transport
+
+    def calls(self, output: Any) -> list[ToolCall]:
+        """The calls the model asked for, read out of the provider's response."""
+        return adapter_for(self._format).extract_calls(output)
+
+    def execute(self, output: Any) -> list[Any]:
+        """Runs the calls the model asked for and returns what to send back.
+
+        Every call goes to the gateway, so the policy, the audit trail and the
+        upstream credentials stay where they were. The caller's process only
+        decides whether to make the call at all.
+        """
+        adapter = adapter_for(self._format)
+        results = []
+        for call in adapter.extract_calls(output):
+            arguments = restore_arguments(call.arguments, self._originals.get(call.name))
+            result = self._transport.call_tool(call.name, arguments)
+            results.append(ToolResult(call=call, result=result))
+        return adapter.to_outputs(results)
+
+
+class _ToolSurface:
+    """What both handles share: a surface, and the ways to spend it."""
+
+    def __init__(self, transport: MCPTransport, tools: list[GatewayTool]) -> None:
+        self._transport = transport
+        self.tools = tools
+
+    @property
+    def mcp(self) -> Endpoint:
+        """URL and headers for a framework that brings its own MCP client."""
+        return Endpoint(url=self._transport.url, headers=self._transport.headers)
+
+    def toolkit(self, tool_format: ToolFormat | str, strict: bool = False) -> Toolkit:
+        """The same surface, translated for a provider you call directly."""
+        resolved = ToolFormat(tool_format)
+        conversion = adapter_for(resolved).convert(self.tools, strict)
+        return Toolkit(
+            conversion.tools, conversion.warnings, resolved, conversion.originals, self._transport
+        )
+
+    def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:
+        """One tool, called directly. The escape hatch under the toolkits.
+
+        The server prefix is optional here: "list_issues" reaches
+        "linear_list_issues" while Linear is the only server of this application
+        that serves it. The gateway put that prefix there, so a caller writing
+        the name by hand should not have to.
+        """
+        return self._transport.call_tool(resolve_tool_name(name, self.tools), arguments)
+
+    def refresh(self) -> list[GatewayTool]:
+        """Re-reads the surface.
+
+        An admin owns this toolkit and can change it under a running agent, so
+        a long-lived process re-reads rather than trusting the list it took at
+        startup.
+        """
+        self.tools = self._transport.list_tools()
+        return self.tools
+
+
+class Agent(_ToolSurface):
+    """An application's handle on its gateway.
+
+    It speaks as the application itself: one principal, its own upstream
+    accounts, nothing per-user. Which handle you get is not a choice made here -
+    it follows from how the consumer was configured, which is why ``connect()``
+    returns one of these or refuses.
+    """
+
+    actor = Actor.APPLICATION
+
+    def __init__(
+        self,
+        config: Config,
+        transport_impl: Transport,
+        slug: str,
+        transport: MCPTransport,
+        tools: list[GatewayTool],
+        connections: list[Connection],
+    ) -> None:
+        super().__init__(transport, tools)
+        self._config = config
+        self._http = transport_impl
+        self.slug = slug
+        #: The application's own upstream accounts, as of ``connect()``.
+        self.connections = connections
+
+    def refresh_connections(self) -> list[Connection]:
+        """What the application still owes before it can call every server."""
+        return list_connections(self._config, self._http, self.slug)
+
+    def for_end_user(self, end_user: str) -> EndUserAgent:
+        """The same application, acting for one named person.
+
+        No round trip and no second surface to read: the toolkit an admin bound
+        is the application's, identical for everyone it acts for. What changes
+        is one header, and with it whose upstream account the gateway reaches
+        for.
+        """
+        return end_user_agent(
+            self._config,
+            self._http,
+            self.slug,
+            end_user,
+            self._transport.url,
+            self.tools,
+        )
+
+
+class EndUserAgent(_ToolSurface):
+    """An application's handle for one of its own end users.
+
+    The user travels in a header, so a handle is a header and nothing more -
+    but the MCP endpoint's headers are fixed when a client connects, which is
+    why each user needs their own transport rather than a shared one.
+    """
+
+    actor = Actor.END_USER
+
+    def __init__(
+        self,
+        config: Config,
+        transport_impl: Transport,
+        slug: str,
+        end_user: str,
+        transport: MCPTransport,
+        tools: list[GatewayTool],
+    ) -> None:
+        super().__init__(transport, tools)
+        self._config = config
+        self._http = transport_impl
+        self.slug = slug
+        self.end_user = end_user
+
+    def connections(self) -> list[Connection]:
+        """Which servers this user has connected, and which they have not."""
+        return list_connections(self._config, self._http, self.slug, self.end_user)
+
+    def connect_link(self, provider: str | None = None) -> ConnectLink:
+        """The page to put in front of this user so they can connect an account.
+
+        Naming a provider narrows it to that one server; omitting it covers
+        every server of the application that forwards a credential. The link
+        expires, so it is minted when it is about to be shown, not cached.
+        """
+        return create_connect_link(self._config, self._http, self.slug, self.end_user, provider)
+
+
+def end_user_agent(
+    config: Config,
+    transport_impl: Transport,
+    slug: str,
+    raw_end_user: str,
+    url: str,
+    tools: list[GatewayTool],
+) -> EndUserAgent:
+    """Builds the per-user handle, with the header that names them."""
+    end_user = require_end_user(raw_end_user)
+    transport = MCPTransport(config, transport_impl, url, {END_USER_HEADER: end_user})
+    return EndUserAgent(config, transport_impl, slug, end_user, transport, tools)

trustgate/client.py

@@ -0,0 +1,180 @@
+"""The entry point: a gateway and a key, and everything else is asked for."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .agent import Agent, EndUserAgent, end_user_agent
+from .config import API_KEY_HEADER, resolve_config
+from .connections import list_connections
+from .errors import MissingToolsError, UpstreamNotConnectedError
+from .mcp import MCPTransport
+from .transport import Transport, UrllibTransport
+from .types import CONNECTED, Connection, GatewayTool, resolve_tool_name
+from .whoami import KeyIdentity, KeyUpstream, select_consumer, who_am_i
+
+
+@dataclass(frozen=True)
+class LLMEndpoint:
+    """What the LLM plane needs to be handed to a provider's own client."""
+
+    #: Pass as ``base_url`` to the OpenAI client. It ends in ``/v1``.
+    base_url: str
+    api_key: str
+    headers: dict[str, str]
+    #: The consumer behind it, for logs and for error messages.
+    consumer: str
+
+    @property
+    def anthropic_base_url(self) -> str:
+        """Pass as ``base_url`` to the Anthropic client.
+
+        The two clients disagree on where the version goes. OpenAI's is handed
+        a base that already ends in ``/v1`` and appends ``/chat/completions``;
+        Anthropic's appends ``/v1/messages`` to what it is given, so handing it
+        ``base_url`` asks the gateway for ``/v1/v1/messages``. This is the
+        application's root, the one every dialect but OpenAI's hangs from.
+        """
+        return _without_version(self.base_url)
+
+
+def _without_version(url: str) -> str:
+    trimmed = url.rstrip("/")
+    return trimmed[: -len("/v1")] if trimmed.endswith("/v1") else trimmed
+
+
+class TrustGate:
+    """A gateway and a key, and everything else is asked for.
+
+    The key is attached to consumers, and a consumer has one type - so the
+    tools live behind an MCP consumer and the models behind an LLM one. Their
+    slugs were chosen by whoever created them, and the two planes do not share
+    a host, so neither is something a caller should have to carry: the gateway
+    is asked once, at ``connect()``, and answers both.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        mcp_consumer: str | None = None,
+        llm_consumer: str | None = None,
+        timeout: float = 30.0,
+        transport: Transport | None = None,
+    ) -> None:
+        self._config = resolve_config(base_url, api_key, mcp_consumer, llm_consumer, timeout)
+        self._transport = transport or UrllibTransport()
+        self._identity: KeyIdentity | None = None
+
+    def identity(self) -> KeyIdentity:
+        """What this key reaches.
+
+        Read once and remembered: it is a property of the key, and a
+        long-lived process should not re-ask on every call.
+        """
+        if self._identity is None:
+            self._identity = who_am_i(self._config, self._transport)
+        return self._identity
+
+    def llm(self) -> LLMEndpoint:
+        """The LLM plane, ready for a provider's own SDK.
+
+        The gateway speaks the providers' own APIs, so nothing here wraps their
+        clients - it points them somewhere else. Wrapping would mean chasing
+        every change they make and breaking streaming on the way.
+        """
+        consumer = select_consumer(
+            self.identity(), "LLM", self._config.llm_consumer, "llm_consumer"
+        )
+        return LLMEndpoint(
+            base_url=consumer.url,
+            api_key=self._config.api_key,
+            headers={API_KEY_HEADER: self._config.api_key},
+            consumer=consumer.slug,
+        )
+
+    def connect(self, requires: list[str] | None = None) -> Agent:
+        """Opens the application's own surface and proves it is usable.
+
+        Two things happen here, and both are the kind that are cheap now and
+        expensive later: whether the tools the agent needs are actually on its
+        toolkit, and whether the servers behind it have an account to call
+        with. The second has no runtime remedy for this handle - nobody is
+        present to open a connect link once a batch is going - which is the
+        whole reason it is checked at startup.
+
+        This is the application actor: the key and nothing else, so the gateway
+        runs the calls as ``app:<consumer_id>``. For a call on behalf of a
+        person, use :meth:`for_end_user`; both work on the same consumer,
+        because who a request runs as is read from the request rather than
+        declared anywhere.
+        """
+        consumer = select_consumer(
+            self.identity(), "MCP", self._config.mcp_consumer, "mcp_consumer"
+        )
+        # Accounts before tools: a server with no account for the application
+        # can fail the listing itself, which would surface as a bare gateway
+        # error before this check - the one that says who fixes it - ever ran.
+        connections = list_connections(self._config, self._transport, consumer.slug)
+        blocked = _blocked_upstreams(consumer.upstreams, connections)
+        if blocked:
+            raise UpstreamNotConnectedError(blocked)
+
+        transport = MCPTransport(self._config, self._transport, consumer.url)
+        tools = transport.list_tools()
+        _check_requires(tools, list(requires or []))
+
+        return Agent(self._config, self._transport, consumer.slug, transport, tools, connections)
+
+    def for_end_user(self, end_user: str, requires: list[str] | None = None) -> EndUserAgent:
+        """The handle for one named person, on the same consumer and the same key.
+
+        The name is asserted by this application and not verified, so the
+        gateway namespaces it: two applications naming ``user_123`` never share
+        an account. What that person still has to connect is theirs to connect
+        - the handle's own connections mint the link to put in front of them -
+        which is why there is no startup preflight here and one in
+        :meth:`connect`.
+        """
+        consumer = select_consumer(
+            self.identity(), "MCP", self._config.mcp_consumer, "mcp_consumer"
+        )
+        agent = end_user_agent(
+            self._config, self._transport, consumer.slug, end_user, consumer.url, []
+        )
+        _check_requires(agent.refresh(), list(requires or []))
+        return agent
+
+
+def _check_requires(tools: list[GatewayTool], requires: list[str]) -> None:
+    """The tools an agent was written around, checked before anything runs.
+
+    Each one is resolved the way call_tool resolves it, so an agent may require
+    the name its server gave the tool and leave the gateway's server prefix to
+    the gateway.
+    """
+    names = {tool.name for tool in tools}
+    missing = [name for name in requires if resolve_tool_name(name, tools) not in names]
+    if missing:
+        raise MissingToolsError(missing, sorted(names))
+
+
+def _blocked_upstreams(
+    upstreams: list[KeyUpstream] | None, connections: list[Connection]
+) -> list[KeyUpstream]:
+    """What this application still has to have connected before it can run.
+
+    ``whoami`` answers it best, because it also names who has to act. But the
+    field is absent on a gateway too old to send it, and an absent list is not
+    an empty one: taking it for "nothing to connect" is how a batch gets past
+    its own startup check and fails on the first row instead, which is the
+    failure the check exists to prevent. So when it is missing the connections
+    list answers, as it did before ``whoami`` carried this at all.
+    """
+    if upstreams is not None:
+        return [upstream for upstream in upstreams if upstream.blocked]
+    return [
+        KeyUpstream(server=connection.registry or connection.provider)
+        for connection in connections
+        if connection.status != CONNECTED
+    ]

trustgate/config.py

@@ -0,0 +1,51 @@
+"""Where the SDK gets its gateway, its key and its consumers."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .errors import TrustGateError
+
+#: The header the gateway reads the consumer's API key from. It also accepts
+#: ``x-api-key`` and ``Authorization: Bearer ag_...``; this one is the
+#: unambiguous spelling, so it is the one the SDK sends.
+API_KEY_HEADER = "X-AG-API-Key"
+
+#: The header that names which of the application's end users a call is for.
+END_USER_HEADER = "X-NeuralTrust-End-User"
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: str
+    api_key: str
+    mcp_consumer: str | None = None
+    llm_consumer: str | None = None
+    timeout: float = 30.0
+
+
+def resolve_config(
+    base_url: str | None = None,
+    api_key: str | None = None,
+    mcp_consumer: str | None = None,
+    llm_consumer: str | None = None,
+    timeout: float = 30.0,
+) -> Config:
+    resolved_url = (base_url or os.environ.get("TRUSTGATE_URL") or "").strip().rstrip("/")
+    resolved_key = (api_key or os.environ.get("TRUSTGATE_API_KEY") or "").strip()
+    if not resolved_url:
+        raise TrustGateError("base_url is required (or set TRUSTGATE_URL)")
+    if not resolved_url.startswith(("http://", "https://")):
+        raise TrustGateError(f'base_url must be an http(s) URL, got "{resolved_url}"')
+    if not resolved_key:
+        raise TrustGateError("api_key is required (or set TRUSTGATE_API_KEY)")
+    return Config(
+        base_url=resolved_url,
+        api_key=resolved_key,
+        mcp_consumer=(mcp_consumer or os.environ.get("TRUSTGATE_MCP_CONSUMER") or "").strip()
+        or None,
+        llm_consumer=(llm_consumer or os.environ.get("TRUSTGATE_LLM_CONSUMER") or "").strip()
+        or None,
+        timeout=timeout,
+    )

trustgate/connections.py

@@ -0,0 +1,100 @@
+"""The connections API: which upstream accounts an actor has, and the link to add one."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote
+
+from .config import API_KEY_HEADER, END_USER_HEADER, Config
+from .errors import InvalidRequestError
+from .transport import Transport, error_for_response
+from .types import Connection, ConnectLink
+
+
+def connections_path(slug: str, end_user: str | None = None) -> str:
+    query = f"?end_user={quote(end_user)}" if end_user else ""
+    return f"/{quote(slug)}/connections{query}"
+
+
+def list_connections(
+    config: Config, transport: Transport, slug: str, end_user: str | None = None
+) -> list[Connection]:
+    response = transport.request(
+        "GET",
+        f"{config.base_url}{connections_path(slug, end_user)}",
+        {API_KEY_HEADER: config.api_key, "Accept": "application/json"},
+        None,
+        config.timeout,
+    )
+    if response.status >= 400:
+        raise error_for_response(response)
+    body = response.json() or {}
+    return [_to_connection(item) for item in (body.get("connections") or [])]
+
+
+def create_connect_link(
+    config: Config,
+    transport: Transport,
+    slug: str,
+    end_user: str,
+    provider: str | None = None,
+) -> ConnectLink:
+    payload: dict[str, Any] = {"end_user": end_user}
+    if provider:
+        payload["provider"] = provider
+    response = transport.request(
+        "POST",
+        f"{config.base_url}/{quote(slug)}/connections/links",
+        {
+            API_KEY_HEADER: config.api_key,
+            END_USER_HEADER: end_user,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json.dumps(payload).encode("utf-8"),
+        config.timeout,
+    )
+    if response.status >= 400:
+        raise error_for_response(response)
+    body = response.json() or {}
+    return ConnectLink(
+        connect_url=body.get("connect_url", ""),
+        ticket=body.get("ticket", ""),
+        provider=body.get("provider") or None,
+        expires_at=_to_datetime(body.get("expires_at")) or datetime.now(),
+    )
+
+
+def require_end_user(end_user: str) -> str:
+    """The gateway is the authority on what an end-user id may be.
+
+    This only catches the mistake worth catching locally, which is the empty
+    one - it would otherwise be sent as a header the gateway reads as "no user
+    named" and answer for the wrong actor.
+    """
+    trimmed = (end_user or "").strip()
+    if not trimmed:
+        raise InvalidRequestError("an end-user id is required to act for a user")
+    return trimmed
+
+
+def _to_connection(payload: dict[str, Any]) -> Connection:
+    return Connection(
+        provider=payload.get("provider", ""),
+        status=payload.get("status", ""),
+        registry=payload.get("registry") or None,
+        code=payload.get("code") or None,
+        account_ref=payload.get("account_ref") or None,
+        expires_at=_to_datetime(payload.get("expires_at")),
+    )
+
+
+def _to_datetime(raw: Any) -> datetime | None:
+    if not raw or not isinstance(raw, str):
+        return None
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None