chatlas 0.11.1__tar.gz → 0.12.0__tar.gz

{chatlas-0.11.1 → 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.1 → chatlas-0.12.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ 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
@@ -22,7 +40,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `.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
@@ -42,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)
@@ -78,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)
@@ -87,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
@@ -149,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
 
@@ -159,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.1 → chatlas-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatlas
-Version: 0.11.1
+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.1 → chatlas-0.12.0}/chatlas/_chat.py

@@ -1535,7 +1535,7 @@ 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,
@@ -1629,6 +1629,15 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         ValueError
             If a tool with the same name already exists and `force` is `False`.
         """
+        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(

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

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 import orjson
 from pydantic import BaseModel, ConfigDict
 
-from ._typing_extensions import NotRequired, TypedDict
+from ._typing_extensions import TypedDict
 
 if TYPE_CHECKING:
     from ._tools import Tool
@@ -24,16 +24,16 @@ class ToolAnnotations(TypedDict, total=False):
     received from untrusted servers.
     """
 
-    title: NotRequired[str]
+    title: str
     """A human-readable title for the tool."""
 
-    readOnlyHint: NotRequired[bool]
+    readOnlyHint: bool
     """
     If true, the tool does not modify its environment.
     Default: false
     """
 
-    destructiveHint: NotRequired[bool]
+    destructiveHint: bool
     """
     If true, the tool may perform destructive updates to its environment.
     If false, the tool performs only additive updates.
@@ -41,7 +41,7 @@ class ToolAnnotations(TypedDict, total=False):
     Default: true
     """
 
-    idempotentHint: NotRequired[bool]
+    idempotentHint: bool
     """
     If true, calling the tool repeatedly with the same arguments
     will have no additional effect on the its environment.
@@ -49,7 +49,7 @@ class ToolAnnotations(TypedDict, total=False):
     Default: false
     """
 
-    openWorldHint: NotRequired[bool]
+    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.
@@ -58,6 +58,11 @@ class ToolAnnotations(TypedDict, total=False):
     Default: true
     """
 
+    extra: dict[str, Any]
+    """
+    Additional metadata about the tool.
+    """
+
 
 ImageContentTypes = Literal[
     "image/png",

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

@@ -326,13 +326,21 @@ def func_to_basemodel(func: Callable) -> type[BaseModel]:
             )
             annotation = Any
 
+        # create_model() will error if the field name starts with `_` (since Pydantic
+        # uses this to indicate private fields). We can work around this by using an alias.
+        alias = None
+        if name.startswith("_"):
+            field_name, alias = (name.lstrip("_"), name)
+        else:
+            field_name, alias = (name, None)
+
         if param.default != inspect.Parameter.empty:
-            field = Field(default=param.default)
+            field = Field(default=param.default, alias=alias)
         else:
-            field = Field()
+            field = Field(alias=alias)
 
         # Add the field to our fields dict
-        fields[name] = (annotation, field)
+        fields[field_name] = (annotation, field)
 
     return create_model(func.__name__, **fields)
 

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

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

{chatlas-0.11.1 → chatlas-0.12.0}/chatlas/types/anthropic/_submit.py

@@ -3,7 +3,7 @@
 # ---------------------------------------------------------
 
 
-from typing import Iterable, Literal, Mapping, Optional, TypedDict, Union
+from typing import Iterable, Literal, Mapping, Optional, Sequence, TypedDict, Union
 
 import anthropic
 import anthropic.types.message_param
@@ -48,7 +48,7 @@ class SubmitInputArgs(TypedDict, total=False):
         str,
     ]
     service_tier: Union[Literal["auto", "standard_only"], anthropic.NotGiven]
-    stop_sequences: Union[list[str], anthropic.NotGiven]
+    stop_sequences: Union[Sequence[str], anthropic.NotGiven]
     stream: Union[Literal[False], Literal[True], anthropic.NotGiven]
     system: Union[
         str,

{chatlas-0.11.1 → chatlas-0.12.0}/chatlas/types/openai/_client.py

@@ -3,14 +3,14 @@
 # ---------------------------------------------------------
 
 
-from typing import Mapping, Optional, TypedDict, Union
+from typing import Awaitable, Callable, Mapping, Optional, TypedDict, Union
 
 import httpx
 import openai
 
 
 class ChatClientArgs(TypedDict, total=False):
-    api_key: str | None
+    api_key: Union[str, Callable[[], Awaitable[str]], None]
     organization: str | None
     project: str | None
     webhook_secret: str | None

{chatlas-0.11.1 → chatlas-0.12.0}/chatlas/types/openai/_client_azure.py

@@ -2,7 +2,7 @@
 # Do not modify this file. It was generated by `scripts/generate_typed_dicts.py`.
 # ---------------------------------------------------------
 
-from typing import Mapping, Optional, TypedDict
+from typing import Awaitable, Callable, Mapping, Optional, TypedDict, Union
 
 import httpx
 import openai
@@ -12,7 +12,7 @@ class ChatAzureClientArgs(TypedDict, total=False):
     azure_endpoint: str | None
     azure_deployment: str | None
     api_version: str | None
-    api_key: str | None
+    api_key: Union[str, Callable[[], Awaitable[str]], None]
     azure_ad_token: str | None
     organization: str | None
     project: str | None

{chatlas-0.11.1 → chatlas-0.12.0}/chatlas/types/openai/_submit.py

@@ -3,7 +3,7 @@
 # ---------------------------------------------------------
 
 
-from typing import Iterable, Literal, Mapping, Optional, TypedDict, Union
+from typing import Iterable, Literal, Mapping, Optional, Sequence, TypedDict, Union
 
 import openai
 import openai.types.chat.chat_completion_allowed_tool_choice_param
@@ -148,7 +148,7 @@ class SubmitInputArgs(TypedDict, total=False):
     service_tier: Union[
         Literal["auto", "default", "flex", "scale", "priority"], None, openai.NotGiven
     ]
-    stop: Union[str, None, list[str], openai.NotGiven]
+    stop: Union[str, None, Sequence[str], openai.NotGiven]
     store: Union[bool, None, openai.NotGiven]
     stream: Union[Literal[False], None, Literal[True], openai.NotGiven]
     stream_options: Union[

{chatlas-0.11.1 → chatlas-0.12.0}/docs/get-started/models.qmd

@@ -64,12 +64,38 @@ If you're using `chatlas` inside your organisation, you'll be limited to what yo
 - `ChatOllama()`, which uses [Ollama](https://ollama.com), allows you to run models on your own computer. The biggest models you can run locally aren't as good as the state of the art hosted models, but they also don't share your data and and are effectively free.
 
 
-### Auto complete
+### Model type hints
 
-Some providers like `ChatOpenAI()` and `ChatAnthropic()` provide autocompletion for the `model` parameter. This makes it quick and easy to find the right model id -- just enter `model=""` and you'll get a list of available models to choose from (assuming your IDE supports type hints).
+Some providers like `ChatOpenAI()` and `ChatAnthropic()` provide type hints for the `model` parameter. This makes it quick and easy to find the right model id -- just enter `model=""` and you'll get a list of available models to choose from (assuming your IDE supports type hints).
 
 ![Screenshot of model autocompletion](/images/model-type-hints.png){class="shadow rounded mb-3" width="67%" }
 
+::: callout-tip
+If the provider doesn't provide these type hints, try using the `.list_models()` method (mentioned below) to find available models.
+:::
+
+
+### Auto provider
+
+[`ChatAuto()`](../reference/ChatAuto.qmd) provides access to any provider/model combination through one simple string.
+This makes for a nice interactive/prototyping experience, where you can quickly switch between different models and providers, and leverage `chatlas`' smart defaults:
+
+```python
+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")
+
+# Choose specific provider/model (Claude Sonnet 4)
+chat = ChatAuto("anthropic/claude-sonnet-4-0")
+```
+
+
 ### Listing model info
 
 Most providers support the `.list_models()` method, which returns detailed information about all available models, including model IDs, pricing, and metadata. This is particularly useful for:
@@ -107,8 +133,3 @@ Different providers may include different metadata fields in the model informati
 
 - **`id`**: Model identifier to use with the `Chat` constructor
 - **`input`/`output`/`cached_input`**: Token pricing in USD per million tokens
-
-
-### Auto provider
-
-[`ChatAuto()`](../reference/ChatAuto.qmd) is a special model provider that allows one to configure the model provider through environment variables. This is useful for having a single, simple, script that can run on any model provider, without having to change the code.

{chatlas-0.11.1 → chatlas-0.12.0}/scripts/_generate_openai_types.py

@@ -1,10 +1,9 @@
 from pathlib import Path
 
+from _utils import generate_typeddict_code, write_code_to_file
 from openai import AsyncAzureOpenAI, AsyncOpenAI
 from openai.resources.chat import Completions
 
-from _utils import generate_typeddict_code, write_code_to_file
-
 types_dir = Path(__file__).parent.parent / "chatlas" / "types"
 provider_dir = types_dir / "openai"
 
@@ -28,12 +27,22 @@ init_args = generate_typeddict_code(
     excluded_fields={"self"},
 )
 
+
+# Temporary workaround for an issue where a type like
+#   Callable[[], Awaitable[str]]
+# is getting incorrectly transpiled as
+#   Callable[Awaitable[str]]
+def fix_callable_types(text: str):
+    return text.replace("Callable[Awaitable[str]]", "Callable[[], Awaitable[str]]")
+
+
+init_args = fix_callable_types(init_args)
+
 write_code_to_file(
     init_args,
     provider_dir / "_client.py",
 )
 
-
 init_args = generate_typeddict_code(
     AsyncAzureOpenAI.__init__,
     "ChatAzureClientArgs",
@@ -44,6 +53,8 @@ init_args = generate_typeddict_code(
     },
 )
 
+init_args = fix_callable_types(init_args)
+
 write_code_to_file(
     init_args,
     provider_dir / "_client_azure.py",