trytilde 3.0.1__py3-none-any.whl

tilde/__init__.py

@@ -0,0 +1,114 @@
+"""Tilde Python SDK: agent hosts, invocation context, channel tools and management clients.
+
+Generated contracts live beside these modules under the proto package names, for example
+``tilde.runtime.v1.chat_pb2`` and ``tilde.types.v1.chat_pb2``. Run ``sdk/py/scripts/generate.py``
+after changing proto/.
+"""
+
+from tilde._cancel import Cancellation, InvocationCancelled, StopLoop
+from tilde._inference import Inference, inference
+from tilde._invocation import current_invocation
+from tilde._tools import (
+    BundledOptions,
+    BundledTools,
+    Tool,
+    ToolAnnotations,
+    ToolCatalog,
+    define_tools,
+    tool_id,
+)
+from tilde.channels import Channels, ChannelTool, ChannelTools
+from tilde.clients import (
+    ManagementClient,
+    RuntimeClient,
+    create_management_client,
+    create_runtime_client,
+    create_tilde_chat_client,
+)
+from tilde.context import AgentContext, DownloadedAttachment, SteeringInput
+from tilde.host import (
+    ConnectedAgent,
+    HostState,
+    InvocationOptions,
+    Wake,
+    connect_agent,
+    create_lambda_handler,
+    run_connected_agent,
+    run_invocation,
+)
+from tilde.logging import DeploymentLogging, agent_log_processor, configure_deployment_logging
+from tilde.messages import (
+    ContextMessage,
+    ConversationMessage,
+    GoalMessage,
+    MessageClient,
+    MessageHistory,
+    ObjectiveMessage,
+    TaskMessage,
+)
+from tilde.prompts import PromptDefinition, define_prompt
+from tilde.skills import (
+    SkillDefinition,
+    SkillFile,
+    SkillFileBody,
+    SkillsClient,
+    SkillsDefinition,
+    define_skill,
+    define_skills,
+)
+from tilde.tracing import agent_span_processor
+
+__all__ = [
+    "Inference",
+    "AgentContext",
+    "BundledOptions",
+    "BundledTools",
+    "Cancellation",
+    "ChannelTool",
+    "ChannelTools",
+    "Channels",
+    "ConnectedAgent",
+    "ContextMessage",
+    "ConversationMessage",
+    "DeploymentLogging",
+    "DownloadedAttachment",
+    "GoalMessage",
+    "HostState",
+    "InvocationCancelled",
+    "InvocationOptions",
+    "ManagementClient",
+    "MessageClient",
+    "MessageHistory",
+    "ObjectiveMessage",
+    "PromptDefinition",
+    "RuntimeClient",
+    "SkillDefinition",
+    "SkillFile",
+    "SkillFileBody",
+    "SkillsClient",
+    "SkillsDefinition",
+    "SteeringInput",
+    "StopLoop",
+    "TaskMessage",
+    "Tool",
+    "ToolAnnotations",
+    "ToolCatalog",
+    "Wake",
+    "agent_log_processor",
+    "agent_span_processor",
+    "configure_deployment_logging",
+    "connect_agent",
+    "create_lambda_handler",
+    "create_management_client",
+    "create_runtime_client",
+    "create_tilde_chat_client",
+    "current_invocation",
+    "define_prompt",
+    "define_skill",
+    "define_skills",
+    "define_tools",
+    "inference",
+    "run_connected_agent",
+    "run_invocation",
+    "tool_id",
+]

tilde/__main__.py

@@ -0,0 +1,9 @@
+"""``python -m tilde deploy [ENTRY] ...``; see ``tilde.deploy``."""
+
+import sys
+
+from tilde.deploy import main
+
+if len(sys.argv) < 2 or sys.argv[1] != "deploy":
+    sys.exit("usage: python -m tilde deploy [ENTRY] [options] (see python -m tilde deploy --help)")
+sys.exit(main(sys.argv[2:]))

tilde/_cancel.py

@@ -0,0 +1,50 @@
+"""Cooperative cancellation shared by the host and the invocation context."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+
+class StopLoop(BaseException):
+    """Raised by ``ctx.stop()``; frameworks must let it propagate like a cancellation."""
+
+
+class InvocationCancelled(BaseException):
+    """The invocation is no longer active (stop control, host shutdown, lost callbacks)."""
+
+
+class Cancellation:
+    """AbortSignal equivalent: aborts once, remembers why and notifies registered callbacks."""
+
+    def __init__(self) -> None:
+        self._event = asyncio.Event()
+        self.reason: BaseException | None = None
+        self._callbacks: list[Callable[[], None]] = []
+
+    @property
+    def aborted(self) -> bool:
+        return self._event.is_set()
+
+    def abort(self, reason: BaseException | None = None) -> None:
+        if self._event.is_set():
+            return
+        self.reason = reason
+        self._event.set()
+        callbacks, self._callbacks = self._callbacks, []
+        for callback in callbacks:
+            callback()
+
+    def on_abort(self, callback: Callable[[], None]) -> None:
+        if self._event.is_set():
+            callback()
+        else:
+            self._callbacks.append(callback)
+
+    def check(self) -> None:
+        """Raise when aborted, like ``AbortSignal.throwIfAborted``."""
+        if self._event.is_set():
+            raise self.reason if self.reason is not None else InvocationCancelled()
+
+    async def wait(self) -> None:
+        await self._event.wait()

tilde/_inference.py

@@ -0,0 +1,106 @@
+"""Route model calls through Tilde's inference gateway with the invocation's own credentials.
+
+``ctx.inference("openai/prod")`` (or an alias the agent was given, such as ``"default"``)
+returns what an OpenAI-compatible client needs: ``base_url``, a placeholder ``api_key`` and an
+``httpx`` client whose auth hook sends the current, renewed invocation token on every request.
+The gateway swaps in the real provider credential and accounts the call, so agents never hold
+provider keys.
+
+``tilde.inference(alias)`` is the module-level form for model clients built at import time:
+every request resolves the invocation running it (token, callback URL, prompt stamps), and a
+request made outside an invocation fails.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Generator
+from typing import Any
+
+import httpx
+
+from tilde._invocation import require_invocation
+
+_SLUG = re.compile(r"^([a-z0-9_]+/)?[A-Za-z0-9._@+:-]+$")
+# Module-level clients are built before any invocation exists; each request is rebased onto
+# the invocation's callback URL, so this host is never dialed.
+_UNBOUND = "http://tilde.invalid"
+
+
+class _InvocationAuth(httpx.Auth):
+    def __init__(self, prepare: Callable[[httpx.Request], httpx.Request]) -> None:
+        self._prepare = prepare
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        yield self._prepare(request)
+
+
+class Inference:
+    """Connection details for one inference slug."""
+
+    api_key = "tilde"
+
+    def __init__(
+        self,
+        base_url: str,
+        authorization: Callable[[], str],
+        prompts: Callable[[], str] = lambda: "",
+        callback_url: Callable[[], str] | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self._authorization = authorization
+        self._prompts = prompts
+        self._callback_url = callback_url
+        self.auth: httpx.Auth = _InvocationAuth(self.prepare)
+
+    def prepare(self, request: httpx.Request) -> httpx.Request:
+        """Stamp one outgoing request, for frameworks that hook requests instead of clients."""
+        if self._callback_url is not None:
+            base = httpx.URL(self._callback_url().rstrip("/"))
+            request.url = request.url.copy_with(
+                scheme=base.scheme,
+                host=base.host,
+                port=base.port,
+                raw_path=base.raw_path.rstrip(b"/") + request.url.raw_path,
+            )
+            request.headers["host"] = request.url.netloc.decode("ascii")
+        # Replaces whatever key the provider SDK set; the gateway authenticates this token.
+        request.headers["authorization"] = self._authorization()
+        stamps = self._prompts()
+        if stamps:
+            request.headers["x-tilde-prompt"] = stamps
+        else:
+            request.headers.pop("x-tilde-prompt", None)
+        return request
+
+    def async_client(self, **options: Any) -> httpx.AsyncClient:
+        """An ``httpx.AsyncClient`` for async provider SDKs (``AsyncOpenAI(http_client=...)``)."""
+        return httpx.AsyncClient(auth=self.auth, **{"timeout": 600.0, **options})
+
+    def client(self, **options: Any) -> httpx.Client:
+        """A synchronous ``httpx.Client`` for provider SDKs that also call synchronously."""
+        return httpx.Client(auth=self.auth, **{"timeout": 600.0, **options})
+
+
+def _check(slug: str) -> None:
+    if not _SLUG.match(slug):
+        raise ValueError("Inference slug must be provider/account or an alias")
+
+
+def bound_inference(
+    callback_url: str, slug: str, authorization: Callable[[], str], prompts: Callable[[], str]
+) -> Inference:
+    _check(slug)
+    return Inference(f"{callback_url.rstrip('/')}/inference/{slug}", authorization, prompts)
+
+
+def inference(slug: str) -> Inference:
+    """Inference for the invocation running each request; safe to build at import time."""
+    _check(slug)
+    what = f"tilde.inference({slug!r})"
+    return Inference(
+        f"{_UNBOUND}/inference/{slug}",
+        lambda: require_invocation(what).trace_authorization(),
+        lambda: require_invocation(what).prompt_stamps(),
+        lambda: require_invocation(what).callback_url,
+    )

tilde/_invocation.py

@@ -0,0 +1,26 @@
+"""The invocation the current task is running, for module-level objects built at import time."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tilde.context import AgentContext
+
+# Set by the host around ``run(ctx)``; asyncio tasks and ``asyncio.to_thread`` inherit it.
+current: ContextVar[AgentContext | None] = ContextVar("tilde_invocation", default=None)
+
+
+def current_invocation() -> AgentContext | None:
+    """The running invocation's context, or ``None`` outside ``run(ctx)``."""
+    return current.get()
+
+
+def require_invocation(what: str) -> AgentContext:
+    ctx = current.get()
+    if ctx is None:
+        raise RuntimeError(
+            f"{what} was used outside a Tilde invocation; call it from within run(ctx)"
+        )
+    return ctx

tilde/_otlp.py

@@ -0,0 +1,35 @@
+"""Minimal OTLP/HTTP protobuf uploads to the invocation callback with the current connect token."""
+
+from __future__ import annotations
+
+import logging
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from urllib.parse import urlsplit, urlunsplit
+
+log = logging.getLogger("tilde")
+
+
+def otlp_url(base_url: str, signal: str) -> str:
+    """Match the runtime RPC base path when a reverse proxy separates audiences by prefix."""
+    parts = urlsplit(base_url)
+    path = f"{parts.path.rstrip('/')}/v1/{signal}"
+    return urlunsplit((parts.scheme, parts.netloc, path, "", ""))
+
+
+def post_protobuf(
+    url: str, payload: bytes, authorization: Callable[[], str], timeout: float = 15.0
+) -> bool:
+    request = urllib.request.Request(
+        url,
+        data=payload,
+        method="POST",
+        headers={"Content-Type": "application/x-protobuf", "Authorization": authorization()},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 - caller-supplied callback URL
+            return 200 <= response.status < 300
+    except (urllib.error.URLError, OSError, ValueError) as error:
+        log.debug("OTLP upload to %s failed: %s", url, error)
+        return False

tilde/_tools.py

@@ -0,0 +1,182 @@
+"""Tools in ``ctx.tools``: provider tools published for the invocation (descriptions and schemas
+come from Tilde) and SDK lifecycle helpers. The agent's bundled tools are its own framework tools,
+published by each adapter's ``with_tilde_tools``."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import uuid
+from collections.abc import AsyncIterable, Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+ExecuteFn = Callable[[Any, str], Awaitable[Any]]
+#: How calls of one of the agent's own tools show in end-user chats; traces keep full detail.
+ToolDisplay = Literal["full", "summary", "hidden"]
+StreamFn = Callable[[Any, AsyncIterable[Any], str], Awaitable[Any]]
+
+
+@dataclass(slots=True, frozen=True)
+class ToolAnnotations:
+    """Hints for ordering, confirming or parallelising calls; never authorization."""
+
+    read_only: bool = False
+    destructive: bool = False
+    idempotent: bool = False
+    open_world: bool = False
+
+
+@dataclass(slots=True)
+class Tool:
+    """One tool in ``ctx.tools``, or the published definition of a bundled tool."""
+
+    description: str
+    input_schema: dict[str, Any]
+    _execute: ExecuteFn = field(repr=False)
+    provider_id: str | None = None
+    chunk_schema: dict[str, Any] | None = None
+    _stream: StreamFn | None = field(default=None, repr=False)
+    output_schema: dict[str, Any] | None = None
+    #: Short label for transcripts.
+    summary: str | None = None
+    annotations: ToolAnnotations | None = None
+    #: Returns a ticket at once; the outcome arrives later as new input and through tools.result.
+    background: bool = False
+    display: ToolDisplay = "full"
+
+    async def execute(self, input: Any, *, tool_call_id: str | None = None) -> Any:
+        """Send completed input; ``tool_call_id`` is the framework's call ID for auditing."""
+        return await self._execute(input, tool_call_id or str(uuid.uuid4()))
+
+    @property
+    def can_stream(self) -> bool:
+        return self._stream is not None
+
+    async def stream(self, input: Any, chunks: AsyncIterable[Any], *, tool_call_id: str) -> Any:
+        """Send incremental input in the provider's ``chunk_schema`` format.
+
+        A framework must feed chunks explicitly; registering a tool never streams model tokens.
+        """
+        if self._stream is None:
+            raise ValueError("This tool does not accept incremental input")
+        return await self._stream(input, chunks, tool_call_id)
+
+
+ToolCatalog = dict[str, Tool]
+
+
+@dataclass(slots=True, frozen=True)
+class BundledOptions:
+    """Tilde metadata for one of the agent's own framework tools, overriding what the framework
+    declares. ``display`` is how its calls show in end-user chats: with input and output, only
+    the summary, or hidden; traces keep full detail."""
+
+    summary: str | None = None
+    display: ToolDisplay = "full"
+    annotations: ToolAnnotations | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class BundledTools:
+    """An agent's own framework tools with their Tilde options, from ``define_tools``."""
+
+    tools: list[Any]
+    options: dict[str, BundledOptions]
+
+
+def define_tools(
+    tools: Sequence[Any], *, options: Mapping[str, BundledOptions] | None = None
+) -> BundledTools:
+    """Declare the agent's bundled tools: its framework's own tools (functions, ``@tool``s,
+    ``FunctionTool``s, ...) with Tilde options by tool name. Pass the result to the adapter's
+    per-invocation helper as ``bundled`` (or its parts to ``with_tilde_tools``); at module level,
+    ``tilde deploy`` declares the tools with the deployment."""
+    return BundledTools(list(tools), dict(options or {}))
+
+
+@dataclass(slots=True, frozen=True)
+class ToolSpec:
+    """One of the agent's framework tools as Tilde publishes it per invocation and ``tilde deploy``
+    declares it, with its Tilde options applied. Each adapter's ``describe_tool`` builds it."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any] | None = None
+    summary: str | None = None
+    annotations: ToolAnnotations | None = None
+    display: ToolDisplay = "full"
+
+
+def tool_spec(
+    name: str,
+    description: str,
+    input_schema: dict[str, Any],
+    *,
+    output_schema: dict[str, Any] | None = None,
+    annotations: ToolAnnotations | None = None,
+    options: BundledOptions | None = None,
+) -> ToolSpec:
+    """What the framework declares, overridden by ``options``."""
+    options = options or BundledOptions()
+    return ToolSpec(
+        name=name,
+        description=description,
+        input_schema=input_schema,
+        output_schema=output_schema,
+        summary=options.summary,
+        annotations=options.annotations or annotations,
+        display=options.display,
+    )
+
+
+def bundled_tool(spec: ToolSpec, execute: ExecuteFn) -> Tool:
+    """Internal: the definition adapters publish for a framework tool. ``execute`` runs it for a
+    ``tools.execute`` routed here and must audit the call itself, exactly as a direct call is."""
+    return Tool(
+        description=spec.description,
+        input_schema=spec.input_schema,
+        _execute=execute,
+        output_schema=spec.output_schema,
+        summary=spec.summary,
+        annotations=spec.annotations,
+        display=spec.display,
+    )
+
+
+_MODEL_INVALID = re.compile(r"[^a-zA-Z0-9_-]")
+
+
+def model_tool_name(name: str, invalid: re.Pattern[str] = _MODEL_INVALID) -> str:
+    """The name a framework shows the model for a Tilde tool: ``name`` with characters matching
+    ``invalid`` (the framework's disallowed characters) replaced by ``_``. Catalog names
+    (``{source}.{tool}``) can exceed the 64 characters models accept, so a longer result is
+    truncated and suffixed with a hash of ``name``, keeping it stable and distinct from other
+    long names sharing its start. Adapters bind each alias to its catalog tool when converting.
+    Matches ``modelToolName`` in the TypeScript SDK."""
+    key = invalid.sub("_", name)
+    if len(key) <= 64:
+        return key
+    return f"{key[:55]}_{hashlib.sha256(name.encode()).hexdigest()[:8]}"
+
+
+def tool_id(invocation: str, call: str, name: str) -> str:
+    """Stable UUID derived from the invocation and the framework's tool-call ID."""
+    if not call:
+        raise ValueError("Tool call ID is required")
+    h = hashlib.sha256(f"{invocation}:{call}:{name}".encode()).hexdigest()
+    return f"{h[:8]}-{h[8:12]}-4{h[13:16]}-a{h[17:20]}-{h[20:32]}"
+
+
+def as_object(input: Any) -> dict[str, Any]:
+    if not isinstance(input, dict):
+        raise ValueError("Tool input must be an object")
+    return input
+
+
+def as_string(input: dict[str, Any], key: str) -> str:
+    value = input.get(key)
+    if not isinstance(value, str):
+        raise ValueError(f"{key} must be a string")
+    return value

tilde/_transport.py

@@ -0,0 +1,28 @@
+"""One HTTP/2 transport per process for callbacks, matching the Node SDK's HTTP/2 clients."""
+
+from __future__ import annotations
+
+import pyqwest
+
+_transport: pyqwest.HTTPTransport | None = None
+
+
+def http_client() -> pyqwest.Client:
+    global _transport
+    if _transport is None:
+        # Plaintext callback URLs use HTTP/2 prior knowledge; TLS negotiates HTTP/2 through ALPN.
+        # Redirects are refused so bearer credentials never follow an upstream redirect.
+        _transport = pyqwest.HTTPTransport(
+            http_version=pyqwest.HTTPVersion.HTTP2,
+            follow_redirects=False,
+            tls_include_system_certs=True,
+        )
+    return pyqwest.Client(_transport)
+
+
+async def close_http_client() -> None:
+    """Close pooled callback connections, for example before a test server shuts down."""
+    global _transport
+    transport, _transport = _transport, None
+    if transport is not None:
+        await transport.aclose()