carlyemail-toolkit 0.1.0__tar.gz

carlyemail_toolkit-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.py[cod]
+.env
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.DS_Store
+infra/venv/
+infra/Pulumi.*.yaml.bak
+.pulumi/
+docs-static/
+node_modules/
+package-lock.json

carlyemail_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: carlyemail-toolkit
+Version: 0.1.0
+Summary: CarlyEmail's email tools for the OpenAI Agents SDK, LangChain, LiveKit Agents, and any other framework.
+Project-URL: Homepage, https://carlyemail.com
+Project-URL: Documentation, https://docs.carlyemail.com/integrations/toolkit
+Author: SWH Labs LLC
+License-Expression: MIT
+Keywords: agents,carlyemail,email,langchain,livekit,llm,openai-agents,toolkit
+Requires-Python: >=3.10
+Requires-Dist: carlyemail>=0.4.0
+Provides-Extra: dev
+Requires-Dist: langchain-core<2,>=0.3; extra == 'dev'
+Requires-Dist: livekit-agents>=1.0; extra == 'dev'
+Requires-Dist: openai-agents>=0.1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=0.3; extra == 'langchain'
+Provides-Extra: livekit
+Requires-Dist: livekit-agents>=1.0; extra == 'livekit'
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.1; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# carlyemail-toolkit
+
+CarlyEmail's email tools for the OpenAI Agents SDK, LangChain, LiveKit Agents,
+and any other agent framework. A real inbox your agent can send, receive and
+reply from, without writing the tools yourself.
+
+```bash
+pip install "carlyemail-toolkit[openai]"     # or [langchain], [livekit]
+export CARLYEMAIL_API_KEY=ce_us_...
+```
+
+```python
+from agents import Agent
+from carlyemail_toolkit.openai import CarlyEmailToolkit
+
+agent = Agent(
+    name="Inbox",
+    instructions="Read the thread before replying. Draft when unsure.",
+    tools=CarlyEmailToolkit().get_tools(),
+)
+```
+
+```python
+from langchain.agents import create_agent
+from carlyemail_toolkit.langchain import CarlyEmailToolkit
+
+agent = create_agent("openai:gpt-5-mini", CarlyEmailToolkit().get_tools())
+```
+
+```python
+from livekit.agents import Agent
+from carlyemail_toolkit.livekit import CarlyEmailToolkit
+
+agent = Agent(instructions="...", tools=CarlyEmailToolkit().get_tools())
+```
+
+```python
+from carlyemail_toolkit import CarlyEmailToolkit   # no framework
+
+for tool in CarlyEmailToolkit().get_tools():
+    tool.name, tool.description, tool.input_schema, tool.read_only
+    tool(thread_id="...")                          # runs it
+```
+
+## What is in it
+
+The 25 tools the hosted [MCP server](https://docs.carlyemail.com/mcp) serves —
+inboxes, threads, messages, drafts, attachments, labels, and account
+verification — with the same names, descriptions and parameter schemas, called
+over the REST API. Pass names to take only some:
+
+```python
+tools = CarlyEmailToolkit().get_tools(["list_messages", "get_thread", "reply_to_message"])
+```
+
+A name that is not a tool raises rather than being dropped.
+
+## Which inbox
+
+Every tool takes `inbox_id`, and most work without it. A key scoped to one
+inbox means that inbox. An organization with one inbox means that one. With
+several, the tools that read threads and drafts look across all of them, and
+every other tool refuses and names the inboxes so the agent can ask which —
+the same behaviour as the hosted server.
+
+## Errors
+
+A failed call raises the way each framework expects — `RuntimeError` (OpenAI
+Agents SDK), `ToolException` (LangChain, which becomes an error message the
+model reads), `ToolError` (LiveKit Agents) — with the API's message and the
+fix it suggests, in one bounded line.
+
+See <https://docs.carlyemail.com/integrations/toolkit>.

carlyemail_toolkit-0.1.0/README.md

@@ -0,0 +1,73 @@
+# carlyemail-toolkit
+
+CarlyEmail's email tools for the OpenAI Agents SDK, LangChain, LiveKit Agents,
+and any other agent framework. A real inbox your agent can send, receive and
+reply from, without writing the tools yourself.
+
+```bash
+pip install "carlyemail-toolkit[openai]"     # or [langchain], [livekit]
+export CARLYEMAIL_API_KEY=ce_us_...
+```
+
+```python
+from agents import Agent
+from carlyemail_toolkit.openai import CarlyEmailToolkit
+
+agent = Agent(
+    name="Inbox",
+    instructions="Read the thread before replying. Draft when unsure.",
+    tools=CarlyEmailToolkit().get_tools(),
+)
+```
+
+```python
+from langchain.agents import create_agent
+from carlyemail_toolkit.langchain import CarlyEmailToolkit
+
+agent = create_agent("openai:gpt-5-mini", CarlyEmailToolkit().get_tools())
+```
+
+```python
+from livekit.agents import Agent
+from carlyemail_toolkit.livekit import CarlyEmailToolkit
+
+agent = Agent(instructions="...", tools=CarlyEmailToolkit().get_tools())
+```
+
+```python
+from carlyemail_toolkit import CarlyEmailToolkit   # no framework
+
+for tool in CarlyEmailToolkit().get_tools():
+    tool.name, tool.description, tool.input_schema, tool.read_only
+    tool(thread_id="...")                          # runs it
+```
+
+## What is in it
+
+The 25 tools the hosted [MCP server](https://docs.carlyemail.com/mcp) serves —
+inboxes, threads, messages, drafts, attachments, labels, and account
+verification — with the same names, descriptions and parameter schemas, called
+over the REST API. Pass names to take only some:
+
+```python
+tools = CarlyEmailToolkit().get_tools(["list_messages", "get_thread", "reply_to_message"])
+```
+
+A name that is not a tool raises rather than being dropped.
+
+## Which inbox
+
+Every tool takes `inbox_id`, and most work without it. A key scoped to one
+inbox means that inbox. An organization with one inbox means that one. With
+several, the tools that read threads and drafts look across all of them, and
+every other tool refuses and names the inboxes so the agent can ask which —
+the same behaviour as the hosted server.
+
+## Errors
+
+A failed call raises the way each framework expects — `RuntimeError` (OpenAI
+Agents SDK), `ToolException` (LangChain, which becomes an error message the
+model reads), `ToolError` (LiveKit Agents) — with the API's message and the
+fix it suggests, in one bounded line.
+
+See <https://docs.carlyemail.com/integrations/toolkit>.

carlyemail_toolkit-0.1.0/carlyemail_toolkit/__init__.py

@@ -0,0 +1,29 @@
+"""CarlyEmail tools for agent frameworks.
+
+    from carlyemail_toolkit.openai import CarlyEmailToolkit     # OpenAI Agents SDK
+    from carlyemail_toolkit.langchain import CarlyEmailToolkit  # LangChain
+    from carlyemail_toolkit.livekit import CarlyEmailToolkit    # LiveKit Agents
+    from carlyemail_toolkit import CarlyEmailToolkit            # anything else
+
+    tools = CarlyEmailToolkit().get_tools()
+
+Each reads `CARLYEMAIL_API_KEY`, or takes `api_key=`, or a `CarlyEmail` client.
+The tools are the ones the hosted MCP server serves, called over the REST API.
+"""
+
+from carlyemail_toolkit.errors import ToolkitError, error_message
+from carlyemail_toolkit.toolkit import BaseToolkit, BoundTool, CarlyEmailToolkit
+from carlyemail_toolkit.tools import FIRST_INBOX, TOOLS, Tool
+
+__all__ = [
+    "FIRST_INBOX",
+    "TOOLS",
+    "BaseToolkit",
+    "BoundTool",
+    "CarlyEmailToolkit",
+    "Tool",
+    "ToolkitError",
+    "error_message",
+]
+
+__version__ = "0.1.0"

carlyemail_toolkit-0.1.0/carlyemail_toolkit/errors.py

@@ -0,0 +1,51 @@
+"""What a failed tool call says to the framework that made it.
+
+Every adapter raises the exception its framework expects, and every one of them
+builds the message here, so a refused send reads the same whether the agent is
+on LangChain or LiveKit.
+"""
+
+from __future__ import annotations
+
+from carlyemail import CarlyEmailError
+
+#: A validation error body can list every field it disliked. That is useful to
+#: a person and useless to a model, which reads the first sentence and acts.
+MAX_MESSAGE_LENGTH = 500
+
+
+class ToolkitError(Exception):
+    """A refusal made on this side of the wire, before any request went out.
+
+    Carries `code` and `fix` the way the API's own errors do, so a caller that
+    already handles `CarlyEmailError` has nothing new to learn.
+    """
+
+    def __init__(self, message: str, *, code: str, fix: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.fix = fix
+
+
+def error_message(error: BaseException) -> str:
+    """One bounded sentence or three: what went wrong, what clears it, where to read more.
+
+    The API answers errors with `message`, `fix` and `docs`, and the SDK keeps
+    all three on the exception. The message alone tells the model it failed;
+    the fix is what lets it do something about it on the next turn.
+    """
+    if isinstance(error, ToolkitError):
+        text = f"{error} {error.fix}"
+    elif isinstance(error, CarlyEmailError):
+        parts = [str(error)]
+        if error.fix:
+            parts.append(str(error.fix))
+        if error.docs:
+            parts.append(f"See {error.docs}")
+        tag = f"{error.code}, HTTP {error.status}" if error.code else f"HTTP {error.status}"
+        text = f"{' '.join(parts)} ({tag})"
+    else:
+        text = f"{type(error).__name__}: {error}"
+    if len(text) > MAX_MESSAGE_LENGTH:
+        return text[:MAX_MESSAGE_LENGTH] + "…"
+    return text

carlyemail_toolkit-0.1.0/carlyemail_toolkit/langchain.py

@@ -0,0 +1,42 @@
+"""CarlyEmail tools for LangChain.
+
+    from langchain.agents import create_agent
+    from carlyemail_toolkit.langchain import CarlyEmailToolkit
+
+    agent = create_agent("openai:gpt-5-mini", CarlyEmailToolkit().get_tools())
+
+These are the hosted MCP server's tools as native `BaseTool`s, with no MCP
+client in the loop. For a loader, a retriever and a verified inbound router,
+`langchain-carlyemail` is the package.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from langchain_core.tools import BaseTool, StructuredTool, ToolException
+
+from carlyemail_toolkit.errors import error_message
+from carlyemail_toolkit.toolkit import BaseToolkit
+from carlyemail_toolkit.tools import Tool
+
+
+class CarlyEmailToolkit(BaseToolkit[BaseTool]):
+    def _build(self, tool: Tool) -> BaseTool:
+        def run(**arguments: Any) -> str:
+            try:
+                return json.dumps(tool.run(self.client, arguments))
+            except Exception as error:
+                # With `handle_tool_error` set, a ToolException becomes an
+                # error ToolMessage the model can read and act on, instead of
+                # ending the run.
+                raise ToolException(error_message(error)) from error
+
+        return StructuredTool.from_function(
+            func=run,
+            name=tool.name,
+            description=tool.description,
+            args_schema=tool.input_schema,
+            handle_tool_error=True,
+        )

carlyemail_toolkit-0.1.0/carlyemail_toolkit/livekit.py

@@ -0,0 +1,39 @@
+"""CarlyEmail tools for LiveKit Agents.
+
+from livekit.agents import Agent
+from carlyemail_toolkit.livekit import CarlyEmailToolkit
+
+agent = Agent(instructions="...", tools=CarlyEmailToolkit().get_tools())
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from livekit.agents.llm import RawFunctionTool, ToolError, function_tool
+
+from carlyemail_toolkit.errors import error_message
+from carlyemail_toolkit.toolkit import BaseToolkit
+from carlyemail_toolkit.tools import Tool
+
+
+class CarlyEmailToolkit(BaseToolkit[RawFunctionTool]):
+    def _build(self, tool: Tool) -> RawFunctionTool:
+        async def run(raw_arguments: dict[str, object]) -> str:
+            try:
+                result = await asyncio.to_thread(tool.run, self.client, raw_arguments)
+            except Exception as error:
+                # A ToolError is what the agent reads back to the person; any
+                # other exception is treated as the tool having broken.
+                raise ToolError(error_message(error)) from error
+            return json.dumps(result)
+
+        return function_tool(
+            run,
+            raw_schema={
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": tool.input_schema,
+            },
+        )

carlyemail_toolkit-0.1.0/carlyemail_toolkit/openai.py

@@ -0,0 +1,45 @@
+"""CarlyEmail tools for the OpenAI Agents SDK.
+
+from agents import Agent
+from carlyemail_toolkit.openai import CarlyEmailToolkit
+
+agent = Agent(name="Inbox", instructions="...", tools=CarlyEmailToolkit().get_tools())
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from agents import FunctionTool
+
+from carlyemail_toolkit.errors import error_message
+from carlyemail_toolkit.toolkit import BaseToolkit
+from carlyemail_toolkit.tools import Tool
+
+
+class CarlyEmailToolkit(BaseToolkit[FunctionTool]):
+    def _build(self, tool: Tool) -> FunctionTool:
+        async def on_invoke_tool(context: Any, input_str: str) -> str:
+            arguments = json.loads(input_str) if input_str else {}
+            try:
+                result = await asyncio.to_thread(tool.run, self.client, arguments)
+            except Exception as error:
+                # `failure_error_function` belongs to the decorator, not to a
+                # FunctionTool built by hand. Raising is what makes the SDK
+                # record a failed call rather than a successful one whose
+                # output happens to describe a failure.
+                raise RuntimeError(error_message(error)) from error
+            return json.dumps(result)
+
+        return FunctionTool(
+            name=tool.name,
+            description=tool.description,
+            params_json_schema=tool.input_schema,
+            on_invoke_tool=on_invoke_tool,
+            # Strict mode makes every property required. The server's schemas
+            # mark what is actually required, and an optional `cc` the model
+            # must fill in on every call is a worse tool, not a safer one.
+            strict_json_schema=False,
+        )

carlyemail_toolkit-0.1.0/carlyemail_toolkit/toolkit.py

@@ -0,0 +1,111 @@
+"""The toolkit shape every adapter shares, and the framework-free one."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Generic, TypeVar
+
+from carlyemail import CarlyEmail
+
+from carlyemail_toolkit.tools import TOOLS, Tool
+
+T = TypeVar("T")
+
+
+class BaseToolkit(Generic[T]):  # noqa: UP046 — the package runs on 3.10
+    """Builds one framework-native tool per entry in `TOOLS`.
+
+    Subclasses say how in `_build`; everything else — the client, the filter
+    by name — is the same on every framework.
+    """
+
+    def __init__(
+        self,
+        client: CarlyEmail | None = None,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        self.client = client or CarlyEmail(api_key=api_key, base_url=base_url)
+        self._built: dict[str, T] = {tool.name: self._build(tool) for tool in TOOLS}
+
+    def _build(self, tool: Tool) -> T:
+        raise NotImplementedError
+
+    def get_tools(self, names: Iterable[str] | None = None) -> list[T]:
+        """All tools, or the named ones in the order named.
+
+        A name that is not a tool is an error, not an omission. Silently
+        dropping it is how an agent ships with `send_message` misspelled and
+        nobody finds out until it cannot send.
+        """
+        if names is None:
+            return list(self._built.values())
+        wanted = list(names)
+        unknown = [name for name in wanted if name not in self._built]
+        if unknown:
+            raise ValueError(
+                f"Unknown tool(s): {', '.join(unknown)}. " f"Available: {', '.join(self._built)}."
+            )
+        return [self._built[name] for name in wanted]
+
+    def names(self) -> list[str]:
+        return list(self._built)
+
+
+class BoundTool:
+    """A tool tied to one client. Call it with keyword arguments.
+
+    For frameworks the toolkit has no adapter for: everything a tool
+    definition needs is on it — `name`, `description`, `input_schema`, the
+    annotations — and calling it runs the tool.
+    """
+
+    def __init__(self, tool: Tool, client: CarlyEmail) -> None:
+        self.tool = tool
+        self.client = client
+
+    @property
+    def name(self) -> str:
+        return self.tool.name
+
+    @property
+    def title(self) -> str:
+        return self.tool.title
+
+    @property
+    def description(self) -> str:
+        return self.tool.description
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return self.tool.input_schema
+
+    @property
+    def read_only(self) -> bool:
+        return self.tool.read_only
+
+    @property
+    def destructive(self) -> bool:
+        return self.tool.destructive
+
+    @property
+    def idempotent(self) -> bool:
+        return self.tool.idempotent
+
+    @property
+    def open_world(self) -> bool:
+        return self.tool.open_world
+
+    def __call__(self, **arguments: Any) -> Any:
+        return self.tool.run(self.client, arguments)
+
+    def __repr__(self) -> str:
+        return f"<BoundTool {self.name}>"
+
+
+class CarlyEmailToolkit(BaseToolkit[BoundTool]):
+    """The tools with no framework around them."""
+
+    def _build(self, tool: Tool) -> BoundTool:
+        return BoundTool(tool, self.client)