trytilde-crewai 3.0.1__tar.gz

trytilde_crewai-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_crewai-3.0.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: trytilde-crewai
+Version: 3.0.1
+Summary: Tilde adapter for CrewAI: convert invocation history to CrewAI messages and channel tools to CrewAI tools
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: crewai<2,>=1.15
+Requires-Dist: pyyaml>=6
+Requires-Dist: trytilde
+Description-Content-Type: text/markdown
+
+# CrewAI adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+CrewAI messages and channel tools to CrewAI tools, following Tilde's core/framework
+separation.
+
+```python
+import tilde
+from crewai import LLM, Agent
+from crewai.project import CrewBase, agent
+from tilde_crewai import convert_to_crewai_messages, convert_to_crewai_tools, inference_interceptor
+
+INFERENCE = tilde.inference("default")
+llm = LLM(
+    model="openai/gpt-4o-mini",
+    base_url=INFERENCE.base_url,
+    api_key=INFERENCE.api_key,
+    interceptor=inference_interceptor(INFERENCE),
+)
+
+
+@CrewBase
+class SupportCrew:
+    agents_config = "config/agents.yaml"  # role/goal/backstory, registered by `tilde deploy`
+
+    def __init__(self, tools):
+        self.tools = tools
+
+    @agent
+    def support(self) -> Agent:
+        return Agent(config=self.agents_config["support"], llm=llm, tools=self.tools, max_iter=8)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_crewai_messages(history.items, context=ctx)
+    await (
+        SupportCrew(convert_to_crewai_tools(ctx.channel.current)).support().kickoff_async(messages)
+    )
+```
+
+## Deploy discovery, inference and steering
+
+This package registers a `tilde.discover` entry point, so `python -m tilde deploy` recognises
+`@CrewBase` classes (or instances) and reads their YAML raw, before CrewAI interpolates inputs:
+agent `role`/`goal`/`backstory` become prompts `agents/<key>/<field>` and task
+`description`/`expected_output` become `tasks/<key>/<field>`, in braces format when the text
+holds a `{variable}`, with origin `<yaml path>#<key>.<field>`. Skill search paths listed under
+an agent's `skills:` in the YAML are shipped too (resolved from the working directory, as CrewAI
+does); skills passed in code are not visible without instantiating, so declare them with
+`tilde.define_skills(...)` and pass `.path`. Agents built in code at module scope are reported
+as warnings.
+
+The LLM is built once at module scope: `inference_interceptor` stamps each request with the
+running invocation's token and prompt stamps and sends it to that invocation's gateway. Importing
+`tilde_crewai` registers a global `before_llm_call` hook that appends the invocation's newly
+steered input (`ctx.take_inputs()`) as user messages before each model call; outside an
+invocation it does nothing.
+
+Skills assigned to the agent in Tilde (not shipped with the deployment) reach running
+deployments through CrewAI's own skill discovery: give the per-invocation agent
+`skills=[SKILLS.path, Path(await ctx.skills.directory())]`. The directory holds one folder per
+registry skill, cached by version, so a skill assigned in the UI is used on the next invocation.
+
+Set `CREWAI_DISABLE_TELEMETRY=true` in the environment before `crewai` is imported to turn
+off CrewAI's anonymous telemetry. `OTEL_SDK_DISABLED=true` has the same effect but also
+disables your own OpenTelemetry SDK, so prefer the CrewAI flag. `max_iter` caps the agent's
+model/tool iterations. Leave agent `memory` off; Tilde owns the history.
+
+The converted list is passed to `kickoff_async`. CrewAI messages are OpenAI-style
+`{"role", "content"}` dicts (`crewai.utilities.types.LLMMessage`) and carry no id. Every message
+keeps its role as conversation history, except the last `user` message: CrewAI collapses it to
+text and promotes it into its task prompt (`Current Task: ...`). Content parts on that message
+would be dropped, so when it carries media the converter appends a short text request
+(`tilde_crewai.messages.MEDIA_REQUEST`) to be promoted in its place.
+
+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 receive the assistant
+role.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and attached as content
+parts with base64 data URLs. 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. CrewAI has no media type for history and
+passes content parts to the provider unchanged, so the default parts are the OpenAI Chat
+Completions shapes (`image_url`, `file`), CrewAI's default OpenAI API. For the Responses API
+or another provider, return that provider's part from `on_attachment`. CrewAI's own `files`
+message field is not used: it needs the optional `crewai-files` extra.
+
+```python
+from tilde_crewai import MessageHandlers
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_crewai_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: {"role": "user", "content": f"Our goal: {item.goal.objective}"},
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_your_format,  # (conversion) -> str | content part dict | list | None
+)
+```
+
+`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
+conversation conversions use the existing per-agent cache, in bounded batches. Files are
+hydrated afresh and are never stored in the cache; objectives/goals/tasks remain live
+projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_crewai_tools(ctx.channel.current)` returns `crewai.tools.BaseTool` instances that
+keep the provider's descriptions and JSON schemas. CrewAI reads tool parameters from a pydantic
+`args_schema`; the adapter supplies a field-less model whose `model_json_schema()` returns the
+provider schema, so nothing is introspected and arguments reach the channel exactly as the
+model sent them. The adapter does not publish the model's final text. The agent chooses the
+provider tool and arguments, including routing fields required by that provider.
+
+CrewAI itself changes three things that an adapter cannot turn off:
+
+- Every tool schema goes through its OpenAI strict-mode pass before it reaches the model:
+  all properties of every object become `required`, objects get
+  `additionalProperties: false`, `oneOf` becomes `anyOf`, `$ref`s are inlined and unsupported
+  `format`s are removed. Types, nesting, enums and descriptions are preserved. The model must
+  therefore supply a value for optional provider fields.
+- Model-facing names are lowercased snake_case (`sendMessage` becomes `send_message`).
+  Conflicts are checked on that name.
+- The model's tool-call id is not passed to tools, hooks or events, so it cannot be forwarded.
+  Tilde's core generates a UUID per execution; audited tool-call ids do not match the
+  provider's ids.
+
+CrewAI executes tools synchronously on worker threads. Channel execution belongs to the
+invocation's event loop, so call `convert_to_crewai_tools` on that loop (inside your `run`
+handler): the tools capture it and submit each execution back to it, blocking only the worker
+thread. `await tool.arun(...)` runs directly on the loop. Results are returned to the model as
+JSON. CrewAI's tool-result cache is opt-in; leave it off so repeated sends are executed.
+
+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_-]` and
+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.
+
+## Bundled tools
+
+The agent's own CrewAI tools join Tilde's with one call, on the invocation's event loop:
+
+```python
+from crewai.tools import tool
+from tilde import BundledOptions
+from tilde_crewai import with_tilde_tools
+
+
+@tool("roll_dice")
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+tools = await with_tilde_tools(
+    ctx, [roll_dice], options={"roll_dice": BundledOptions(summary="Rolled dice")}
+)
+agent = Agent(role="Assistant", goal="Help", backstory="...", llm=llm, tools=tools)
+```
+
+`with_tilde_tools` returns the current channel's tools, `ctx.agent_tools` and a delegating tool
+per native tool that keeps its schemas, `result_as_answer`, usage limit, cache function and
+failure policy. The native tools are published to Tilde under the name CrewAI shows the model
+(`sanitize_tool_name`), so `tools.search` finds them and a `tools.execute` naming one runs it
+here. Every call is audited once on the event loop. CrewAI has no free metadata, so summaries
+come from `options`, keyed by the tool's own name. CrewAI never passes the model's tool-call id
+to tools, so direct calls are audited under a generated id; `tools.execute` calls are not counted
+towards the usage limit.

trytilde_crewai-3.0.1/README.md

@@ -0,0 +1,180 @@
+# CrewAI adapter
+
+Core history and delivery live in `trytilde`. This package converts typed context to
+CrewAI messages and channel tools to CrewAI tools, following Tilde's core/framework
+separation.
+
+```python
+import tilde
+from crewai import LLM, Agent
+from crewai.project import CrewBase, agent
+from tilde_crewai import convert_to_crewai_messages, convert_to_crewai_tools, inference_interceptor
+
+INFERENCE = tilde.inference("default")
+llm = LLM(
+    model="openai/gpt-4o-mini",
+    base_url=INFERENCE.base_url,
+    api_key=INFERENCE.api_key,
+    interceptor=inference_interceptor(INFERENCE),
+)
+
+
+@CrewBase
+class SupportCrew:
+    agents_config = "config/agents.yaml"  # role/goal/backstory, registered by `tilde deploy`
+
+    def __init__(self, tools):
+        self.tools = tools
+
+    @agent
+    def support(self) -> Agent:
+        return Agent(config=self.agents_config["support"], llm=llm, tools=self.tools, max_iter=8)
+
+
+async def run(ctx):
+    history = await ctx.message.history()
+    messages = await convert_to_crewai_messages(history.items, context=ctx)
+    await (
+        SupportCrew(convert_to_crewai_tools(ctx.channel.current)).support().kickoff_async(messages)
+    )
+```
+
+## Deploy discovery, inference and steering
+
+This package registers a `tilde.discover` entry point, so `python -m tilde deploy` recognises
+`@CrewBase` classes (or instances) and reads their YAML raw, before CrewAI interpolates inputs:
+agent `role`/`goal`/`backstory` become prompts `agents/<key>/<field>` and task
+`description`/`expected_output` become `tasks/<key>/<field>`, in braces format when the text
+holds a `{variable}`, with origin `<yaml path>#<key>.<field>`. Skill search paths listed under
+an agent's `skills:` in the YAML are shipped too (resolved from the working directory, as CrewAI
+does); skills passed in code are not visible without instantiating, so declare them with
+`tilde.define_skills(...)` and pass `.path`. Agents built in code at module scope are reported
+as warnings.
+
+The LLM is built once at module scope: `inference_interceptor` stamps each request with the
+running invocation's token and prompt stamps and sends it to that invocation's gateway. Importing
+`tilde_crewai` registers a global `before_llm_call` hook that appends the invocation's newly
+steered input (`ctx.take_inputs()`) as user messages before each model call; outside an
+invocation it does nothing.
+
+Skills assigned to the agent in Tilde (not shipped with the deployment) reach running
+deployments through CrewAI's own skill discovery: give the per-invocation agent
+`skills=[SKILLS.path, Path(await ctx.skills.directory())]`. The directory holds one folder per
+registry skill, cached by version, so a skill assigned in the UI is used on the next invocation.
+
+Set `CREWAI_DISABLE_TELEMETRY=true` in the environment before `crewai` is imported to turn
+off CrewAI's anonymous telemetry. `OTEL_SDK_DISABLED=true` has the same effect but also
+disables your own OpenTelemetry SDK, so prefer the CrewAI flag. `max_iter` caps the agent's
+model/tool iterations. Leave agent `memory` off; Tilde owns the history.
+
+The converted list is passed to `kickoff_async`. CrewAI messages are OpenAI-style
+`{"role", "content"}` dicts (`crewai.utilities.types.LLMMessage`) and carry no id. Every message
+keeps its role as conversation history, except the last `user` message: CrewAI collapses it to
+text and promotes it into its task prompt (`Current Task: ...`). Content parts on that message
+would be dropped, so when it carries media the converter appends a short text request
+(`tilde_crewai.messages.MEDIA_REQUEST`) to be promoted in its place.
+
+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 receive the assistant
+role.
+
+Images and PDFs are downloaded through `ctx.attachments.download` and attached as content
+parts with base64 data URLs. 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. CrewAI has no media type for history and
+passes content parts to the provider unchanged, so the default parts are the OpenAI Chat
+Completions shapes (`image_url`, `file`), CrewAI's default OpenAI API. For the Responses API
+or another provider, return that provider's part from `on_attachment`. CrewAI's own `files`
+message field is not used: it needs the optional `crewai-files` extra.
+
+```python
+from tilde_crewai import MessageHandlers
+
+history = await ctx.message.history(include_work=True)
+messages = await convert_to_crewai_messages(
+    history.items,
+    context=ctx,
+    on_message=MessageHandlers(
+        goal=lambda item: {"role": "user", "content": f"Our goal: {item.goal.objective}"},
+        task=lambda item: None,  # Omit this type, or provide a different rendering.
+    ),
+    on_attachment=decode_your_format,  # (conversion) -> str | content part dict | list | None
+)
+```
+
+`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
+conversation conversions use the existing per-agent cache, in bounded batches. Files are
+hydrated afresh and are never stored in the cache; objectives/goals/tasks remain live
+projections rather than cached chat records.
+
+## Channel tools
+
+`convert_to_crewai_tools(ctx.channel.current)` returns `crewai.tools.BaseTool` instances that
+keep the provider's descriptions and JSON schemas. CrewAI reads tool parameters from a pydantic
+`args_schema`; the adapter supplies a field-less model whose `model_json_schema()` returns the
+provider schema, so nothing is introspected and arguments reach the channel exactly as the
+model sent them. The adapter does not publish the model's final text. The agent chooses the
+provider tool and arguments, including routing fields required by that provider.
+
+CrewAI itself changes three things that an adapter cannot turn off:
+
+- Every tool schema goes through its OpenAI strict-mode pass before it reaches the model:
+  all properties of every object become `required`, objects get
+  `additionalProperties: false`, `oneOf` becomes `anyOf`, `$ref`s are inlined and unsupported
+  `format`s are removed. Types, nesting, enums and descriptions are preserved. The model must
+  therefore supply a value for optional provider fields.
+- Model-facing names are lowercased snake_case (`sendMessage` becomes `send_message`).
+  Conflicts are checked on that name.
+- The model's tool-call id is not passed to tools, hooks or events, so it cannot be forwarded.
+  Tilde's core generates a UUID per execution; audited tool-call ids do not match the
+  provider's ids.
+
+CrewAI executes tools synchronously on worker threads. Channel execution belongs to the
+invocation's event loop, so call `convert_to_crewai_tools` on that loop (inside your `run`
+handler): the tools capture it and submit each execution back to it, blocking only the worker
+thread. `await tool.arun(...)` runs directly on the loop. Results are returned to the model as
+JSON. CrewAI's tool-result cache is opt-in; leave it off so repeated sends are executed.
+
+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_-]` and
+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.
+
+## Bundled tools
+
+The agent's own CrewAI tools join Tilde's with one call, on the invocation's event loop:
+
+```python
+from crewai.tools import tool
+from tilde import BundledOptions
+from tilde_crewai import with_tilde_tools
+
+
+@tool("roll_dice")
+def roll_dice(count: int = 1) -> list[int]:
+    """Roll six-sided dice."""
+    return [random.randint(1, 6) for _ in range(count)]
+
+
+tools = await with_tilde_tools(
+    ctx, [roll_dice], options={"roll_dice": BundledOptions(summary="Rolled dice")}
+)
+agent = Agent(role="Assistant", goal="Help", backstory="...", llm=llm, tools=tools)
+```
+
+`with_tilde_tools` returns the current channel's tools, `ctx.agent_tools` and a delegating tool
+per native tool that keeps its schemas, `result_as_answer`, usage limit, cache function and
+failure policy. The native tools are published to Tilde under the name CrewAI shows the model
+(`sanitize_tool_name`), so `tools.search` finds them and a `tools.execute` naming one runs it
+here. Every call is audited once on the event loop. CrewAI has no free metadata, so summaries
+come from `options`, keyed by the tool's own name. CrewAI never passes the model's tool-call id
+to tools, so direct calls are audited under a generated id; `tools.execute` calls are not counted
+towards the usage limit.

trytilde_crewai-3.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "trytilde-crewai"
+version = "3.0.1"
+description = "Tilde adapter for CrewAI: convert invocation history to CrewAI messages and channel tools to CrewAI tools"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = ["trytilde", "crewai>=1.15,<2", "pyyaml>=6"]
+
+# `tilde deploy` reads @CrewBase YAML prompts and skills through this discoverer.
+[project.entry-points."tilde.discover"]
+crewai = "tilde_crewai.discover:discover"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tilde_crewai"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tilde_crewai", "README.md"]

trytilde_crewai-3.0.1/src/tilde_crewai/__init__.py

@@ -0,0 +1,35 @@
+"""Tilde adapter for CrewAI: typed context to CrewAI messages, channel tools to CrewAI tools,
+the inference gateway through a transport interceptor, steering through a global
+``before_llm_call`` hook (registered on import) and ``tilde deploy`` discovery of
+``@CrewBase`` YAML prompts."""
+
+from tilde_crewai.attachments import (
+    AttachmentConversion,
+    AttachmentHandler,
+    AttachmentPart,
+    AttachmentResult,
+    convert_attachment,
+    normalize_media_type,
+)
+from tilde_crewai.discover import discover
+from tilde_crewai.inference import InferenceInterceptor, inference_interceptor
+from tilde_crewai.messages import MessageHandlers, convert_to_crewai_messages
+from tilde_crewai.steering import inject_steering
+from tilde_crewai.tools import convert_to_crewai_tools, with_tilde_tools
+
+__all__ = [
+    "AttachmentConversion",
+    "AttachmentHandler",
+    "AttachmentPart",
+    "AttachmentResult",
+    "InferenceInterceptor",
+    "MessageHandlers",
+    "convert_attachment",
+    "convert_to_crewai_messages",
+    "convert_to_crewai_tools",
+    "discover",
+    "inference_interceptor",
+    "inject_steering",
+    "normalize_media_type",
+    "with_tilde_tools",
+]

trytilde_crewai-3.0.1/src/tilde_crewai/attachments.py

@@ -0,0 +1,79 @@
+"""Default attachment hydration: images and PDFs become content parts, text files become text.
+
+CrewAI has no media type of its own for conversation history; its LLM layer passes a message's
+content-part list to the provider unchanged. The parts built here are the OpenAI Chat
+Completions shapes (``image_url`` and ``file`` with base64 data URLs), CrewAI's default OpenAI
+API. For another provider, return that provider's part from a custom ``on_attachment``.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from tilde import ConversationMessage, DownloadedAttachment
+from tilde.types.v1.chat_pb2 import Attachment
+
+# A string is rendered as text; a dict is passed through as a provider content part.
+AttachmentPart = str | dict[str, Any]
+AttachmentResult = AttachmentPart | list[AttachmentPart] | None
+
+
+@dataclass(slots=True)
+class AttachmentConversion:
+    message: ConversationMessage
+    attachment: Attachment
+    # Uses the current invocation's authenticated, thread-scoped attachment API.
+    download: Callable[[], Awaitable[DownloadedAttachment]]
+
+
+AttachmentHandler = Callable[[AttachmentConversion], AttachmentResult | Awaitable[AttachmentResult]]
+
+_TEXT_TYPES = {"application/json", "application/xml"}
+_IMAGE_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp"}
+_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 content parts and textual files as their actual text."""
+    attachment = input.attachment
+    media_type = normalize_media_type(attachment.media_type, attachment.filename)
+    text = media_type.startswith("text/") or media_type in _TEXT_TYPES
+    image = media_type in _IMAGE_TYPES
+    if not text and not image and media_type != "application/pdf":
+        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')}"
+    data_url = f"data:{media_type};base64,{base64.b64encode(result.content).decode('ascii')}"
+    if image:
+        return {"type": "image_url", "image_url": {"url": data_url}}
+    return {"type": "file", "file": {"filename": attachment.filename, "file_data": data_url}}
+
+
+def normalize_media_type(value: str, filename: str) -> str:
+    media_type = value.split(";")[0].strip().lower()
+    if media_type and media_type != "application/octet-stream":
+        return media_type
+    extension = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    return _EXTENSIONS.get(extension, media_type or "application/octet-stream")

trytilde_crewai-3.0.1/src/tilde_crewai/discover.py

@@ -0,0 +1,124 @@
+"""``tilde deploy`` discovery for CrewAI (entry point ``tilde.discover``).
+
+``@CrewBase`` classes keep their YAML config paths relative to the class file
+(``base_directory`` / ``original_agents_config_path``). The YAML is read raw, before CrewAI
+interpolates inputs: each agent ``role``/``goal``/``backstory`` becomes the prompt
+``agents/<key>/<field>`` and each task ``description``/``expected_output`` becomes
+``tasks/<key>/<field>``, in braces format when it holds a ``{variable}``. Skill search paths
+listed under an agent's ``skills:`` resolve from the working directory, as CrewAI resolves them.
+Nothing is instantiated, so tools given to agents in ``@agent`` methods are not seen; a
+``define_tools`` value of CrewAI tools, and the tools of a module-level agent, are declared as
+``with_tilde_tools`` publishes them.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import yaml
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from crewai.tools import BaseTool
+
+from tilde import BundledOptions, BundledTools, SkillDefinition, SkillFile
+from tilde.discovery import (
+    PROMPT_FORMAT_BRACES,
+    PROMPT_FORMAT_PLAIN,
+    Discovered,
+    DiscoveryContext,
+    declared_prompt,
+    declared_tool,
+)
+from tilde.management.v1.deployments_pb2 import DeclaredTool
+from tilde.prompts import valid_prompt_name
+from tilde.skills import read_skills
+from tilde_crewai.tools import describe_tool
+
+# CrewAI's own interpolation pattern (crewai.utilities.string_utils).
+_VARIABLE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_\-]*)}")
+_FIELDS = {"agents": ("role", "goal", "backstory"), "tasks": ("description", "expected_output")}
+
+
+def discover(value: Any, context: DiscoveryContext) -> Discovered | None:
+    if isinstance(value, BundledTools):
+        if not value.tools or not all(isinstance(tool, BaseTool) for tool in value.tools):
+            return None
+        return Discovered(tools=_tools(value.tools, value.options, f"{context.origin()}.tools"))
+    if isinstance(value, BaseAgent):
+        context.warn(
+            f"CrewAI agent {context.module}.{context.name} is built in code; declare it in a "
+            "@CrewBase agents.yaml to register its prompts"
+        )
+        tools = [tool for tool in value.tools or [] if isinstance(tool, BaseTool)]
+        return Discovered(tools=_tools(tools, None, f"{context.origin()}.tools"))
+    cls = value if isinstance(value, type) else type(value)
+    if not getattr(cls, "is_crew_class", False) or not hasattr(cls, "base_directory"):
+        return None
+    found = Discovered()
+    for kind, attribute in (
+        ("agents", "original_agents_config_path"),
+        ("tasks", "original_tasks_config_path"),
+    ):
+        path = getattr(cls, attribute, None)
+        explicit = getattr(cls, f"{kind}_config", None) is not None
+        if not isinstance(path, str):
+            if explicit:
+                context.warn(f"{cls.__name__}.{kind}_config is not a YAML path; not registered")
+            continue
+        file = Path(cls.base_directory) / path
+        if not file.is_file():
+            if explicit:
+                context.warn(f"{cls.__name__}: {kind} config {file} does not exist")
+            continue
+        config = yaml.safe_load(file.read_text(encoding="utf-8")) or {}
+        if not isinstance(config, dict):
+            context.warn(f"{context.relative(file)} is not a mapping of {kind}")
+            continue
+        _read(kind, config, context.relative(file), found, context)
+    return found
+
+
+def _tools(
+    tools: list[BaseTool], options: Mapping[str, BundledOptions] | None, origin: str
+) -> list[DeclaredTool]:
+    specs = [describe_tool(tool, options) for tool in tools]
+    return [declared_tool(spec, f"{origin}.{spec.name}") for spec in specs]
+
+
+def _read(
+    kind: str, config: dict[str, Any], origin: str, found: Discovered, context: DiscoveryContext
+) -> None:
+    for key, entry in config.items():
+        if not isinstance(entry, dict):
+            continue
+        for field in _FIELDS[kind]:
+            text = entry.get(field)
+            if not isinstance(text, str) or not text:
+                continue
+            name = f"{kind}/{key}/{field}"
+            if not valid_prompt_name(name):
+                context.warn(f"{origin}#{key}: {key!r} cannot name a prompt")
+                break
+            format = PROMPT_FORMAT_BRACES if _VARIABLE.search(text) else PROMPT_FORMAT_PLAIN
+            found.prompts.append(declared_prompt(name, text, format, f"{origin}#{key}.{field}"))
+        if kind == "agents":
+            for skill in entry.get("skills") or []:
+                found.skills.extend(_skills(skill, f"{origin}#{key}.skills", context))
+
+
+def _skills(skill: Any, origin: str, context: DiscoveryContext) -> list[SkillDefinition]:
+    if not isinstance(skill, str):
+        context.warn(f"{origin}: only skill paths and inline SKILL.md are registered")
+        return []
+    if skill.startswith("@"):
+        context.warn(f"{origin}: registry skill {skill} is not shipped with the deployment")
+        return []
+    if skill.lstrip().startswith("---"):
+        name = re.search(r"^name:\s*['\"]?([^'\"\n]+)", skill, re.MULTILINE)
+        if name is None:
+            context.warn(f"{origin}: inline SKILL.md has no name")
+            return []
+        return [SkillDefinition(name[1].strip(), [SkillFile("SKILL.md", skill.encode())])]
+    return read_skills(context.root / skill)

trytilde_crewai-3.0.1/src/tilde_crewai/inference.py

@@ -0,0 +1,39 @@
+"""Route CrewAI's native OpenAI client through Tilde's inference gateway.
+
+CrewAI builds its own OpenAI clients, so the invocation token is stamped by a transport
+interceptor rather than a supplied ``httpx`` client. With ``tilde.inference(alias)`` the LLM is
+built once at module scope and every request resolves the invocation running it (token,
+callback URL and prompt stamps)::
+
+    INFERENCE = tilde.inference("default")
+    llm = LLM(model="openai/gpt-4o-mini", base_url=INFERENCE.base_url,
+              api_key=INFERENCE.api_key, interceptor=inference_interceptor(INFERENCE))
+"""
+
+from __future__ import annotations
+
+import httpx
+from crewai.llms.hooks.base import BaseInterceptor
+
+from tilde import Inference
+
+
+class InferenceInterceptor(BaseInterceptor[httpx.Request, httpx.Response]):
+    def __init__(self, inference: Inference) -> None:
+        self._inference = inference
+
+    def on_outbound(self, message: httpx.Request) -> httpx.Request:
+        return self._inference.prepare(message)
+
+    def on_inbound(self, message: httpx.Response) -> httpx.Response:
+        return message
+
+    async def aon_outbound(self, message: httpx.Request) -> httpx.Request:
+        return self._inference.prepare(message)
+
+    async def aon_inbound(self, message: httpx.Response) -> httpx.Response:
+        return message
+
+
+def inference_interceptor(inference: Inference) -> InferenceInterceptor:
+    return InferenceInterceptor(inference)

trytilde_crewai-3.0.1/src/tilde_crewai/messages.py

@@ -0,0 +1,190 @@
+"""Convert typed Tilde context into CrewAI messages.
+
+Pass the result as ``await agent.kickoff_async(messages)``. CrewAI takes OpenAI-style
+``{"role", "content"}`` dicts (``crewai.utilities.types.LLMMessage``): every message keeps its
+role as conversation history, except the last ``user`` message, which CrewAI collapses to text
+and promotes into its task prompt. Content parts on that one message would be lost, so when it
+carries media a short text request is appended to take its place as the promoted turn.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from crewai.utilities.types import LLMMessage
+
+from tilde import (
+    AgentContext,
+    ContextMessage,
+    ConversationMessage,
+    GoalMessage,
+    ObjectiveMessage,
+    TaskMessage,
+)
+from tilde_crewai.attachments import AttachmentConversion, AttachmentHandler, convert_attachment
+
+Converted = LLMMessage | None | Awaitable[LLMMessage | None]
+
+MEDIA_REQUEST = "Respond to the latest message above, using its attachments."
+
+
+@dataclass(slots=True)
+class MessageHandlers:
+    """Explicit handlers take precedence over cached and default rendering; None omits an item."""
+
+    message: Callable[[ConversationMessage], Converted] | None = None
+    objective: Callable[[ObjectiveMessage], Converted] | None = None
+    goal: Callable[[GoalMessage], Converted] | None = None
+    task: Callable[[TaskMessage], Converted] | None = None
+
+
+_BATCH_ITEMS = 100
+_BATCH_BYTES = 1024 * 1024
+
+
+async def convert_to_crewai_messages(
+    messages: Iterable[ContextMessage],
+    *,
+    context: AgentContext | None = None,
+    on_message: MessageHandlers | None = None,
+    on_attachment: AttachmentHandler | None = None,
+) -> list[LLMMessage]:
+    """Convert typed SDK context into the message dicts ``Agent.kickoff_async`` accepts."""
+    output: list[LLMMessage] = []
+    handlers = on_message or MessageHandlers()
+    cache: list[tuple[str, Any]] = []
+    cache_bytes = 0
+
+    async def flush() -> None:
+        nonlocal cache_bytes
+        if cache and context is not None:
+            await context.cache_converted_messages(cache[:])
+            cache.clear()
+        cache_bytes = 0
+
+    for item in messages:
+        hydrated = False
+        if isinstance(item, ObjectiveMessage):
+            converted = (
+                await _call(handlers.objective, item)
+                if handlers.objective
+                else _user(item.objective)
+            )
+        elif isinstance(item, GoalMessage):
+            converted = (
+                await _call(handlers.goal, item)
+                if handlers.goal
+                else _user(f"Goal ({item.goal.status}): {item.goal.objective}")
+            )
+        elif isinstance(item, TaskMessage):
+            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 = _user(text)
+        else:
+            if item.message.status != "complete" and handlers.message is None:
+                continue
+            if handlers.message:
+                converted = await _call(handlers.message, item)
+            else:
+                # File bytes are hydrated afresh through the scoped SDK, never from the cache.
+                converted = _hydrate(item) if not item.message.attachments else None
+                hydrated = converted is not None
+                if converted is None:
+                    converted = await _render(item, context, on_attachment)
+        if converted is None:
+            continue
+        output.append(converted)
+        # Only canonical, text-only conversation messages are cached. Work state is always
+        # current, and hydrated files must not duplicate attachment bytes in the cache.
+        if (
+            context is not None
+            and isinstance(item, ConversationMessage)
+            and item.message.status == "complete"
+            and not hydrated
+            and not item.message.attachments
+            and isinstance(converted.get("content"), str)
+        ):
+            entry = {"id": item.id, "role": converted["role"], "content": converted["content"]}
+            size = len(json.dumps(entry).encode())
+            if size > _BATCH_BYTES:
+                continue
+            if len(cache) == _BATCH_ITEMS or cache_bytes + size > _BATCH_BYTES:
+                await flush()
+            cache.append((item.id, entry))
+            cache_bytes += size
+    await flush()
+    # CrewAI flattens the last user message to text; keep its media in history instead.
+    last_user = next((m for m in reversed(output) if m["role"] == "user"), None)
+    if last_user is not None and isinstance(last_user["content"], list):
+        output.append(_user(MEDIA_REQUEST))
+    return output
+
+
+def _user(text: str) -> LLMMessage:
+    return {"role": "user", "content": text}
+
+
+async def _call(handler: Callable[[Any], Any], value: Any) -> Any:
+    result = handler(value)
+    return await result if inspect.isawaitable(result) else result
+
+
+def _hydrate(item: ConversationMessage) -> LLMMessage | None:
+    cached = item.cached_agent_representation
+    if not isinstance(cached, dict):
+        return None
+    content = cached.get("content")
+    if cached.get("id") != item.id or cached.get("role") != item.role:
+        return None
+    if not isinstance(content, str):
+        return None
+    return {"role": item.role, "content": content}
+
+
+def _downloader(context: AgentContext | None, attachment_id: str):
+    def download():
+        if context is None:
+            raise RuntimeError(
+                "Attachment conversion requires context or a custom on_attachment handler"
+            )
+        return context.attachments.download(attachment_id)
+
+    return download
+
+
+async def _render(
+    item: ConversationMessage, context: AgentContext | None, on_attachment: AttachmentHandler | None
+) -> LLMMessage | None:
+    texts: list[str] = []
+    parts: list[dict[str, Any]] = []
+    if item.message.subject:
+        texts.append(f"Subject: {item.message.subject}")
+    if item.message.text:
+        texts.append(item.message.text)
+    handler = on_attachment or convert_attachment
+    for attachment in item.message.attachments:
+        conversion = AttachmentConversion(
+            message=item, attachment=attachment, download=_downloader(context, attachment.id)
+        )
+        result = await _call(handler, conversion)
+        for part in result if isinstance(result, list) else [result]:
+            if isinstance(part, str):
+                texts.append(part)
+            elif isinstance(part, dict):
+                parts.append(part)
+    if not texts and not parts:
+        return None
+    if not parts:
+        return {"role": item.role, "content": "\n\n".join(texts)}
+    if not texts:
+        # Providers reject empty text beside media; name the files instead of sending "".
+        texts.append("Attached: " + ", ".join(a.filename for a in item.message.attachments))
+    return {"role": item.role, "content": [{"type": "text", "text": "\n\n".join(texts)}, *parts]}

trytilde_crewai-3.0.1/src/tilde_crewai/steering.py

@@ -0,0 +1,23 @@
+"""Steering for CrewAI: a global ``before_llm_call`` hook, registered when ``tilde_crewai`` is
+imported, appends the running invocation's newly steered inputs as user messages before each
+model call. Outside an invocation it does nothing, so crews run unchanged elsewhere.
+"""
+
+from __future__ import annotations
+
+from crewai.hooks import LLMCallHookContext, register_before_llm_call_hook
+
+from tilde import current_invocation
+
+
+def inject_steering(context: LLMCallHookContext) -> None:
+    ctx = current_invocation()
+    if ctx is None:
+        return None
+    # Mutate in place: the executor keeps its own reference to this list.
+    for steered in ctx.take_inputs():
+        context.messages.append({"role": "user", "content": steered.text})
+    return None
+
+
+register_before_llm_call_hook(inject_steering)

trytilde_crewai-3.0.1/src/tilde_crewai/tools.py

@@ -0,0 +1,201 @@
+"""Expose Tilde channel tools to CrewAI with provider descriptions and schemas intact, and
+publish the agent's own CrewAI tools to Tilde as bundled tools."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import json
+import uuid
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from crewai.tools import BaseTool
+from crewai.utilities.string_utils import sanitize_tool_name
+from pydantic import BaseModel, PrivateAttr
+
+from tilde import AgentContext, BundledOptions, ChannelTool, Tool
+from tilde._tools import ToolSpec, bundled_tool, model_tool_name, tool_spec
+
+
+class ChannelCrewTool(BaseTool):
+    """A channel tool executed on the agent's event loop from wherever CrewAI calls it."""
+
+    _channel: ChannelTool | Tool = PrivateAttr()
+    _loop: asyncio.AbstractEventLoop = PrivateAttr()
+
+    def _run(self, **arguments: Any) -> str:
+        # CrewAI's executor calls tools synchronously on a worker thread, while channel
+        # execution belongs to the invocation's event loop.
+        try:
+            running = asyncio.get_running_loop()
+        except RuntimeError:
+            running = None
+        if running is self._loop:
+            raise RuntimeError("Channel tools block when run on the event loop; await arun()")
+        future = asyncio.run_coroutine_threadsafe(self._arun(**arguments), self._loop)
+        return future.result()
+
+    async def _arun(self, **arguments: Any) -> str:
+        # CrewAI does not pass the model's tool-call id to tools; the core generates one.
+        result = await self._channel.execute(arguments)
+        # CrewAI renders results with str(); JSON reads better to the model than a Python repr.
+        return result if isinstance(result, str) else json.dumps(result, default=str)
+
+
+def convert_to_crewai_tools(
+    channels: Mapping[str, ChannelTool | Tool],
+    *,
+    instructions: Mapping[str, str] | None = None,
+    prefix: str = "",
+) -> list[BaseTool]:
+    """Build CrewAI tools that keep provider descriptions and JSON schemas.
+
+    Call this on the invocation's event loop: the loop is captured so that CrewAI's worker
+    threads can execute channel tools on it. CrewAI reads a tool's parameters from
+    ``args_schema.model_json_schema()``, so the schema model returns the provider schema rather
+    than one introspected from fields; having no fields, it also passes arguments through
+    unvalidated. CrewAI then applies its own strict-mode pass and name normalization (see the
+    README). ``instructions`` overrides descriptions by channel name; ``prefix`` namespaces
+    model tool names when combining collections.
+    """
+    loop = asyncio.get_running_loop()
+    result: list[BaseTool] = []
+    names: set[str] = set()
+    for name, channel in channels.items():
+        key = model_tool_name(f"{prefix}{name}")
+        # CrewAI lowercases and snake_cases names for the model and would silently suffix a
+        # duplicate, so conflicts are checked on the name the model sees.
+        model_name = sanitize_tool_name(key)
+        if not key or not model_name or model_name in names:
+            raise ValueError("Conflicting or invalid model tool names")
+        names.add(model_name)
+        description = (
+            instructions[name]
+            if instructions is not None and name in instructions
+            else channel.description
+        )
+        tool = ChannelCrewTool(
+            name=key, description=description, args_schema=_schema_model(channel.input_schema)
+        )
+        tool._channel = channel
+        tool._loop = loop
+        result.append(tool)
+    return result
+
+
+def _schema_model(schema: dict[str, Any]) -> type[BaseModel]:
+    class ChannelToolInput(BaseModel):
+        @classmethod
+        def model_json_schema(cls, *args: Any, **kwargs: Any) -> dict[str, Any]:
+            return copy.deepcopy(schema)
+
+    return ChannelToolInput
+
+
+class _AuditedCrewTool(BaseTool):
+    """One of the agent's own CrewAI tools, audited on the invocation's event loop."""
+
+    _tool: BaseTool = PrivateAttr()
+    _ctx: AgentContext = PrivateAttr()
+    _loop: asyncio.AbstractEventLoop = PrivateAttr()
+    _published: str = PrivateAttr()
+
+    def _run(self, **arguments: Any) -> Any:
+        # CrewAI calls tools synchronously on a worker thread; audits belong to the loop.
+        try:
+            running = asyncio.get_running_loop()
+        except RuntimeError:
+            running = None
+        if running is self._loop:
+            raise RuntimeError("Audited tools block when run on the event loop; await arun()")
+        return asyncio.run_coroutine_threadsafe(self._arun(**arguments), self._loop).result()
+
+    async def _arun(self, **arguments: Any) -> Any:
+        # CrewAI never passes the model's tool-call id to tools; audit under a fresh one.
+        return await self._call(arguments, str(uuid.uuid4()))
+
+    async def _call(self, arguments: dict[str, Any], call: str) -> Any:
+        return await self._ctx._run_audited(
+            self._published, call, arguments, lambda: asyncio.to_thread(self._invoke, arguments)
+        )
+
+    def _invoke(self, arguments: dict[str, Any]) -> Any:
+        # Arguments were validated by this tool's run(); run the wrapped tool's own body.
+        result = self._tool._run(**arguments)
+        return asyncio.run(result) if asyncio.iscoroutine(result) else result
+
+
+async def with_tilde_tools(
+    ctx: AgentContext,
+    native_tools: Sequence[BaseTool],
+    *,
+    options: Mapping[str, BundledOptions] | None = None,
+) -> list[BaseTool]:
+    """The current channel's tools, the agent's other Tilde tools and its own tools, for
+    ``Agent(tools=...)``. Call it on the invocation's event loop.
+
+    Each native tool (``@tool`` or a ``BaseTool`` subclass) is published to Tilde under the name
+    CrewAI shows the model, with its description and argument and result schemas, so
+    ``tools.search`` finds it and a ``tools.execute`` naming it runs it here. It is returned as
+    a ``BaseTool`` that delegates to it, keeping its schemas, ``result_as_answer``, usage limit,
+    cache function and failure policy, and audits every call once. CrewAI has no
+    free metadata, so the summary and display come from ``options[name]`` (the tool's own name).
+
+    Caveats: CrewAI never passes the model's tool-call id to tools, so direct calls are audited
+    under a generated id that does not match the model's; ``tools.execute`` calls use their own
+    call id. A ``tools.execute`` call does not count towards the tool's usage limit.
+    """
+    loop = asyncio.get_running_loop()
+    tools = convert_to_crewai_tools({**ctx.channel.current, **ctx.agent_tools})
+    names = {sanitize_tool_name(tool.name) for tool in tools}
+    definitions = {}
+    for native in native_tools:
+        published = sanitize_tool_name(native.name)
+        if not published or published in names:
+            raise ValueError(f"Tool {native.name} conflicts with another tool")
+        names.add(published)
+        tool = _AuditedCrewTool(
+            name=native.name,
+            description=native.description,
+            env_vars=native.env_vars,
+            args_schema=native.args_schema,
+            result_schema=native.result_schema,
+            cache_function=native.cache_function,
+            result_as_answer=native.result_as_answer,
+            max_usage_count=native.max_usage_count,
+            tool_failure_policy=native.tool_failure_policy,
+        )
+        tool._tool = native
+        tool._ctx = ctx
+        tool._loop = loop
+        tool._published = published
+        definitions[published] = bundled_tool(describe_tool(native, options), _route(tool))
+        tools.append(tool)
+    # Published even when empty, so tools removed since the last call stop running here.
+    await ctx._set_bundled_tools(definitions)
+    return tools
+
+
+def describe_tool(
+    native: BaseTool, options: Mapping[str, BundledOptions] | None = None
+) -> ToolSpec:
+    """What ``with_tilde_tools`` publishes and ``tilde deploy`` declares for one tool: named as
+    CrewAI shows it to the model, with options looked up by the tool's own name."""
+    schema = native.args_schema.model_json_schema()
+    schema.pop("title", None)
+    return tool_spec(
+        sanitize_tool_name(native.name),
+        native.description,
+        schema,
+        output_schema=native.result_schema.model_json_schema() if native.result_schema else None,
+        options=(options or {}).get(native.name),
+    )
+
+
+def _route(tool: _AuditedCrewTool):
+    # A tools.execute naming this tool: validate as CrewAI would, audit under that call's id.
+    async def execute(input: Any, call: str) -> Any:
+        return await tool._call(tool._validate_kwargs(input), call)
+
+    return execute