chatlas 0.11.0__tar.gz → 0.12.0__tar.gz

{chatlas-0.11.0 → chatlas-0.12.0}/.vscode/settings.json

@@ -7,5 +7,12 @@
         },
         "editor.defaultFormatter": "charliermarsh.ruff",
     },
-    "flake8.args": ["--max-line-length=120"]
-}
+    "flake8.args": [
+      "--max-line-length=120"
+    ],
+    "python.testing.pytestArgs": [
+      "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

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

@@ -7,6 +7,39 @@ 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.12.0] - 2025-09-08
+
+### Breaking changes
+
+* `ChatAuto()`'s first (optional) positional parameter has changed from `system_prompt` to `provider_model`, and `system_prompt` is now a keyword parameter. As a result, you may need to change `ChatAuto("[system prompt]")` -> `ChatAuto(system_prompt="[system prompt]")`. In addition, the `provider` and `model` keyword arguments are now deprecated, but continue to work with a warning, as are the previous `CHATLAS_CHAT_PROVIDER` and `CHATLAS_CHAT_MODEL` environment variables. (#159)
+
+### New features
+
+* `ChatAuto()`'s new `provider_model` takes both provider and model in a single string in the format `"{provider}/{model}"`, e.g. `"openai/gpt-5"`. If not provided, `ChatAuto()` looks for the `CHATLAS_CHAT_PROVIDER_MODEL` environment variable, defaulting to `"openai"` if neither are provided. Unlike previous versions of `ChatAuto()`, the environment variables are now used *only if function arguments are not provided*. In other words, if `provider_model` is given, the `CHATLAS_CHAT_PROVIDER_MODEL` environment variable is ignored. Similarly, `CHATLAS_CHAT_ARGS` are only used if no `kwargs` are provided. This improves interactive use cases, makes it easier to introduce application-specific environment variables, and puts more control in the hands of the developer. (#159)
+* The `.register_tool()` method now: 
+  * Accepts a `Tool` instance as input. This is primarily useful for binding things like `annotations` to the `Tool` in one place, and registering it in another. (#172)
+  * Supports function parameter names that start with an underscore. (#174)
+* The `ToolAnnotations` type gains an `extra` key field -- providing a place for providing additional information that other consumers of tool annotations (e.g., [shinychat](https://posit-dev.github.io/shinychat/)) may make use of.
+
+### Bug fixes
+
+* `ChatAuto()` now supports recently added providers such as `ChatCloudflare()`, `ChatDeepseek()`, `ChatHuggingFace()`, etc. (#159)
+
+## [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
@@ -26,7 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New features
 
-* Added `ChatCloudflare()` for chatting via [Cloudflare AI](https://developers.cloudflare.com/workers-ai/get-started/rest-api/). (#150) 
+* Added `ChatCloudflare()` for chatting via [Cloudflare AI](https://developers.cloudflare.com/workers-ai/get-started/rest-api/). (#150)
 * Added `ChatDeepSeek()` for chatting via [DeepSeek](https://www.deepseek.com/). (#147)
 * Added `ChatOpenRouter()` for chatting via [Open Router](https://openrouter.ai/). (#148)
 * Added `ChatHuggingFace()` for chatting via [Hugging Face](https://huggingface.co/). (#144)
@@ -62,7 +95,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New features
 
-* `Chat` gains a handful of new methods: 
+* `Chat` gains a handful of new methods:
     * `.register_mcp_tools_http_stream_async()` and `.register_mcp_tools_stdio_async()`: for registering tools from a [MCP server](https://modelcontextprotocol.io/). (#39)
     * `.get_tools()` and `.set_tools()`: for fine-grained control over registered tools. (#39)
     * `.set_model_params()`: for setting common LLM parameters in a model-agnostic fashion. (#127)
@@ -71,7 +104,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Tool functions passed to `.register_tool()` can now `yield` numerous results. (#39)
 * A `ContentToolResultImage` content class was added for returning images from tools. It is currently only works with `ChatAnthropic`. (#39)
 * A `Tool` can now be constructed from a pre-existing tool schema (via a new `__init__` method). (#39)
-* The `Chat.app()` method gains a `host` parameter. (#122) 
+* The `Chat.app()` method gains a `host` parameter. (#122)
 * `ChatGithub()` now supports the more standard `GITHUB_TOKEN` environment variable for storing the API key. (#123)
 
 ### Changes
@@ -133,7 +166,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.7.1] - 2025-05-10
 
-* Added `openai` as a hard dependency, making installation easier for a wide range of use cases. (#91) 
+* Added `openai` as a hard dependency, making installation easier for a wide range of use cases. (#91)
 
 ## [0.7.0] - 2025-04-22
 
@@ -143,7 +176,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * `.stream()` and `.stream_async()` gain a `content` argument. Set this to `"all"` to include `ContentToolResult`/`ContentToolRequest` objects in the stream. (#75)
 * `ContentToolResult`/`ContentToolRequest` are now exported to `chatlas` namespace. (#75)
 * `ContentToolResult`/`ContentToolRequest` gain a `.tagify()` method so they render sensibly in a Shiny app. (#75)
-* A tool can now return a `ContentToolResult`. This is useful for: 
+* A tool can now return a `ContentToolResult`. This is useful for:
     * Specifying the format used for sending the tool result to the chat model (`model_format`). (#87)
     * Custom rendering of the tool result (by overriding relevant methods in a subclass). (#75)
 * `Chat` gains a new `.current_display` property. When a `.chat()` or `.stream()` is currently active, this property returns an object with a `.echo()` method (to echo new content to the display). This is primarily useful for displaying custom content during a tool call. (#79)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatlas
-Version: 0.11.0
+Version: 0.12.0
 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.12.0/chatlas/_auto.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import os
+import warnings
+from typing import Callable, Literal, Optional
+
+import orjson
+
+from ._chat import Chat
+from ._provider_anthropic import ChatAnthropic, ChatBedrockAnthropic
+from ._provider_cloudflare import ChatCloudflare
+from ._provider_databricks import ChatDatabricks
+from ._provider_deepseek import ChatDeepSeek
+from ._provider_github import ChatGithub
+from ._provider_google import ChatGoogle, ChatVertex
+from ._provider_groq import ChatGroq
+from ._provider_huggingface import ChatHuggingFace
+from ._provider_mistral import ChatMistral
+from ._provider_ollama import ChatOllama
+from ._provider_openai import ChatAzureOpenAI, ChatOpenAI
+from ._provider_openrouter import ChatOpenRouter
+from ._provider_perplexity import ChatPerplexity
+from ._provider_portkey import ChatPortkey
+from ._provider_snowflake import ChatSnowflake
+from ._utils import MISSING_TYPE as DEPRECATED_TYPE
+
+AutoProviders = Literal[
+    "anthropic",
+    "bedrock-anthropic",
+    "cloudflare",
+    "databricks",
+    "deep-seek",
+    "github",
+    "google",
+    "groq",
+    "hugging-face",
+    "mistral",
+    "ollama",
+    "openai",
+    "azure-openai",
+    "open-router",
+    "perplexity",
+    "portkey",
+    "snowflake",
+    "vertex",
+]
+
+_provider_chat_model_map: dict[AutoProviders, Callable[..., Chat]] = {
+    "anthropic": ChatAnthropic,
+    "bedrock-anthropic": ChatBedrockAnthropic,
+    "cloudflare": ChatCloudflare,
+    "databricks": ChatDatabricks,
+    "deep-seek": ChatDeepSeek,
+    "github": ChatGithub,
+    "google": ChatGoogle,
+    "groq": ChatGroq,
+    "hugging-face": ChatHuggingFace,
+    "mistral": ChatMistral,
+    "ollama": ChatOllama,
+    "openai": ChatOpenAI,
+    "azure-openai": ChatAzureOpenAI,
+    "open-router": ChatOpenRouter,
+    "perplexity": ChatPerplexity,
+    "portkey": ChatPortkey,
+    "snowflake": ChatSnowflake,
+    "vertex": ChatVertex,
+}
+
+DEPRECATED = DEPRECATED_TYPE()
+
+
+def ChatAuto(
+    provider_model: Optional[str] = None,
+    *,
+    system_prompt: Optional[str] = None,
+    provider: AutoProviders | DEPRECATED_TYPE = DEPRECATED,
+    model: str | DEPRECATED_TYPE = DEPRECATED,
+    **kwargs,
+) -> Chat:
+    """
+    Chat with any provider.
+
+    This is a generic interface to all the other `Chat*()` functions, allowing
+    you to pick the provider (and model) with a simple string.
+
+    Prerequisites
+    -------------
+
+    ::: {.callout-note}
+    ## API key
+
+    Follow the instructions for the specific provider to obtain an API key.
+    :::
+
+    ::: {.callout-note}
+    ## Python requirements
+
+    Follow the instructions for the specific provider to install the required
+    Python packages.
+    :::
+
+    Examples
+    --------
+
+    `ChatAuto()` makes it easy to switch between different chat providers and models.
+
+    ```python
+    import pandas as pd
+    from chatlas import ChatAuto
+
+    # Default provider (OpenAI) & model
+    chat = ChatAuto()
+    print(chat.provider.name)
+    print(chat.provider.model)
+
+    # Different provider (Anthropic) & default model
+    chat = ChatAuto("anthropic")
+
+    # List models available through the provider
+    models = chat.list_models()
+    print(pd.DataFrame(models))
+
+    # Choose specific provider/model (Claude Sonnet 4)
+    chat = ChatAuto("anthropic/claude-sonnet-4-0")
+    ```
+
+    The default provider/model can also be controlled through an environment variable:
+
+    ```bash
+    export CHATLAS_CHAT_PROVIDER_MODEL="anthropic/claude-sonnet-4-0"
+    ```
+
+    ```python
+    from chatlas import ChatAuto
+
+    chat = ChatAuto()
+    print(chat.provider.name)   # anthropic
+    print(chat.provider.model)  # claude-sonnet-4-0
+    ```
+
+    For application-specific configurations, consider defining your own environment variables:
+
+    ```bash
+    export MYAPP_PROVIDER_MODEL="google/gemini-2.5-flash"
+    ```
+
+    And passing them to `ChatAuto()` as an alternative way to configure the provider/model:
+
+    ```python
+    import os
+    from chatlas import ChatAuto
+
+    chat = ChatAuto(os.getenv("MYAPP_PROVIDER_MODEL"))
+    print(chat.provider.name)   # google
+    print(chat.provider.model)  # gemini-2.5-flash
+    ```
+
+    Parameters
+    ----------
+    provider_model
+        The name of the provider and model to use in the format
+        `"{provider}/{model}"`. Providers are strings formatted in kebab-case,
+        e.g. to use `ChatBedrockAnthropic` set `provider="bedrock-anthropic"`,
+        and models are the provider-specific model names, e.g.
+        `"claude-3-7-sonnet-20250219"`. The `/{model}` portion may also be
+        omitted, in which case, the default model for that provider will be
+        used.
+
+        If no value is provided, the `CHATLAS_CHAT_PROVIDER_MODEL` environment
+        variable will be consulted for a fallback value. If this variable is also
+        not set, a default value of `"openai"` is used.
+    system_prompt
+        A system prompt to set the behavior of the assistant.
+    provider
+        Deprecated; use `provider_model` instead.
+    model
+        Deprecated; use `provider_model` instead.
+    **kwargs
+        Additional keyword arguments to pass to the `Chat` constructor. See the
+        documentation for each provider for more details on the available
+        options.
+
+        These arguments can also be provided via the `CHATLAS_CHAT_ARGS`
+        environment variable as a JSON string. When any additional arguments are
+        provided to `ChatAuto()`, the env var is ignored.
+
+        Note that `system_prompt` and `turns` can't be set via environment variables.
+        They must be provided/set directly to/on `ChatAuto()`.
+
+    Note
+    ----
+    If you want to work with a specific provider, but don't know what models are
+    available (or the exact model name), use
+    `ChatAuto('provider_name').list_models()` to list available models. Another
+    option is to use the provider more directly (e.g., `ChatAnthropic()`). There,
+    the `model` parameter may have type hints for available models.
+
+    Returns
+    -------
+    Chat
+        A chat instance using the specified provider.
+
+    Raises
+    ------
+    ValueError
+        If no valid provider is specified either through parameters or
+        environment variables.
+    """
+    if provider is not DEPRECATED:
+        warn_deprecated_param("provider")
+
+    if model is not DEPRECATED:
+        if provider is DEPRECATED:
+            raise ValueError(
+                "The `model` parameter is deprecated and cannot be used without the `provider` parameter. "
+                "Use `provider_model` instead."
+            )
+        warn_deprecated_param("model")
+
+    if provider_model is None:
+        provider_model = os.environ.get("CHATLAS_CHAT_PROVIDER_MODEL")
+
+    # Backwards compatibility: construct from old env vars as a fallback
+    if provider_model is None:
+        env_provider = get_legacy_env_var("CHATLAS_CHAT_PROVIDER", provider)
+        env_model = get_legacy_env_var("CHATLAS_CHAT_MODEL", model)
+
+        if env_provider:
+            provider_model = env_provider
+            if env_model:
+                provider_model += f"/{env_model}"
+
+    # Fall back to OpenAI if nothing is specified
+    if provider_model is None:
+        provider_model = "openai"
+
+    if "/" in provider_model:
+        the_provider, the_model = provider_model.split("/", 1)
+    else:
+        the_provider, the_model = provider_model, None
+
+    if the_provider not in _provider_chat_model_map:
+        raise ValueError(
+            f"Provider name '{the_provider}' is not a known chatlas provider: "
+            f"{', '.join(_provider_chat_model_map.keys())}"
+        )
+
+    # `system_prompt`, `turns` and `model` always come from `ChatAuto()`
+    base_args = {
+        "system_prompt": system_prompt,
+        "turns": None,
+        "model": the_model,
+    }
+
+    # Environment kwargs, used only if no kwargs provided
+    env_kwargs = {}
+    if not kwargs:
+        env_kwargs = orjson.loads(os.environ.get("CHATLAS_CHAT_ARGS", "{}"))
+
+    final_kwargs = {**env_kwargs, **kwargs, **base_args}
+    final_kwargs = {k: v for k, v in final_kwargs.items() if v is not None}
+
+    return _provider_chat_model_map[the_provider](**final_kwargs)
+
+
+def get_legacy_env_var(
+    env_var_name: str,
+    default: str | DEPRECATED_TYPE,
+) -> str | None:
+    env_value = os.environ.get(env_var_name)
+    if env_value:
+        warnings.warn(
+            f"The '{env_var_name}' environment variable is deprecated. "
+            "Use 'CHATLAS_CHAT_PROVIDER_MODEL' instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return env_value
+    elif isinstance(default, DEPRECATED_TYPE):
+        return None
+    else:
+        return default
+
+
+def warn_deprecated_param(param_name: str, stacklevel: int = 3) -> None:
+    warnings.warn(
+        f"The '{param_name}' parameter is deprecated. Use 'provider_model' instead.",
+        DeprecationWarning,
+        stacklevel=stacklevel,
+    )

{chatlas-0.11.0 → chatlas-0.12.0}/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):
@@ -1534,9 +1535,10 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
 
     def register_tool(
         self,
-        func: Callable[..., Any] | Callable[..., Awaitable[Any]],
+        func: Callable[..., Any] | Callable[..., Awaitable[Any]] | Tool,
         *,
         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,22 @@ 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)
+        if isinstance(func, Tool):
+            name = name or func.name
+            annotations = annotations or func.annotations
+            if model is not None:
+                func = Tool.from_func(
+                    func.func, name=name, model=model, annotations=annotations
+                )
+            func = func.func
+
+        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 +1946,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 +2009,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 +2169,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 +2217,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.12.0}/chatlas/_content.py

@@ -6,9 +6,64 @@ from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 import orjson
 from pydantic import BaseModel, ConfigDict
 
+from ._typing_extensions import 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: str
+    """A human-readable title for the tool."""
+
+    readOnlyHint: bool
+    """
+    If true, the tool does not modify its environment.
+    Default: false
+    """
+
+    destructiveHint: 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: 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: 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
+    """
+
+    extra: dict[str, Any]
+    """
+    Additional metadata about the tool.
+    """
+
+
 ImageContentTypes = Literal[
     "image/png",
     "image/jpeg",
@@ -19,6 +74,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 +269,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"