chatlas 0.11.0__tar.gz → 0.11.1__tar.gz

{chatlas-0.11.0 → chatlas-0.11.1}/CHANGELOG.md

@@ -7,6 +7,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 -->
 
+## [0.11.1] - 2025-08-29
+
+### New features
+
+* `.register_tool()` gains a `name` parameter (useful for overriding the name of the function). (#162)
+
+### Bug fixes
+
+* `ContentToolRequest` is (once again) serializable to/from JSON via Pydantic. (#164)
+* `.register_tool(model=model)` no longer unexpectedly errors when `model` contains `pydantic.Field(alias='_my_alias')`. (#161)
+
+### Changes
+
+* `.register_tool(annotations=annotations)` drops support for `mcp.types.ToolAnnotations()` and instead expects a dictionary of the same info. (#164)
+
+
 ## [0.11.0] - 2025-08-26
 
 ### New features

{chatlas-0.11.0 → chatlas-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatlas
-Version: 0.11.0
+Version: 0.11.1
 Summary: A simple and consistent interface for chatting with LLMs
 Project-URL: Homepage, https://posit-dev.github.io/chatlas
 Project-URL: Documentation, https://posit-dev.github.io/chatlas

{chatlas-0.11.0 → chatlas-0.11.1}/chatlas/_chat.py

@@ -34,6 +34,7 @@ from ._content import (
     ContentText,
     ContentToolRequest,
     ContentToolResult,
+    ToolInfo,
 )
 from ._display import (
     EchoDisplayOptions,
@@ -52,7 +53,7 @@ from ._typing_extensions import TypedDict, TypeGuard
 from ._utils import MISSING, MISSING_TYPE, html_escape, wrap_async
 
 if TYPE_CHECKING:
-    from mcp.types import ToolAnnotations
+    from ._content import ToolAnnotations
 
 
 class TokensDict(TypedDict):
@@ -1537,6 +1538,7 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         func: Callable[..., Any] | Callable[..., Awaitable[Any]],
         *,
         force: bool = False,
+        name: Optional[str] = None,
         model: Optional[type[BaseModel]] = None,
         annotations: "Optional[ToolAnnotations]" = None,
     ):
@@ -1610,6 +1612,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         force
             If `True`, overwrite any existing tool with the same name. If `False`
             (the default), raise an error if a tool with the same name already exists.
+        name
+            The name of the tool. If not provided, the name will be inferred from the
+            `func`'s name (or the `model`'s name, if provided).
         model
             A Pydantic model that describes the input parameters for the function.
             If not provided, the model will be inferred from the function's type hints.
@@ -1618,14 +1623,13 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             name and docstring of the function.
         annotations
             Additional properties that describe the tool and its behavior.
-            Should be a `from mcp.types import ToolAnnotations` instance.
 
         Raises
         ------
         ValueError
             If a tool with the same name already exists and `force` is `False`.
         """
-        tool = Tool.from_func(func, model=model, annotations=annotations)
+        tool = Tool.from_func(func, name=name, model=model, annotations=annotations)
         if tool.name in self._tools and not force:
             raise ValueError(
                 f"Tool with name '{tool.name}' is already registered. "
@@ -1933,7 +1937,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             all_results: list[ContentToolResult] = []
             for x in turn.contents:
                 if isinstance(x, ContentToolRequest):
-                    x.tool = self._tools.get(x.name)
+                    tool = self._tools.get(x.name)
+                    if tool is not None:
+                        x.tool = ToolInfo.from_tool(tool)
                     if echo == "output":
                         self._echo_content(f"\n\n{x}\n\n")
                     if content == "all":
@@ -1994,7 +2000,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             all_results: list[ContentToolResult] = []
             for x in turn.contents:
                 if isinstance(x, ContentToolRequest):
-                    x.tool = self._tools.get(x.name)
+                    tool = self._tools.get(x.name)
+                    if tool is not None:
+                        x.tool = ToolInfo.from_tool(tool)
                     if echo == "output":
                         self._echo_content(f"\n\n{x}\n\n")
                     if content == "all":
@@ -2152,7 +2160,7 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         self._turns.extend([user_turn, turn])
 
     def _invoke_tool(self, request: ContentToolRequest):
-        tool = request.tool
+        tool = self._tools.get(request.name)
         func = tool.func if tool is not None else None
 
         if func is None:
@@ -2200,7 +2208,7 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             yield self._handle_tool_error_result(request, e)
 
     async def _invoke_tool_async(self, request: ContentToolRequest):
-        tool = request.tool
+        tool = self._tools.get(request.name)
 
         if tool is None:
             yield self._handle_tool_error_result(

{chatlas-0.11.0 → chatlas-0.11.1}/chatlas/_content.py

@@ -6,9 +6,59 @@ from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 import orjson
 from pydantic import BaseModel, ConfigDict
 
+from ._typing_extensions import NotRequired, TypedDict
+
 if TYPE_CHECKING:
     from ._tools import Tool
 
+
+class ToolAnnotations(TypedDict, total=False):
+    """
+    Additional properties describing a Tool to clients.
+
+    NOTE: all properties in ToolAnnotations are **hints**.
+    They are not guaranteed to provide a faithful description of
+    tool behavior (including descriptive properties like `title`).
+
+    Clients should never make tool use decisions based on ToolAnnotations
+    received from untrusted servers.
+    """
+
+    title: NotRequired[str]
+    """A human-readable title for the tool."""
+
+    readOnlyHint: NotRequired[bool]
+    """
+    If true, the tool does not modify its environment.
+    Default: false
+    """
+
+    destructiveHint: NotRequired[bool]
+    """
+    If true, the tool may perform destructive updates to its environment.
+    If false, the tool performs only additive updates.
+    (This property is meaningful only when `readOnlyHint == false`)
+    Default: true
+    """
+
+    idempotentHint: NotRequired[bool]
+    """
+    If true, calling the tool repeatedly with the same arguments
+    will have no additional effect on the its environment.
+    (This property is meaningful only when `readOnlyHint == false`)
+    Default: false
+    """
+
+    openWorldHint: NotRequired[bool]
+    """
+    If true, this tool may interact with an "open world" of external
+    entities. If false, the tool's domain of interaction is closed.
+    For example, the world of a web search tool is open, whereas that
+    of a memory tool is not.
+    Default: true
+    """
+
+
 ImageContentTypes = Literal[
     "image/png",
     "image/jpeg",
@@ -19,6 +69,45 @@ ImageContentTypes = Literal[
 Allowable content types for images.
 """
 
+
+class ToolInfo(BaseModel):
+    """
+    Serializable tool information
+
+    This contains only the serializable parts of a Tool that are needed
+    for ContentToolRequest to be JSON-serializable. This allows tool
+    metadata to be preserved without including the non-serializable
+    function reference.
+
+    Parameters
+    ----------
+    name
+        The name of the tool.
+    description
+        A description of what the tool does.
+    parameters
+        A dictionary describing the input parameters and their types.
+    annotations
+        Additional properties that describe the tool and its behavior.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    annotations: Optional[ToolAnnotations] = None
+
+    @classmethod
+    def from_tool(cls, tool: "Tool") -> "ToolInfo":
+        """Create a ToolInfo from a Tool instance."""
+        func_schema = tool.schema["function"]
+        return cls(
+            name=tool.name,
+            description=func_schema.get("description", ""),
+            parameters=func_schema.get("parameters", {}),
+            annotations=tool.annotations,
+        )
+
+
 ContentTypeEnum = Literal[
     "text",
     "image_remote",
@@ -175,14 +264,15 @@ class ContentToolRequest(Content):
     arguments
         The arguments to pass to the tool/function.
     tool
-        The tool/function to be called. This is set internally by chatlas's tool
-        calling loop.
+        Serializable information about the tool. This is set internally by
+        chatlas's tool calling loop and contains only the metadata needed
+        for serialization (name, description, parameters, annotations).
     """
 
     id: str
     name: str
     arguments: object
-    tool: Optional["Tool"] = None
+    tool: Optional[ToolInfo] = None
 
     content_type: ContentTypeEnum = "tool_request"
 

{chatlas-0.11.0 → chatlas-0.11.1}/chatlas/_tools.py

@@ -2,7 +2,15 @@ from __future__ import annotations
 
 import inspect
 import warnings
-from typing import TYPE_CHECKING, Any, AsyncGenerator, Awaitable, Callable, Optional
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncGenerator,
+    Awaitable,
+    Callable,
+    Optional,
+    cast,
+)
 
 import openai
 from pydantic import BaseModel, Field, create_model
@@ -12,6 +20,7 @@ from ._content import (
     ContentToolResult,
     ContentToolResultImage,
     ContentToolResultResource,
+    ToolAnnotations,
 )
 
 __all__ = (
@@ -22,7 +31,6 @@ __all__ = (
 if TYPE_CHECKING:
     from mcp import ClientSession as MCPClientSession
     from mcp import Tool as MCPTool
-    from mcp.types import ToolAnnotations
     from openai.types.chat import ChatCompletionToolParam
 
 
@@ -44,8 +52,7 @@ class Tool:
     parameters
         A dictionary describing the input parameters and their types.
     annotations
-        Additional properties that describe the tool and its behavior. Should be
-        a `from mcp.types import ToolAnnotations` instance.
+        Additional properties that describe the tool and its behavior.
     """
 
     func: Callable[..., Any] | Callable[..., Awaitable[Any]]
@@ -77,6 +84,7 @@ class Tool:
         cls: type["Tool"],
         func: Callable[..., Any] | Callable[..., Awaitable[Any]],
         *,
+        name: Optional[str] = None,
         model: Optional[type[BaseModel]] = None,
         annotations: "Optional[ToolAnnotations]" = None,
     ) -> "Tool":
@@ -87,6 +95,9 @@ class Tool:
         ----------
         func
             The function to wrap as a tool.
+        name
+            The name of the tool. If not provided, the name will be inferred from the
+            function's name.
         model
             A Pydantic model that describes the input parameters for the function.
             If not provided, the model will be inferred from the function's type hints.
@@ -94,8 +105,7 @@ class Tool:
             Note that the name and docstring of the model takes precedence over the
             name and docstring of the function.
         annotations
-            Additional properties that describe the tool and its behavior. Should be
-            a `from mcp.types import ToolAnnotations` instance.
+            Additional properties that describe the tool and its behavior.
 
         Returns
         -------
@@ -114,7 +124,8 @@ class Tool:
         # Throw if there is a mismatch between the model and the function parameters
         params = inspect.signature(func).parameters
         fields = model.model_fields
-        diff = set(params) ^ set(fields)
+        fields_alias = [val.alias if val.alias else key for key, val in fields.items()]
+        diff = set(params) ^ set(fields_alias)
         if diff:
             raise ValueError(
                 f"`model` fields must match tool function parameters exactly. "
@@ -125,7 +136,7 @@ class Tool:
 
         return cls(
             func=func,
-            name=model.__name__ or func.__name__,
+            name=name or model.__name__ or func.__name__,
             description=model.__doc__ or func.__doc__ or "",
             parameters=params,
             annotations=annotations,
@@ -203,12 +214,17 @@ class Tool:
 
         params = mcp_tool_input_schema_to_param_schema(mcp_tool.inputSchema)
 
+        # Convert MCP ToolAnnotations to our TypedDict format
+        annotations = None
+        if mcp_tool.annotations:
+            annotations = cast(ToolAnnotations, mcp_tool.annotations.model_dump())
+
         return cls(
             func=_utils.wrap_async(_call),
             name=mcp_tool.name,
             description=mcp_tool.description or "",
             parameters=params,
-            annotations=mcp_tool.annotations,
+            annotations=annotations,
         )
 
 

{chatlas-0.11.0 → chatlas-0.11.1}/chatlas/_typing_extensions.py

@@ -13,7 +13,7 @@ else:
 # Even though TypedDict is available in Python 3.8, because it's used with NotRequired,
 # they should both come from the same typing module.
 # https://peps.python.org/pep-0655/#usage-in-python-3-11
-if sys.version_info >= (3, 11):
+if sys.version_info >= (3, 12):
     from typing import NotRequired, Required, TypedDict
 else:
     from typing_extensions import NotRequired, Required, TypedDict

{chatlas-0.11.0 → chatlas-0.11.1}/chatlas/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.11.0'
-__version_tuple__ = version_tuple = (0, 11, 0)
+__version__ = version = '0.11.1'
+__version_tuple__ = version_tuple = (0, 11, 1)
 
 __commit_id__ = commit_id = None

{chatlas-0.11.0 → chatlas-0.11.1}/chatlas/types/__init__.py

@@ -13,6 +13,8 @@ from .._content import (
     ContentToolRequest,
     ContentToolResult,
     ImageContentTypes,
+    ToolAnnotations,
+    ToolInfo,
 )
 from .._provider import ModelInfo
 from .._tokens import TokenUsage
@@ -32,6 +34,8 @@ __all__ = (
     "ImageContentTypes",
     "SubmitInputArgsT",
     "TokenUsage",
+    "ToolAnnotations",
+    "ToolInfo",
     "MISSING_TYPE",
     "MISSING",
     "ModelInfo",

{chatlas-0.11.0 → chatlas-0.11.1}/docs/_quarto.yml

@@ -188,6 +188,8 @@ quartodoc:
         - types.MISSING
         - types.SubmitInputArgsT
         - types.TokenUsage
+        - types.ToolAnnotations
+        - types.ToolInfo
 
 
 

{chatlas-0.11.0 → chatlas-0.11.1}/tests/conftest.py

@@ -90,11 +90,7 @@ def assert_tools_simple(chat_fun: ChatFun, stream: bool = True):
 
 
 def assert_tools_simple_stream_content(chat_fun: ChatFun):
-    try:
-        from mcp.types import ToolAnnotations
-    except ImportError:
-        pytest.skip("mcp is not installed")
-        return
+    from chatlas._content import ToolAnnotations
 
     chat = chat_fun(system_prompt="Be very terse, not even punctuation.")
 
@@ -114,7 +110,7 @@ def assert_tools_simple_stream_content(chat_fun: ChatFun):
     assert request[0].tool is not None
     assert request[0].tool.name == "get_date"
     assert request[0].tool.annotations is not None
-    assert request[0].tool.annotations.title == "Get Date"
+    assert request[0].tool.annotations["title"] == "Get Date"
 
     # Emits a response (with a reference to the request)
     response = [x for x in chunks if isinstance(x, ContentToolResult)]

{chatlas-0.11.0 → chatlas-0.11.1}/tests/test_content_tools.py

@@ -3,6 +3,7 @@ from typing import Any, Optional, Union
 import pytest
 
 from chatlas import ChatOpenAI
+from chatlas._content import ToolInfo
 from chatlas.types import ContentToolRequest, ContentToolResult
 
 
@@ -113,11 +114,12 @@ def test_invoke_tool_returns_tool_result():
         name: str = "tool",
         args: Optional[dict[str, Any]] = None,
     ):
+        tool_obj = chat._tools.get(name)
         return ContentToolRequest(
             id="id",
             name=name,
             arguments=args or {},
-            tool=chat._tools.get(name),
+            tool=ToolInfo.from_tool(tool_obj) if tool_obj else None,
         )
 
     req1 = new_tool_request()
@@ -178,11 +180,12 @@ async def test_invoke_tool_returns_tool_result_async():
         name: str = "tool",
         args: Optional[dict[str, Any]] = None,
     ):
+        tool_obj = chat._tools.get(name)
         return ContentToolRequest(
             id="id",
             name=name,
             arguments=args or {},
-            tool=chat._tools.get(name),
+            tool=ToolInfo.from_tool(tool_obj) if tool_obj else None,
         )
 
     req1 = new_tool_request()
@@ -254,18 +257,20 @@ def test_tool_custom_result():
     chat.register_tool(custom_tool)
     chat.register_tool(custom_tool_err)
 
+    tool_obj = chat._tools.get("custom_tool")
     req = ContentToolRequest(
         id="id",
         name="custom_tool",
         arguments={},
-        tool=chat._tools.get("custom_tool"),
+        tool=ToolInfo.from_tool(tool_obj) if tool_obj else None,
     )
 
+    tool_err_obj = chat._tools.get("custom_tool_err")
     req_err = ContentToolRequest(
         id="id",
         name="custom_tool_err",
         arguments={},
-        tool=chat._tools.get("custom_tool_err"),
+        tool=ToolInfo.from_tool(tool_err_obj) if tool_err_obj else None,
     )
 
     results = list(chat._invoke_tool(req))
@@ -316,18 +321,20 @@ async def test_tool_custom_result_async():
     chat.register_tool(custom_tool)
     chat.register_tool(custom_tool_err)
 
+    tool_obj = chat._tools.get("custom_tool")
     req = ContentToolRequest(
         id="id",
         name="custom_tool",
         arguments={},
-        tool=chat._tools.get("custom_tool"),
+        tool=ToolInfo.from_tool(tool_obj) if tool_obj else None,
     )
 
+    tool_err_obj = chat._tools.get("custom_tool_err")
     req_err = ContentToolRequest(
         id="id",
         name="custom_tool_err",
         arguments={},
-        tool=chat._tools.get("custom_tool_err"),
+        tool=ToolInfo.from_tool(tool_err_obj) if tool_err_obj else None,
     )
 
     results = []
@@ -361,3 +368,38 @@ async def test_tool_custom_result_async():
     assert res_err.name == req_err.name
     assert res_err.arguments == req_err.arguments
 
+
+def test_content_tool_request_serializable():
+    """Test that ContentToolRequest with Tool instance is JSON serializable"""
+    chat = ChatOpenAI()
+
+    def add(x: int, y: int) -> int:
+        """Add two numbers"""
+        return x + y
+
+    chat.register_tool(add)
+
+    # Create a ContentToolRequest with the Tool info
+    tool = chat._tools["add"]
+    request = ContentToolRequest(
+        id="test-123",
+        name="add",
+        arguments={"x": 1, "y": 2},
+        tool=ToolInfo.from_tool(tool),
+    )
+
+    # Test that it can be serialized to JSON
+    json_data = request.model_dump_json()
+    assert isinstance(json_data, str)
+
+    # Test that the JSON can be parsed
+    parsed = ContentToolRequest.model_validate_json(json_data)
+    assert parsed.id == "test-123"
+    assert parsed.name == "add"
+    assert parsed.arguments == {"x": 1, "y": 2}
+    assert parsed.content_type == "tool_request"
+
+    # Test that the tool is serialized (func is excluded from serialization)
+    assert parsed.tool is not None
+    assert parsed.tool.name == "add"
+    assert parsed.tool.description == "Add two numbers"