trytilde-pydantic-ai 3.0.1__tar.gz

trytilde_pydantic_ai-3.0.1/.gitignore

@@ -0,0 +1,51 @@
+/target/
+/dist/
+node_modules/
+# Build output of an older example-agent layout; the examples live under sdk/ts/examples.
+/dev/example-agent-1/
+/web/dist/
+/.tools/
+/.env.*
+!/.env.example
+!/.env.test
+/.run/
+.run/
+
+/sdk/ts/**/dist/
+# Generated TypeScript contracts; @trytilde/contracts builds them from proto/.
+/sdk/ts/packages/contracts/gen/
+
+/web/provider-dist/
+
+__pycache__/
+
+# Local runtime credentials must not enter the initial repository commit.
+/.env
+log
+
+/.local/
+
+# Bifrost benchmark container state
+/dev/inference-bench/bifrost/*
+!/dev/inference-bench/bifrost/config.json
+
+# Local Claude Code worktrees
+/.claude/worktrees/
+
+# Python SDK: uv environments and generated contracts (sdk/py/scripts/generate.py).
+/sdk/py/.venv/
+/sdk/py/.venv-crewai/
+/sdk/py/**/.venv/
+/sdk/py/packages/tilde/src/tilde/agent_event_ingress/
+/sdk/py/packages/tilde/src/tilde/agent_host/
+/sdk/py/packages/tilde/src/tilde/ingress/
+/sdk/py/packages/tilde/src/tilde/management/
+/sdk/py/packages/tilde/src/tilde/provider/
+/sdk/py/packages/tilde/src/tilde/run/
+/sdk/py/packages/tilde/src/tilde/runtime/
+/sdk/py/packages/tilde/src/tilde/setup/
+/sdk/py/packages/tilde/src/tilde/tool_host/
+/sdk/py/packages/tilde/src/tilde/types/
+/sdk/py/**/*.egg-info/
+.pytest_cache/
+.ruff_cache/

trytilde_pydantic_ai-3.0.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: trytilde-pydantic-ai
+Version: 3.0.1
+Summary: Tilde adapter for Pydantic AI: typed context to model messages, channel tools to Pydantic AI tools
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: pydantic-ai-slim<3,>=2
+Requires-Dist: trytilde
+Description-Content-Type: text/markdown
+
+# Pydantic AI adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+Pydantic AI `ModelMessage` history and channel tools to Pydantic AI tools, bundles an
+invocation's run options in `tilde_pydantic_ai(ctx)` and lets `tilde deploy` register a
+module-level agent's prompts.
+
+```python
+import tilde
+from pydantic_ai import Agent
+from pydantic_ai.usage import UsageLimits
+from tilde_pydantic_ai import convert_to_pydantic_ai_messages, tilde_pydantic_ai
+
+INFERENCE = tilde.inference("default")
+responder = Agent(model_using(INFERENCE), instructions="Respond using the channel's tools.")
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_pydantic_ai_messages(history.items, context=ctx)
+    await responder.run(
+        message_history=messages,
+        usage_limits=UsageLimits(request_limit=8),
+        **await tilde_pydantic_ai(ctx),
+    )
+```
+
+`tilde_pydantic_ai(ctx)` returns `capabilities=[TildeInvocation]` and a `cancellation_token`
+that a stop or suspension cancels. The per-run capability contributes the current channel's
+tools, enqueues input steered while the agent works after every graph node (`RunContext.enqueue`,
+delivered with the next model request), stamps the agent's dynamic instructions on its model
+calls and, since Pydantic AI has no native skills, adds `list_skills`/`read_skill` with the
+skills summary in the instructions (`skills=False` leaves them out).
+
+`tilde deploy` (entry point `tilde.discover`) registers each module-level `Agent`'s instructions
+and system prompts as `<name or variable>/instructions` and `<name>/system_prompt` (`/<n>` from 1
+when there are several): text is plain, `TemplateStr` is mustache and a function is dynamic with
+its source as the template. They are read from Pydantic AI's private fields (2.43); an
+unreadable agent is reported in the inventory.
+
+History pages are chronological; pass `before_message_id=history.next_page_token` for older
+messages. The latest page includes the current objective unless it already matches the latest
+received message. `include_objective=False` omits it. `include_work=True` also reads current
+goals/tasks and requires `work.read`. Only the acting agent's messages become `ModelResponse`
+items; everything else is a `ModelRequest` with a `UserPromptPart`. Messages whose status is
+not `complete` are skipped unless a custom `message` handler is given.
+
+Pydantic AI parts have no id field. Each converted message keeps its Tilde id in the
+application-level `metadata` (`{"tilde_message_id": ...}`, read it with `message_id(message)`);
+that metadata is never sent to the model.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and embedded as
+`BinaryContent`. Text files include their real content. Unsupported binary formats get an
+explicit attachment description; use `on_attachment` to parse them yourself. No private URL or
+credential needs to be exposed to the model. Converting a message with attachments without a
+`context` or custom handler raises instead of silently dropping the file.
+
+```python
+from tilde_pydantic_ai import MessageHandlers, text_message
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_pydantic_ai_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: text_message(item.id, "user", f"Our goal: {item.goal.objective}"),
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_attachment,  # async def decode_attachment(input) -> str | BinaryContent
+)
+```
+
+`MessageHandlers` supports `message`, `objective`, `goal` and `task`; handlers may be sync or
+async. Supplied handlers take precedence over cached/default rendering; returning `None` omits
+an item. Without an override the converter renders all supported types. Completed, attachment-free
+conversation messages are cached through the existing per-agent cache in bounded batches (100
+items or 1 MiB) as a small `{"id", "role", "text"}` JSON value; a cached entry is reused only
+when its id and role match. Files are hydrated afresh and never stored in the cache;
+objectives/goals/tasks remain live projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_pydantic_ai_tools(ctx.channel.current)` preserves the provider's descriptions and
+JSON schemas (via `Tool.from_schema`) and forwards Pydantic AI's `RunContext.tool_call_id` to
+Tilde's audited tool execution. It does not publish the model's final text. The agent chooses
+the provider tool and arguments, including routing fields required by that provider.
+Cancellation is enforced by the core: a stopped invocation refuses further tool RPCs.
+
+Override tool instructions with `instructions={"sendMessage": "..."}`, or change the channel
+tool's `description` before conversion. When combining namespaces, use `prefix="slack_"` (or
+another prefix) to keep model tool names distinct. Names are sanitized to `[a-zA-Z0-9_-]`;
+names over 64 characters are truncated with a stable hash suffix; conflicts raise.
+
+The core SDK exposes typed callable tools on `ctx.channel.slack`, `github`, `agentmail`, `linq`,
+`whatsapp`, `telnyx_whatsapp` and `native`. Use `ctx.channel.connections()` and
+`ctx.channel.for_connection(id)` when multiple connections use a provider. `ctx.channel.current`
+never falls back to a different connection when the inbound connection has no available tools.
+
+Cap a run with `usage_limits=UsageLimits(request_limit=8)` (or `tool_calls_limit`), the
+Pydantic AI equivalent of `stepCountIs`.
+
+## Bundled tools
+
+The agent's own Pydantic AI tools join Tilde's in one toolset:
+
+```python
+from pydantic_ai import Agent, Tool
+from tilde import BundledOptions
+from tilde_pydantic_ai import with_tilde_tools
+
+
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+toolset = await with_tilde_tools(
+    ctx, [Tool(roll_dice, metadata={"tilde": BundledOptions(summary="Rolled dice")})]
+)
+agent = Agent(model, toolsets=[toolset])
+```
+
+`with_tilde_tools` takes `Tool`s or plain functions and returns one toolset with the current
+channel's tools, `ctx.agent_tools` and the native tools. It publishes the native tools to Tilde
+with their parameter and return schemas, so `tools.search` finds them and a `tools.execute`
+naming one validates and runs it here within the run's `RunContext`; every call is audited once
+with the model's call id. `options={"roll_dice": BundledOptions(...)}` overrides
+`metadata["tilde"]`. A `ModelRetry` is audited as a failed call. Tools registered with
+`@agent.tool` are outside the toolset and are neither published nor audited.

trytilde_pydantic_ai-3.0.1/README.md

@@ -0,0 +1,129 @@
+# Pydantic AI adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+Pydantic AI `ModelMessage` history and channel tools to Pydantic AI tools, bundles an
+invocation's run options in `tilde_pydantic_ai(ctx)` and lets `tilde deploy` register a
+module-level agent's prompts.
+
+```python
+import tilde
+from pydantic_ai import Agent
+from pydantic_ai.usage import UsageLimits
+from tilde_pydantic_ai import convert_to_pydantic_ai_messages, tilde_pydantic_ai
+
+INFERENCE = tilde.inference("default")
+responder = Agent(model_using(INFERENCE), instructions="Respond using the channel's tools.")
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_pydantic_ai_messages(history.items, context=ctx)
+    await responder.run(
+        message_history=messages,
+        usage_limits=UsageLimits(request_limit=8),
+        **await tilde_pydantic_ai(ctx),
+    )
+```
+
+`tilde_pydantic_ai(ctx)` returns `capabilities=[TildeInvocation]` and a `cancellation_token`
+that a stop or suspension cancels. The per-run capability contributes the current channel's
+tools, enqueues input steered while the agent works after every graph node (`RunContext.enqueue`,
+delivered with the next model request), stamps the agent's dynamic instructions on its model
+calls and, since Pydantic AI has no native skills, adds `list_skills`/`read_skill` with the
+skills summary in the instructions (`skills=False` leaves them out).
+
+`tilde deploy` (entry point `tilde.discover`) registers each module-level `Agent`'s instructions
+and system prompts as `<name or variable>/instructions` and `<name>/system_prompt` (`/<n>` from 1
+when there are several): text is plain, `TemplateStr` is mustache and a function is dynamic with
+its source as the template. They are read from Pydantic AI's private fields (2.43); an
+unreadable agent is reported in the inventory.
+
+History pages are chronological; pass `before_message_id=history.next_page_token` for older
+messages. The latest page includes the current objective unless it already matches the latest
+received message. `include_objective=False` omits it. `include_work=True` also reads current
+goals/tasks and requires `work.read`. Only the acting agent's messages become `ModelResponse`
+items; everything else is a `ModelRequest` with a `UserPromptPart`. Messages whose status is
+not `complete` are skipped unless a custom `message` handler is given.
+
+Pydantic AI parts have no id field. Each converted message keeps its Tilde id in the
+application-level `metadata` (`{"tilde_message_id": ...}`, read it with `message_id(message)`);
+that metadata is never sent to the model.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and embedded as
+`BinaryContent`. Text files include their real content. Unsupported binary formats get an
+explicit attachment description; use `on_attachment` to parse them yourself. No private URL or
+credential needs to be exposed to the model. Converting a message with attachments without a
+`context` or custom handler raises instead of silently dropping the file.
+
+```python
+from tilde_pydantic_ai import MessageHandlers, text_message
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_pydantic_ai_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: text_message(item.id, "user", f"Our goal: {item.goal.objective}"),
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_attachment,  # async def decode_attachment(input) -> str | BinaryContent
+)
+```
+
+`MessageHandlers` supports `message`, `objective`, `goal` and `task`; handlers may be sync or
+async. Supplied handlers take precedence over cached/default rendering; returning `None` omits
+an item. Without an override the converter renders all supported types. Completed, attachment-free
+conversation messages are cached through the existing per-agent cache in bounded batches (100
+items or 1 MiB) as a small `{"id", "role", "text"}` JSON value; a cached entry is reused only
+when its id and role match. Files are hydrated afresh and never stored in the cache;
+objectives/goals/tasks remain live projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_pydantic_ai_tools(ctx.channel.current)` preserves the provider's descriptions and
+JSON schemas (via `Tool.from_schema`) and forwards Pydantic AI's `RunContext.tool_call_id` to
+Tilde's audited tool execution. It does not publish the model's final text. The agent chooses
+the provider tool and arguments, including routing fields required by that provider.
+Cancellation is enforced by the core: a stopped invocation refuses further tool RPCs.
+
+Override tool instructions with `instructions={"sendMessage": "..."}`, or change the channel
+tool's `description` before conversion. When combining namespaces, use `prefix="slack_"` (or
+another prefix) to keep model tool names distinct. Names are sanitized to `[a-zA-Z0-9_-]`;
+names over 64 characters are truncated with a stable hash suffix; conflicts raise.
+
+The core SDK exposes typed callable tools on `ctx.channel.slack`, `github`, `agentmail`, `linq`,
+`whatsapp`, `telnyx_whatsapp` and `native`. Use `ctx.channel.connections()` and
+`ctx.channel.for_connection(id)` when multiple connections use a provider. `ctx.channel.current`
+never falls back to a different connection when the inbound connection has no available tools.
+
+Cap a run with `usage_limits=UsageLimits(request_limit=8)` (or `tool_calls_limit`), the
+Pydantic AI equivalent of `stepCountIs`.
+
+## Bundled tools
+
+The agent's own Pydantic AI tools join Tilde's in one toolset:
+
+```python
+from pydantic_ai import Agent, Tool
+from tilde import BundledOptions
+from tilde_pydantic_ai import with_tilde_tools
+
+
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+toolset = await with_tilde_tools(
+    ctx, [Tool(roll_dice, metadata={"tilde": BundledOptions(summary="Rolled dice")})]
+)
+agent = Agent(model, toolsets=[toolset])
+```
+
+`with_tilde_tools` takes `Tool`s or plain functions and returns one toolset with the current
+channel's tools, `ctx.agent_tools` and the native tools. It publishes the native tools to Tilde
+with their parameter and return schemas, so `tools.search` finds them and a `tools.execute`
+naming one validates and runs it here within the run's `RunContext`; every call is audited once
+with the model's call id. `options={"roll_dice": BundledOptions(...)}` overrides
+`metadata["tilde"]`. A `ModelRetry` is audited as a failed call. Tools registered with
+`@agent.tool` are outside the toolset and are neither published nor audited.

trytilde_pydantic_ai-3.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "trytilde-pydantic-ai"
+version = "3.0.1"
+description = "Tilde adapter for Pydantic AI: typed context to model messages, channel tools to Pydantic AI tools"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = ["trytilde", "pydantic-ai-slim>=2,<3"]
+
+# `tilde deploy` reads module-level agents' prompts (and skill folders) through this discoverer.
+[project.entry-points."tilde.discover"]
+pydantic-ai = "tilde_pydantic_ai.discover:discover"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tilde_pydantic_ai"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tilde_pydantic_ai", "README.md"]

trytilde_pydantic_ai-3.0.1/src/tilde_pydantic_ai/__init__.py

@@ -0,0 +1,34 @@
+"""Tilde adapter for Pydantic AI: typed context to model messages, channel tools to tools, the
+per-run ``tilde_pydantic_ai`` capability and ``tilde deploy`` discovery of module-level agents."""
+
+from tilde_pydantic_ai.attachments import (
+    AttachmentConversion,
+    AttachmentHandler,
+    convert_attachment,
+)
+from tilde_pydantic_ai.discover import discover
+from tilde_pydantic_ai.invocation import TildeInvocation, tilde_pydantic_ai
+from tilde_pydantic_ai.messages import (
+    MESSAGE_ID_KEY,
+    MessageHandlers,
+    convert_to_pydantic_ai_messages,
+    message_id,
+    text_message,
+)
+from tilde_pydantic_ai.tools import convert_to_pydantic_ai_tools, with_tilde_tools
+
+__all__ = [
+    "MESSAGE_ID_KEY",
+    "AttachmentConversion",
+    "AttachmentHandler",
+    "MessageHandlers",
+    "TildeInvocation",
+    "convert_attachment",
+    "discover",
+    "convert_to_pydantic_ai_messages",
+    "convert_to_pydantic_ai_tools",
+    "message_id",
+    "text_message",
+    "tilde_pydantic_ai",
+    "with_tilde_tools",
+]

trytilde_pydantic_ai-3.0.1/src/tilde_pydantic_ai/attachments.py

@@ -0,0 +1,66 @@
+"""Attachment hydration: real file bytes for the model, never private URLs or credentials."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from pydantic_ai.messages import BinaryContent, UserContent
+
+from tilde import ConversationMessage, DownloadedAttachment
+from tilde.types.v1.chat_pb2 import Attachment
+
+
+@dataclass(slots=True)
+class AttachmentConversion:
+    message: ConversationMessage
+    attachment: Attachment
+    download: Callable[[], Awaitable[DownloadedAttachment]]
+    """Uses the current invocation's authenticated, thread-scoped attachment API."""
+
+
+AttachmentResult = UserContent | list[UserContent] | None
+AttachmentHandler = Callable[[AttachmentConversion], AttachmentResult | Awaitable[AttachmentResult]]
+
+_TEXT_TYPES = {"application/json", "application/xml"}
+_FILE_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp", "application/pdf"}
+_EXTENSIONS = {
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "png": "image/png",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "pdf": "application/pdf",
+    "txt": "text/plain",
+    "md": "text/plain",
+    "csv": "text/plain",
+    "log": "text/plain",
+    "json": "application/json",
+    "xml": "application/xml",
+}
+
+
+async def convert_attachment(input: AttachmentConversion) -> AttachmentResult:
+    """Hydrate images/PDFs as binary content and textual files as actual text, not filenames."""
+    attachment = input.attachment
+    media_type = normalize_media_type(attachment.media_type, attachment.filename)
+    text = media_type.startswith("text/") or media_type in _TEXT_TYPES
+    if not text and media_type not in _FILE_TYPES:
+        return (
+            f"Attached file: {attachment.filename} ({media_type}). "
+            "A custom attachment handler is needed to read this format."
+        )
+    result = await input.download()
+    if result.attachment.id != attachment.id:
+        raise RuntimeError("Attachment download returned a different file")
+    if text:
+        return f"Attached file: {attachment.filename}\n{result.content.decode('utf-8', 'replace')}"
+    return BinaryContent(result.content, media_type=media_type, identifier=attachment.filename)
+
+
+def normalize_media_type(value: str, filename: str) -> str:
+    kind = value.split(";")[0].strip().lower()
+    if kind and kind != "application/octet-stream":
+        return kind
+    extension = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    return _EXTENSIONS.get(extension, kind or "application/octet-stream")

trytilde_pydantic_ai-3.0.1/src/tilde_pydantic_ai/discover.py

@@ -0,0 +1,124 @@
+"""``tilde deploy`` discovery for Pydantic AI (entry point ``tilde.discover``).
+
+A module-level ``Agent`` registers its instructions and system prompts, named
+``<agent name or variable>/instructions`` and ``<agent>/system_prompt`` (``/<n>`` from 1 when
+there are several): literal text is plain, ``TemplateStr`` (Handlebars) is mustache and a
+function is dynamic with its source as the template; ``tilde_pydantic_ai`` stamps the dynamic ones
+on the run's model calls. Pydantic AI keeps them in private fields (``_instructions``,
+``_system_prompts``, ``_system_prompt_functions``, as of 2.43); an agent whose fields cannot be
+read is reported in the inventory.
+
+Tools are declared as ``with_tilde_tools`` publishes them: the agent's function tools
+(``tools=``, ``@agent.tool``; the private ``_function_toolset``) and a ``define_tools`` value of
+Pydantic AI ``Tool``s, or of plain functions when the project imports Pydantic AI.
+"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+from pydantic_ai import Agent, Tool
+from pydantic_ai.messages import InstructionPart
+from pydantic_ai.template import TemplateStr
+
+from tilde import BundledOptions, BundledTools
+from tilde.discovery import (
+    PROMPT_FORMAT_DYNAMIC,
+    PROMPT_FORMAT_MUSTACHE,
+    PROMPT_FORMAT_PLAIN,
+    Discovered,
+    DiscoveryContext,
+    declared_prompt,
+    declared_tool,
+)
+from tilde.management.v1.deployments_pb2 import DeclaredPrompt, DeclaredTool
+from tilde.prompts import valid_prompt_name
+from tilde_pydantic_ai.tools import describe_tool
+
+
+def discover(value: Any, context: DiscoveryContext) -> Discovered | None:
+    if isinstance(value, BundledTools):
+        return _bundled(value, context)
+    if not isinstance(value, Agent):
+        return None
+    file = Path(sys.modules[context.module].__file__ or "")
+    origin = f"{context.relative(file)}#{context.name}"
+    name = value.name or context.name
+    try:
+        tools = list(value._function_toolset.tools.values())
+    except AttributeError:
+        context.warn(f"Pydantic AI agent {name}: tools could not be read ({origin})")
+        tools = []
+    return Discovered(
+        prompts=agent_prompts(value, name, origin, context.warn),
+        tools=_declared(tools, None, f"{origin}.tools"),
+    )
+
+
+def _bundled(value: BundledTools, context: DiscoveryContext) -> Discovered | None:
+    if not all(isinstance(tool, Tool) or inspect.isroutine(tool) for tool in value.tools):
+        return None
+    # Plain functions alone could be another framework's.
+    ours = {"pydantic_ai", "tilde_pydantic_ai"} & context.imported or any(
+        isinstance(tool, Tool) for tool in value.tools
+    )
+    if not value.tools or not ours:
+        return None
+    tools = [tool if isinstance(tool, Tool) else Tool(tool) for tool in value.tools]
+    return Discovered(tools=_declared(tools, value.options, f"{context.origin()}.tools"))
+
+
+def _declared(
+    tools: list[Tool[Any]], options: Mapping[str, BundledOptions] | None, origin: str
+) -> list[DeclaredTool]:
+    return [declared_tool(describe_tool(tool, options), f"{origin}.{tool.name}") for tool in tools]
+
+
+def agent_prompts(
+    agent: Agent[Any, Any], name: str, origin: str, warn: Callable[[str], None]
+) -> list[DeclaredPrompt]:
+    """The agent's prompts; ``tilde_pydantic_ai`` calls this again at runtime for the stamps."""
+    try:
+        instructions = [sourced.instruction for sourced in agent._instructions]
+        system = [*agent._system_prompts]
+        system += [runner.function for runner in agent._system_prompt_functions]
+    except AttributeError:
+        warn(f"Pydantic AI agent {name}: instructions could not be read ({origin})")
+        return []
+    if not valid_prompt_name(name):
+        warn(f"Pydantic AI agent {name!r} cannot name a prompt; set Agent(name=...) ({origin})")
+        return []
+    prompts = []
+    for kind, values in (("instructions", instructions), ("system_prompt", system)):
+        for index, value in enumerate(values, 1):
+            key = f"{name}/{kind}" if len(values) == 1 else f"{name}/{kind}/{index}"
+            where = f"{origin}.{kind}" if len(values) == 1 else f"{origin}.{kind}[{index - 1}]"
+            prompt = _prompt(key, value, where, warn)
+            if prompt is not None:
+                prompts.append(prompt)
+    return prompts
+
+
+def _prompt(
+    name: str, value: Any, origin: str, warn: Callable[[str], None]
+) -> DeclaredPrompt | None:
+    if isinstance(value, str):
+        return declared_prompt(name, value, PROMPT_FORMAT_PLAIN, origin) if value else None
+    if isinstance(value, InstructionPart):
+        return declared_prompt(name, value.content, PROMPT_FORMAT_PLAIN, origin)
+    # TemplateStr is callable too; str() is its Handlebars source.
+    if isinstance(value, TemplateStr):
+        return declared_prompt(name, str(value), PROMPT_FORMAT_MUSTACHE, origin)
+    if callable(value):
+        try:
+            source = inspect.getsource(value)
+        except (OSError, TypeError):
+            warn(f"{origin}: the source of {name} could not be read; not registered")
+            return None
+        return declared_prompt(name, source, PROMPT_FORMAT_DYNAMIC, origin)
+    warn(f"{origin}: unsupported instruction {type(value).__name__}; not registered")
+    return None

trytilde_pydantic_ai-3.0.1/src/tilde_pydantic_ai/invocation.py

@@ -0,0 +1,79 @@
+"""The per-invocation pieces of a Pydantic AI run, as ``agent.run`` keyword arguments."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai import CancellationToken, RunContext
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.toolsets import AbstractToolset, CombinedToolset, FunctionToolset
+
+from tilde import AgentContext, BundledTools
+from tilde.discovery import PROMPT_FORMAT_DYNAMIC
+from tilde_pydantic_ai.discover import agent_prompts
+from tilde_pydantic_ai.tools import convert_to_pydantic_ai_tools, with_tilde_tools
+
+
+@dataclass
+class TildeInvocation(AbstractCapability[Any]):
+    """Per-run capability: Tilde tools, the skills summary, steering and dynamic prompt stamps.
+
+    Steering: after every graph node, newly steered input is enqueued (``RunContext.enqueue``)
+    and Pydantic AI delivers it as a user message with the next model request, or redirects a
+    run that would otherwise end into one more request.
+    """
+
+    context: AgentContext
+    toolset: AbstractToolset[Any]
+    skills: str | None = None
+
+    @classmethod
+    def get_serialization_name(cls) -> str | None:
+        return None  # holds the live invocation
+
+    def get_toolset(self) -> AbstractToolset[Any]:
+        return self.toolset
+
+    def get_instructions(self) -> str | None:
+        return self.skills
+
+    async def before_run(self, ctx: RunContext[Any]) -> None:
+        # `agent.run` has named an unnamed agent after its variable by now, as discovery did.
+        agent = ctx.agent
+        if agent is None or agent.name is None:
+            return
+        for prompt in agent_prompts(agent, agent.name, "", lambda _: None):
+            if prompt.format == PROMPT_FORMAT_DYNAMIC:
+                self.context.activate_prompt(prompt.name, prompt.hash)
+
+    async def after_node_run(self, ctx: RunContext[Any], *, node: Any, result: Any) -> Any:
+        for steered in self.context.take_inputs():
+            ctx.enqueue(steered.text)
+        return result
+
+
+async def tilde_pydantic_ai(
+    ctx: AgentContext, *, bundled: BundledTools | None = None, skills: bool = True
+) -> dict[str, Any]:
+    """``agent.run(..., **await tilde_pydantic_ai(ctx, bundled=TOOLS))``: the current channel's
+    tools, the agent's other Tilde tools, its bundled tools (``bundled``, from ``define_tools``,
+    audited and published as ``with_tilde_tools`` does), the invocation's cancellation,
+    steering, dynamic prompt stamps and, with ``skills``, the agent's skills (deployed and
+    registry-assigned) as ``list_skills``/``read_skill`` tools with a summary in the
+    instructions, since Pydantic AI has no native skills.
+    """
+    toolset = await with_tilde_tools(
+        ctx,
+        bundled.tools if bundled else [],
+        options=bundled.options if bundled else None,
+    )
+    summary = await ctx.skills.summary() if skills else ""
+    if summary:
+        toolset = CombinedToolset(
+            [toolset, FunctionToolset(convert_to_pydantic_ai_tools(ctx.skills.tools()))]
+        )
+    token = CancellationToken()
+    ctx.cancellation.on_abort(token.cancel)
+    capability = TildeInvocation(ctx, toolset, summary or None)
+    return {"capabilities": [capability], "cancellation_token": token}

trytilde_pydantic_ai-3.0.1/src/tilde_pydantic_ai/messages.py

@@ -0,0 +1,215 @@
+"""Convert typed Tilde context into Pydantic AI model messages for ``message_history``.
+
+User-role items become ``ModelRequest(parts=[UserPromptPart(...)])`` and the acting agent's own
+messages become ``ModelResponse(parts=[TextPart(...)])``. Pydantic AI parts carry no id, so the
+Tilde message id is stored in each message's application-level ``metadata`` (never sent to the
+model) as ``{"tilde_message_id": id}`` and in the cached ``{"id", "role", "text"}`` representation.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from pydantic_ai.messages import (
+    BinaryContent,
+    FilePart,
+    ModelMessage,
+    ModelRequest,
+    ModelResponse,
+    TextPart,
+    UserContent,
+    UserPromptPart,
+)
+
+from tilde import (
+    AgentContext,
+    ContextMessage,
+    ConversationMessage,
+    GoalMessage,
+    ObjectiveMessage,
+    TaskMessage,
+)
+from tilde_pydantic_ai.attachments import (
+    AttachmentConversion,
+    AttachmentHandler,
+    convert_attachment,
+)
+
+MESSAGE_ID_KEY = "tilde_message_id"
+_MAX_BYTES = 1024 * 1024
+_MAX_ITEMS = 100
+
+Converted = ModelMessage | None
+Handler = Callable[[Any], Converted | Awaitable[Converted]]
+
+
+@dataclass(slots=True)
+class MessageHandlers:
+    """Explicit handlers take precedence over cached and default rendering; None omits an item."""
+
+    message: Callable[[ConversationMessage], Converted | Awaitable[Converted]] | None = None
+    objective: Callable[[ObjectiveMessage], Converted | Awaitable[Converted]] | None = None
+    goal: Callable[[GoalMessage], Converted | Awaitable[Converted]] | None = None
+    task: Callable[[TaskMessage], Converted | Awaitable[Converted]] | None = None
+
+
+def text_message(id: str, role: Literal["user", "assistant"], text: str) -> ModelMessage:
+    """A single-text message tagged with its Tilde id, the shape the converter caches."""
+    return _build(id, role, [text])
+
+
+def message_id(message: ModelMessage) -> str | None:
+    """The Tilde message id a converted message came from, if it carries one."""
+    return (message.metadata or {}).get(MESSAGE_ID_KEY)
+
+
+async def convert_to_pydantic_ai_messages(
+    messages: Iterable[ContextMessage],
+    *,
+    context: AgentContext | None = None,
+    on_message: MessageHandlers | None = None,
+    on_attachment: AttachmentHandler | None = None,
+) -> list[ModelMessage]:
+    """Convert typed SDK context into ``ModelMessage`` history for ``Agent.run``."""
+    output: list[ModelMessage] = []
+    batch: list[tuple[str, Any]] = []
+    batch_bytes = 0
+
+    async def flush() -> None:
+        nonlocal batch_bytes
+        if batch and context is not None:
+            await context.cache_converted_messages(batch[:])
+            batch.clear()
+        batch_bytes = 0
+
+    handlers = on_message or MessageHandlers()
+    for item in messages:
+        if (
+            item.type == "message"
+            and item.message.status != "complete"
+            and handlers.message is None
+        ):
+            continue
+        converted: ModelMessage | None
+        cacheable = False
+        if item.type == "objective":
+            converted = (
+                await _call(handlers.objective, item)
+                if handlers.objective
+                else text_message(item.id, "user", item.objective)
+            )
+        elif item.type == "goal":
+            converted = (
+                await _call(handlers.goal, item)
+                if handlers.goal
+                else text_message(
+                    item.id, "user", f"Goal ({item.goal.status}): {item.goal.objective}"
+                )
+            )
+        elif item.type == "task":
+            if handlers.task:
+                converted = await _call(handlers.task, item)
+            else:
+                text = f"Task ({item.task.status}): {item.task.title}"
+                if item.task.blocked_reason:
+                    text += f"\nBlocked: {item.task.blocked_reason}"
+                converted = text_message(item.id, "user", text)
+        elif handlers.message:
+            converted = await _call(handlers.message, item)
+        else:
+            # File bytes are hydrated afresh through the scoped SDK, never replayed from the cache.
+            converted = _hydrate(item) if not item.message.attachments else None
+            if converted is None:
+                converted = await _render(item, context, on_attachment)
+                cacheable = item.message.status == "complete" and not item.message.attachments
+        if converted is None:
+            continue
+        output.append(converted)
+        # Only canonical messages can be cached by the runtime. Work state is always current,
+        # and hydrated files must not duplicate large/sensitive attachment bytes in the cache.
+        if context is None or not cacheable:
+            continue
+        entry = {"id": item.id, "role": item.role, "text": _text_of(converted)}
+        size = len(json.dumps(entry).encode())
+        if size > _MAX_BYTES:
+            continue
+        if len(batch) == _MAX_ITEMS or batch_bytes + size > _MAX_BYTES:
+            await flush()
+        batch.append((item.id, entry))
+        batch_bytes += size
+    await flush()
+    return output
+
+
+async def _call(handler: Handler, item: ContextMessage) -> Converted:
+    result = handler(item)
+    return await result if inspect.isawaitable(result) else result
+
+
+async def _render(
+    item: ConversationMessage,
+    context: AgentContext | None,
+    on_attachment: AttachmentHandler | None,
+) -> ModelMessage | None:
+    content: list[UserContent] = []
+    if item.message.HasField("subject") and item.message.subject:
+        content.append(f"Subject: {item.message.subject}")
+    if item.message.text:
+        content.append(item.message.text)
+    for attachment in item.message.attachments:
+
+        async def download(attachment=attachment):
+            if context is None:
+                raise RuntimeError(
+                    "Attachment conversion requires context or a custom on_attachment handler"
+                )
+            return await context.attachments.download(attachment.id)
+
+        result = (on_attachment or convert_attachment)(
+            AttachmentConversion(message=item, attachment=attachment, download=download)
+        )
+        if inspect.isawaitable(result):
+            result = await result
+        if result is None:
+            continue
+        content.extend(result if isinstance(result, list) else [result])
+    return _build(item.id, item.role, content) if content else None
+
+
+def _build(id: str, role: Literal["user", "assistant"], content: list[UserContent]) -> ModelMessage:
+    metadata = {MESSAGE_ID_KEY: id}
+    if role == "assistant":
+        parts = [
+            FilePart(content=part) if isinstance(part, BinaryContent) else TextPart(str(part))
+            for part in content
+        ]
+        return ModelResponse(parts=parts, metadata=metadata)
+    prompt = content[0] if len(content) == 1 and isinstance(content[0], str) else content
+    return ModelRequest(parts=[UserPromptPart(prompt)], metadata=metadata)
+
+
+def _hydrate(item: ConversationMessage) -> ModelMessage | None:
+    cached = item.cached_agent_representation
+    if (
+        not isinstance(cached, dict)
+        or cached.get("id") != item.id
+        or cached.get("role") != item.role
+        or not isinstance(cached.get("text"), str)
+    ):
+        return None
+    return text_message(item.id, item.role, cached["text"])
+
+
+def _text_of(message: ModelMessage) -> str:
+    texts: list[str] = []
+    for part in message.parts:
+        if isinstance(part, TextPart):
+            texts.append(part.content)
+        elif isinstance(part, UserPromptPart):
+            content = [part.content] if isinstance(part.content, str) else part.content
+            texts.extend(piece for piece in content if isinstance(piece, str))
+    return "\n".join(texts)

trytilde_pydantic_ai-3.0.1/src/tilde_pydantic_ai/tools.py

@@ -0,0 +1,156 @@
+"""Expose Tilde channel tools to Pydantic AI without altering provider schemas or authorization,
+and publish the agent's own Pydantic AI tools to Tilde as bundled tools."""
+
+from __future__ import annotations
+
+import inspect
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from contextvars import ContextVar
+from dataclasses import dataclass, replace
+from typing import Any
+
+from pydantic_ai import RunContext
+from pydantic_ai.tools import Tool
+from pydantic_ai.toolsets import AbstractToolset, FunctionToolset, WrapperToolset
+from pydantic_ai.toolsets.abstract import ToolsetTool
+
+from tilde import AgentContext, BundledOptions, ChannelTool
+from tilde import Tool as TildeTool
+from tilde._tools import ToolSpec, bundled_tool, model_tool_name, tool_spec
+
+# The RunContext of the Tilde tool being executed; a routed tools.execute runs within it.
+_RUN_CONTEXT: ContextVar[RunContext[Any]] = ContextVar("tilde_pydantic_ai_run_context")
+
+
+def convert_to_pydantic_ai_tools(
+    channels: Mapping[str, ChannelTool | TildeTool],
+    *,
+    instructions: Mapping[str, str] | None = None,
+    prefix: str = "",
+) -> list[Tool[Any]]:
+    """Preserve provider schemas and forward the model's tool-call id to Tilde's audited execution.
+
+    ``instructions`` overrides provider descriptions by channel tool name; ``prefix`` namespaces
+    model tool names when combining several channel collections. Pass the result as ``tools=``
+    to ``Agent``.
+    """
+    result: list[Tool[Any]] = []
+    seen: set[str] = set()
+    for name, channel in channels.items():
+        key = model_tool_name(f"{prefix}{name}")
+        if not key or key in seen:
+            raise ValueError("Conflicting or invalid model tool names")
+        seen.add(key)
+        description = (
+            instructions[name] if instructions and name in instructions else channel.description
+        )
+        result.append(
+            Tool.from_schema(
+                _execute(channel),
+                name=key,
+                description=description,
+                json_schema=channel.input_schema,
+                takes_ctx=True,
+            )
+        )
+    return result
+
+
+def _execute(channel: ChannelTool | TildeTool):
+    # Pydantic AI sets RunContext.tool_call_id to the model's call id before invoking a tool
+    # function that takes the context; the schema's fields arrive as keyword arguments.
+    async def execute(ctx: RunContext[Any], /, **arguments: Any) -> Any:
+        token = _RUN_CONTEXT.set(ctx)
+        try:
+            return await channel.execute(arguments, tool_call_id=ctx.tool_call_id)
+        finally:
+            _RUN_CONTEXT.reset(token)
+
+    return execute
+
+
+async def with_tilde_tools(
+    ctx: AgentContext,
+    native_tools: Sequence[Tool[Any] | Callable[..., Any]],
+    *,
+    options: Mapping[str, BundledOptions] | None = None,
+) -> AbstractToolset[Any]:
+    """One toolset with the current channel's tools, the agent's other Tilde tools and its own
+    tools, for ``Agent(toolsets=[...])``.
+
+    ``native_tools`` are ``Tool`` instances or plain functions (``takes_ctx`` inferred). Each is
+    published to Tilde with its name, description, parameter and return schemas, so
+    ``tools.search`` finds it and a ``tools.execute`` naming it runs it here; every call is
+    audited once with the model's call id. Tilde metadata comes from
+    ``Tool(..., metadata={"tilde": BundledOptions(...)})`` or ``options[name]``, which wins.
+    Call it once per invocation.
+
+    Caveats: tools registered with ``@agent.tool`` are outside this toolset and are neither
+    published nor audited; a ``ModelRetry`` is audited as a failed call; a tool's ``prepare``
+    function does not change what is published.
+    """
+    tools = [tool if isinstance(tool, Tool) else Tool(tool) for tool in native_tools]
+    channel_tools = convert_to_pydantic_ai_tools({**ctx.channel.current, **ctx.agent_tools})
+    toolset = _AuditedToolset(
+        FunctionToolset([*channel_tools, *tools]),
+        tilde=ctx,
+        bundled=frozenset(tool.name for tool in tools),
+    )
+    definitions = {
+        tool.name: bundled_tool(describe_tool(tool, options), _route(toolset, tool.name))
+        for tool in tools
+    }
+    # Published even when empty, so tools removed since the last call stop running here.
+    await ctx._set_bundled_tools(definitions)
+    return toolset
+
+
+def describe_tool(tool: Tool[Any], options: Mapping[str, BundledOptions] | None = None) -> ToolSpec:
+    """What ``with_tilde_tools`` publishes and ``tilde deploy`` declares for one tool."""
+    definition = tool.tool_def
+    declared = (definition.metadata or {}).get("tilde")
+    return tool_spec(
+        tool.name,
+        definition.description or "",
+        definition.parameters_json_schema,
+        output_schema=definition.return_schema,
+        options=(options or {}).get(tool.name, declared),
+    )
+
+
+@dataclass
+class _AuditedToolset(WrapperToolset[Any]):
+    tilde: AgentContext
+    bundled: frozenset[str]
+
+    async def call_tool(
+        self, name: str, tool_args: dict[str, Any], ctx: RunContext[Any], tool: ToolsetTool[Any]
+    ) -> Any:
+        if name not in self.bundled:
+            return await super().call_tool(name, tool_args, ctx, tool)
+        return await self.tilde._run_audited(
+            name,
+            ctx.tool_call_id or str(uuid.uuid4()),
+            tool_args,
+            lambda: super(_AuditedToolset, self).call_tool(name, tool_args, ctx, tool),
+        )
+
+
+def _route(toolset: _AuditedToolset, name: str):
+    # A tools.execute naming this tool: validate and call it as Pydantic AI would, within the
+    # tools.execute call's RunContext, so the audited call_tool above reports it once.
+    async def execute(input: Any, call: str) -> Any:
+        run = _RUN_CONTEXT.get(None)
+        if run is None:
+            raise RuntimeError(f"{name} runs through tools.execute only inside a Pydantic AI run")
+        step = replace(run, tool_name=name, tool_call_id=call)
+        tool = (await toolset.get_tools(step))[name]
+        args = tool.args_validator.validate_python(input)
+        if tool.args_validator_func is not None:
+            checked = tool.args_validator_func(step, **args)
+            if inspect.isawaitable(checked):
+                await checked
+        return await toolset.call_tool(name, args, step, tool)
+
+    return execute