chatlas 0.9.2__py3-none-any.whl → 0.11.0__py3-none-any.whl

chatlas/__init__.py

@@ -1,19 +1,30 @@
 from . import types
 from ._auto import ChatAuto
 from ._chat import Chat
-from ._content import ContentToolRequest, ContentToolResult, ContentToolResultImage
+from ._content import (
+    ContentToolRequest,
+    ContentToolResult,
+    ContentToolResultImage,
+    ContentToolResultResource,
+)
 from ._content_image import content_image_file, content_image_plot, content_image_url
 from ._content_pdf import content_pdf_file, content_pdf_url
 from ._interpolate import interpolate, interpolate_file
 from ._provider import Provider
 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 ._tokens import token_usage
 from ._tools import Tool, ToolRejectError
@@ -28,14 +39,20 @@ __all__ = (
     "ChatAnthropic",
     "ChatAuto",
     "ChatBedrockAnthropic",
+    "ChatCloudflare",
     "ChatDatabricks",
+    "ChatDeepSeek",
     "ChatGithub",
     "ChatGoogle",
     "ChatGroq",
+    "ChatHuggingFace",
+    "ChatMistral",
     "ChatOllama",
     "ChatOpenAI",
+    "ChatOpenRouter",
     "ChatAzureOpenAI",
     "ChatPerplexity",
+    "ChatPortkey",
     "ChatSnowflake",
     "ChatVertex",
     "Chat",
@@ -47,6 +64,7 @@ __all__ = (
     "ContentToolRequest",
     "ContentToolResult",
     "ContentToolResultImage",
+    "ContentToolResultResource",
     "interpolate",
     "interpolate_file",
     "Provider",
@@ -56,3 +74,9 @@ __all__ = (
     "Turn",
     "types",
 )
+
+# Rebuild content models to resolve forward references to ToolAnnotation
+ContentToolRequest.model_rebuild()
+ContentToolResult.model_rebuild()
+ContentToolResultImage.model_rebuild()
+ContentToolResultResource.model_rebuild()

chatlas/_chat.py

@@ -9,6 +9,7 @@ import warnings
 from pathlib import Path
 from threading import Thread
 from typing import (
+    TYPE_CHECKING,
     Any,
     AsyncGenerator,
     AsyncIterator,
@@ -43,13 +44,16 @@ from ._display import (
 )
 from ._logging import log_tool_error
 from ._mcp_manager import MCPSessionManager
-from ._provider import Provider, StandardModelParams, SubmitInputArgsT
+from ._provider import ModelInfo, Provider, StandardModelParams, SubmitInputArgsT
 from ._tokens import compute_cost, get_token_pricing
 from ._tools import Tool, ToolRejectError
 from ._turn import Turn, user_turn
 from ._typing_extensions import TypedDict, TypeGuard
 from ._utils import MISSING, MISSING_TYPE, html_escape, wrap_async
 
+if TYPE_CHECKING:
+    from mcp.types import ToolAnnotations
+
 
 class TokensDict(TypedDict):
     """
@@ -128,6 +132,78 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         self._standard_model_params: StandardModelParams = {}
         self._submit_input_kwargs: Optional[SubmitInputArgsT] = None
 
+    def list_models(self) -> list[ModelInfo]:
+        """
+        List all models available for the provider.
+
+        This method returns detailed information about all models supported by the provider,
+        including model IDs, pricing information, creation dates, and other metadata. This is
+        useful for discovering available models and their characteristics without needing to
+        consult provider documentation.
+
+        Examples
+        --------
+        Get all available models:
+
+        ```python
+        from chatlas import ChatOpenAI
+
+        chat = ChatOpenAI()
+        models = chat.list_models()
+        print(f"Found {len(models)} models")
+        print(f"First model: {models[0]['id']}")
+        ```
+
+        View models in a table format:
+
+        ```python
+        import pandas as pd
+        from chatlas import ChatAnthropic
+
+        chat = ChatAnthropic()
+        df = pd.DataFrame(chat.list_models())
+        print(df[["id", "input", "output"]].head())  # Show pricing info
+        ```
+
+        Find models by criteria:
+
+        ```python
+        from chatlas import ChatGoogle
+
+        chat = ChatGoogle()
+        models = chat.list_models()
+
+        # Find cheapest input model
+        cheapest = min(models, key=lambda m: m.get("input", float("inf")))
+        print(f"Cheapest model: {cheapest['id']}")
+        ```
+
+        Returns
+        -------
+        list[ModelInfo]
+            A list of ModelInfo dictionaries containing model information. Each dictionary
+            contains:
+
+            - `id` (str): The model identifier to use with the Chat constructor
+            - `name` (str, optional): Human-readable model name
+            - `input` (float, optional): Cost per input token in USD per million tokens
+            - `output` (float, optional): Cost per output token in USD per million tokens
+            - `cached_input` (float, optional): Cost per cached input token in USD per million tokens
+            - `created_at` (date, optional): Date the model was created
+            - `owned_by` (str, optional): Organization that owns the model
+            - `provider` (str, optional): Model provider name
+            - `size` (int, optional): Model size in bytes
+            - `url` (str, optional): URL with more information about the model
+
+            The list is typically sorted by creation date (most recent first).
+
+        Note
+        ----
+        Not all providers support this method. Some providers may raise NotImplementedError
+        with information about where to find model listings online.
+        """
+        return self.provider.list_models()
+
     def get_turns(
         self,
         *,
@@ -395,8 +471,8 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
                 )
 
             input_token_price = price_token["input"] / 1e6
-            output_token_price = price_token["output"] / 1e6
-            cached_token_price = price_token["cached_input"] / 1e6
+            output_token_price = price_token.get("output", 0) / 1e6
+            cached_token_price = price_token.get("cached_input", 0) / 1e6
 
         if len(turns_tokens) == 0:
             return 0.0
@@ -1462,6 +1538,7 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         *,
         force: bool = False,
         model: Optional[type[BaseModel]] = None,
+        annotations: "Optional[ToolAnnotations]" = None,
     ):
         """
         Register a tool (function) with the chat.
@@ -1539,13 +1616,16 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             The primary reason why you might want to provide a model in
             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.
 
         Raises
         ------
         ValueError
             If a tool with the same name already exists and `force` is `False`.
         """
-        tool = Tool.from_func(func, model=model)
+        tool = Tool.from_func(func, model=model, annotations=annotations)
         if tool.name in self._tools and not force:
             raise ValueError(
                 f"Tool with name '{tool.name}' is already registered. "
@@ -1853,6 +1933,7 @@ 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)
                     if echo == "output":
                         self._echo_content(f"\n\n{x}\n\n")
                     if content == "all":
@@ -1913,6 +1994,7 @@ 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)
                     if echo == "output":
                         self._echo_content(f"\n\n{x}\n\n")
                     if content == "all":
@@ -2070,8 +2152,8 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         self._turns.extend([user_turn, turn])
 
     def _invoke_tool(self, request: ContentToolRequest):
-        tool_def = self._tools.get(request.name, None)
-        func = tool_def.func if tool_def is not None else None
+        tool = request.tool
+        func = tool.func if tool is not None else None
 
         if func is None:
             yield self._handle_tool_error_result(
@@ -2118,21 +2200,20 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             yield self._handle_tool_error_result(request, e)
 
     async def _invoke_tool_async(self, request: ContentToolRequest):
-        tool_def = self._tools.get(request.name, None)
-        func = None
-        if tool_def:
-            if tool_def._is_async:
-                func = tool_def.func
-            else:
-                func = wrap_async(tool_def.func)
+        tool = request.tool
 
-        if func is None:
+        if tool is None:
             yield self._handle_tool_error_result(
                 request,
                 error=RuntimeError("Unknown tool."),
             )
             return
 
+        if tool._is_async:
+            func = tool.func
+        else:
+            func = wrap_async(tool.func)
+
         # First, invoke the request callbacks. If a ToolRejectError is raised,
         # treat it like a tool failure (i.e., gracefully handle it).
         result: ContentToolResult | None = None

chatlas/_content.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 from pprint import pformat
-from typing import Any, Literal, Optional, Union
+from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 
 import orjson
 from pydantic import BaseModel, ConfigDict
 
+if TYPE_CHECKING:
+    from ._tools import Tool
+
 ImageContentTypes = Literal[
     "image/png",
     "image/jpeg",
@@ -171,11 +174,15 @@ class ContentToolRequest(Content):
         The name of the tool/function to call.
     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.
     """
 
     id: str
     name: str
     arguments: object
+    tool: Optional["Tool"] = None
 
     content_type: ContentTypeEnum = "tool_request"
 

chatlas/_provider.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from datetime import date
 from typing import (
     AsyncIterable,
     Generic,
@@ -16,7 +17,7 @@ from pydantic import BaseModel
 from ._content import Content
 from ._tools import Tool
 from ._turn import Turn
-from ._typing_extensions import TypedDict
+from ._typing_extensions import NotRequired, TypedDict
 
 ChatCompletionT = TypeVar("ChatCompletionT")
 ChatCompletionChunkT = TypeVar("ChatCompletionChunkT")
@@ -35,6 +36,40 @@ submitting input to a model provider.
 """
 
 
+class ModelInfo(TypedDict):
+    "Information returned from the `.list_models()` method"
+
+    id: str
+    "The model ID (this gets passed to the `model` parameter of the `Chat` constructor)"
+
+    cached_input: NotRequired[float | None]
+    "The cost per user token in USD per million tokens for cached input"
+
+    input: NotRequired[float | None]
+    "The cost per user token in USD per million tokens"
+
+    output: NotRequired[float | None]
+    "The cost per assistant token in USD per million tokens"
+
+    created_at: NotRequired[date]
+    "The date the model was created"
+
+    name: NotRequired[str]
+    "The model name"
+
+    owned_by: NotRequired[str]
+    "The owner of the model"
+
+    size: NotRequired[int]
+    "The size of the model in bytes"
+
+    provider: NotRequired[str]
+    "The provider of the model"
+
+    url: NotRequired[str]
+    "A URL to learn more about the model"
+
+
 class StandardModelParams(TypedDict, total=False):
     """
     A TypedDict representing the standard model parameters that can be set
@@ -102,6 +137,13 @@ class Provider(
         """
         return self._model
 
+    @abstractmethod
+    def list_models(self) -> list[ModelInfo]:
+        """
+        List all available models for the provider.
+        """
+        pass
+
     @overload
     @abstractmethod
     def chat_perform(

chatlas/_provider_anthropic.py

@@ -21,8 +21,8 @@ from ._content import (
     ContentToolResultResource,
 )
 from ._logging import log_model_default
-from ._provider import Provider, StandardModelParamNames, StandardModelParams
-from ._tokens import tokens_log
+from ._provider import ModelInfo, Provider, StandardModelParamNames, StandardModelParams
+from ._tokens import get_token_pricing, tokens_log
 from ._tools import Tool, basemodel_to_param_schema
 from ._turn import Turn, user_turn
 from ._utils import split_http_client_kwargs
@@ -163,7 +163,7 @@ def ChatAnthropic(
     """
 
     if model is None:
-        model = log_model_default("claude-3-7-sonnet-latest")
+        model = log_model_default("claude-sonnet-4-0")
 
     return Chat(
         provider=AnthropicProvider(
@@ -209,6 +209,30 @@ class AnthropicProvider(
         self._client = Anthropic(**sync_kwargs)  # type: ignore
         self._async_client = AsyncAnthropic(**async_kwargs)
 
+    def list_models(self):
+        models = self._client.models.list()
+
+        res: list[ModelInfo] = []
+        for m in models:
+            pricing = get_token_pricing(self.name, m.id) or {}
+            info: ModelInfo = {
+                "id": m.id,
+                "name": m.display_name,
+                "created_at": m.created_at.date(),
+                "input": pricing.get("input"),
+                "output": pricing.get("output"),
+                "cached_input": pricing.get("cached_input"),
+            }
+            res.append(info)
+
+        # Sort list by created_by field (more recent first)
+        res.sort(
+            key=lambda x: x.get("created_at", 0),
+            reverse=True,
+        )
+
+        return res
+
     @overload
     def chat_perform(
         self,
@@ -742,8 +766,7 @@ def ChatBedrockAnthropic(
     """
 
     if model is None:
-        # Default model from https://github.com/anthropics/anthropic-sdk-python?tab=readme-ov-file#aws-bedrock
-        model = log_model_default("anthropic.claude-3-5-sonnet-20241022-v2:0")
+        model = log_model_default("us.anthropic.claude-sonnet-4-20250514-v1:0")
 
     return Chat(
         provider=AnthropicBedrockProvider(
@@ -798,3 +821,26 @@ class AnthropicBedrockProvider(AnthropicProvider):
 
         self._client = AnthropicBedrock(**kwargs_full)  # type: ignore
         self._async_client = AsyncAnthropicBedrock(**kwargs_full)  # type: ignore
+
+    def list_models(self):
+        # boto3 should come via anthropic's bedrock extras
+        import boto3
+
+        bedrock = boto3.client("bedrock")
+        resp = bedrock.list_foundation_models()
+        models = resp["modelSummaries"]
+
+        res: list[ModelInfo] = []
+        for m in models:
+            pricing = get_token_pricing(self.name, m["modelId"]) or {}
+            info: ModelInfo = {
+                "id": m["modelId"],
+                "name": m["modelName"],
+                "provider": m["providerName"],
+                "input": pricing.get("input"),
+                "output": pricing.get("output"),
+                "cached_input": pricing.get("cached_input"),
+            }
+            res.append(info)
+
+        return res

chatlas/_provider_cloudflare.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Optional
+
+from ._chat import Chat
+from ._logging import log_model_default
+from ._provider_openai import OpenAIProvider
+from ._utils import MISSING, MISSING_TYPE, is_testing
+
+if TYPE_CHECKING:
+    from ._provider_openai import ChatCompletion
+    from .types.openai import ChatClientArgs, SubmitInputArgs
+
+
+def ChatCloudflare(
+    *,
+    account: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    model: Optional[str] = None,
+    api_key: Optional[str] = None,
+    seed: Optional[int] | MISSING_TYPE = MISSING,
+    kwargs: Optional["ChatClientArgs"] = None,
+) -> Chat["SubmitInputArgs", ChatCompletion]:
+    """
+    Chat with a model hosted on Cloudflare Workers AI.
+
+    Cloudflare Workers AI hosts a variety of open-source AI models.
+
+    Prerequisites
+    -------------
+
+    ::: {.callout-note}
+    ## API credentials
+
+    To use the Cloudflare API, you must have an Account ID and an Access Token,
+    which you can obtain by following the instructions at
+    <https://developers.cloudflare.com/workers-ai/get-started/rest-api/>.
+    :::
+
+    Examples
+    --------
+
+    ```python
+    import os
+    from chatlas import ChatCloudflare
+
+    chat = ChatCloudflare(
+        api_key=os.getenv("CLOUDFLARE_API_KEY"),
+        account=os.getenv("CLOUDFLARE_ACCOUNT_ID"),
+    )
+    chat.chat("What is the capital of France?")
+    ```
+
+    Known limitations
+    -----------------
+
+    - Tool calling does not appear to work.
+    - Images don't appear to work.
+
+    Parameters
+    ----------
+    account
+        The Cloudflare account ID. You generally should not supply this directly,
+        but instead set the `CLOUDFLARE_ACCOUNT_ID` environment variable.
+    system_prompt
+        A system prompt to set the behavior of the assistant.
+    model
+        The model to use for the chat. The default, None, will pick a reasonable
+        default, and warn you about it. We strongly recommend explicitly choosing
+        a model for all but the most casual use.
+    api_key
+        The API key to use for authentication. You generally should not supply
+        this directly, but instead set the `CLOUDFLARE_API_KEY` environment
+        variable.
+    seed
+        Optional integer seed that ChatGPT uses to try and make output more
+        reproducible.
+    kwargs
+        Additional arguments to pass to the `openai.OpenAI()` client constructor.
+
+    Returns
+    -------
+    Chat
+        A chat object that retains the state of the conversation.
+
+    Note
+    ----
+    This function is a lightweight wrapper around [](`~chatlas.ChatOpenAI`) with
+    the defaults tweaked for Cloudflare.
+
+    Note
+    ----
+    Pasting credentials into a chat constructor (e.g.,
+    `ChatCloudflare(api_key="...", account="...")`) is the simplest way to get
+    started, and is fine for interactive use, but is problematic for code that
+    may be shared with others.
+
+    Instead, consider using environment variables or a configuration file to manage
+    your credentials. One popular way to manage credentials is to use a `.env` file
+    to store your credentials, and then use the `python-dotenv` package to load them
+    into your environment.
+
+    ```shell
+    pip install python-dotenv
+    ```
+
+    ```shell
+    # .env
+    CLOUDFLARE_API_KEY=...
+    CLOUDFLARE_ACCOUNT_ID=...
+    ```
+
+    ```python
+    from chatlas import ChatCloudflare
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    chat = ChatCloudflare()
+    chat.console()
+    ```
+
+    Another, more general, solution is to load your environment variables into the shell
+    before starting Python (maybe in a `.bashrc`, `.zshrc`, etc. file):
+
+    ```shell
+    export CLOUDFLARE_API_KEY=...
+    export CLOUDFLARE_ACCOUNT_ID=...
+    ```
+    """
+    # List at https://developers.cloudflare.com/workers-ai/models/
+    # `@cf` appears to be part of the model name
+    if model is None:
+        model = log_model_default("@cf/meta/llama-3.3-70b-instruct-fp8-fast")
+
+    if api_key is None:
+        api_key = os.getenv("CLOUDFLARE_API_KEY")
+
+    if account is None:
+        account = os.getenv("CLOUDFLARE_ACCOUNT_ID")
+
+    if account is None:
+        raise ValueError(
+            "Cloudflare account ID is required. Set the CLOUDFLARE_ACCOUNT_ID "
+            "environment variable or pass the `account` parameter."
+        )
+
+    if isinstance(seed, MISSING_TYPE):
+        seed = 1014 if is_testing() else None
+
+    # https://developers.cloudflare.com/workers-ai/configuration/open-ai-compatibility/
+    cloudflare_api = "https://api.cloudflare.com/client/v4/accounts"
+    base_url = f"{cloudflare_api}/{account}/ai/v1/"
+
+    return Chat(
+        provider=CloudflareProvider(
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            seed=seed,
+            name="Cloudflare",
+            kwargs=kwargs,
+        ),
+        system_prompt=system_prompt,
+    )
+
+
+class CloudflareProvider(OpenAIProvider):
+    def list_models(self):
+        raise NotImplementedError(
+            ".list_models() is not yet implemented for Cloudflare. "
+            "To view model availability online, see https://developers.cloudflare.com/workers-ai/models/"
+        )

chatlas/_provider_databricks.py

@@ -127,3 +127,21 @@ class DatabricksProvider(OpenAIProvider):
             api_key="no-token",  # A placeholder to pass validations, this will not be used
             http_client=httpx.AsyncClient(auth=client._client.auth),
         )
+
+    def list_models(self):
+        raise NotImplementedError(
+            ".list_models() is not yet implemented for Databricks. "
+            "To view model availability online, see "
+            "https://docs.databricks.com/aws/en/machine-learning/model-serving/score-foundation-models#-foundation-model-types"
+        )
+
+    # Databricks doesn't support stream_options
+    def _chat_perform_args(
+        self, stream, turns, tools, data_model=None, kwargs=None
+    ) -> "SubmitInputArgs":
+        kwargs2 = super()._chat_perform_args(stream, turns, tools, data_model, kwargs)
+
+        if "stream_options" in kwargs2:
+            del kwargs2["stream_options"]
+
+        return kwargs2