chatlas 0.10.0__py3-none-any.whl → 0.11.1__py3-none-any.whl

chatlas/__init__.py

@@ -1,7 +1,12 @@
 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
@@ -59,6 +64,7 @@ __all__ = (
     "ContentToolRequest",
     "ContentToolResult",
     "ContentToolResultImage",
+    "ContentToolResultResource",
     "interpolate",
     "interpolate_file",
     "Provider",
@@ -68,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,
@@ -33,6 +34,7 @@ from ._content import (
     ContentText,
     ContentToolRequest,
     ContentToolResult,
+    ToolInfo,
 )
 from ._display import (
     EchoDisplayOptions,
@@ -43,13 +45,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 ._content import ToolAnnotations
+
 
 class TokensDict(TypedDict):
     """
@@ -128,6 +133,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,
         *,
@@ -1461,7 +1538,9 @@ 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,
     ):
         """
         Register a tool (function) with the chat.
@@ -1533,19 +1612,24 @@ 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.
             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.
 
         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, 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. "
@@ -1853,6 +1937,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             all_results: list[ContentToolResult] = []
             for x in turn.contents:
                 if isinstance(x, ContentToolRequest):
+                    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":
@@ -1913,6 +2000,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             all_results: list[ContentToolResult] = []
             for x in turn.contents:
                 if isinstance(x, ContentToolRequest):
+                    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":
@@ -2070,8 +2160,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 = self._tools.get(request.name)
+        func = tool.func if tool is not None else None
 
         if func is None:
             yield self._handle_tool_error_result(
@@ -2118,21 +2208,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 = self._tools.get(request.name)
 
-        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,64 @@
 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
 
+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",
@@ -16,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",
@@ -171,11 +263,16 @@ class ContentToolRequest(Content):
         The name of the tool/function to call.
     arguments
         The arguments to pass to the tool/function.
+    tool
+        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[ToolInfo] = 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
@@ -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,
@@ -797,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

@@ -153,7 +153,7 @@ def ChatCloudflare(
     base_url = f"{cloudflare_api}/{account}/ai/v1/"
 
     return Chat(
-        provider=OpenAIProvider(
+        provider=CloudflareProvider(
             api_key=api_key,
             model=model,
             base_url=base_url,
@@ -163,3 +163,11 @@ def ChatCloudflare(
         ),
         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

@@ -128,6 +128,13 @@ class DatabricksProvider(OpenAIProvider):
             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

chatlas/_provider_github.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 import os
 from typing import TYPE_CHECKING, Optional
 
+import requests
+
 from ._chat import Chat
 from ._logging import log_model_default
-from ._provider_openai import OpenAIProvider
+from ._provider_openai import ModelInfo, OpenAIProvider
 from ._utils import MISSING, MISSING_TYPE, is_testing
 
 if TYPE_CHECKING:
@@ -18,7 +20,7 @@ def ChatGithub(
     system_prompt: Optional[str] = None,
     model: Optional[str] = None,
     api_key: Optional[str] = None,
-    base_url: str = "https://models.inference.ai.azure.com/",
+    base_url: str = "https://models.github.ai/inference/",
     seed: Optional[int] | MISSING_TYPE = MISSING,
     kwargs: Optional["ChatClientArgs"] = None,
 ) -> Chat["SubmitInputArgs", ChatCompletion]:
@@ -125,7 +127,7 @@ def ChatGithub(
         seed = 1014 if is_testing() else None
 
     return Chat(
-        provider=OpenAIProvider(
+        provider=GitHubProvider(
             api_key=api_key,
             model=model,
             base_url=base_url,
@@ -135,3 +137,61 @@ def ChatGithub(
         ),
         system_prompt=system_prompt,
     )
+
+
+class GitHubProvider(OpenAIProvider):
+    def __init__(self, base_url: str, **kwargs):
+        super().__init__(**kwargs)
+        self._base_url = base_url
+
+    def list_models(self) -> list[ModelInfo]:
+        # For some reason the OpenAI SDK API fails here? So perform request manually
+        # models = self._client.models.list()
+
+        base_url = self._base_url
+        if not base_url.endswith("/"):
+            base_url += "/"
+
+        if "azure" in base_url:
+            # i.e., https://models.inference.ai.azure.com
+            return list_models_gh_azure(base_url)
+        else:
+            # i.e., https://models.github.ai/inference/
+            return list_models_gh(base_url)
+
+
+def list_models_gh(base_url: str = "https://models.github.ai/inference/"):
+    # replace /inference endpoint with /catalog
+    base_url = base_url.replace("/inference", "/catalog")
+    response = requests.get(f"{base_url}models")
+    response.raise_for_status()
+    models = response.json()
+
+    res: list[ModelInfo] = []
+    for m in models:
+        _id = m["id"].split("/")[-1]
+        info: ModelInfo = {
+            "id": _id,
+            "name": m["name"],
+            "provider": m["publisher"],
+            "url": m["html_url"],
+        }
+        res.append(info)
+
+    return res
+
+
+def list_models_gh_azure(base_url: str = "https://models.inference.ai.azure.com"):
+    response = requests.get(f"{base_url}models")
+    response.raise_for_status()
+    models = response.json()
+
+    res: list[ModelInfo] = []
+    for m in models:
+        info: ModelInfo = {
+            "id": m["name"],
+            "provider": m["publisher"]
+        }
+        res.append(info)
+
+    return res

chatlas/_provider_google.py

@@ -21,8 +21,8 @@ from ._content import (
 )
 from ._logging import log_model_default
 from ._merge import merge_dicts
-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
 from ._turn import Turn, user_turn
 
@@ -180,6 +180,30 @@ class GoogleProvider(
 
         self._client = genai.Client(**kwargs_full)
 
+    def list_models(self):
+        models = self._client.models.list()
+
+        res: list[ModelInfo] = []
+        for m in models:
+            name = m.name or "[unknown]"
+            pricing = get_token_pricing(self.name, name) or {}
+            info: ModelInfo = {
+                "id": name,
+                "name": m.display_name or "[unknown]",
+                "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", 0),
+            reverse=True,
+        )
+
+        return res
+
     @overload
     def chat_perform(
         self,