chatlas 0.10.0__py3-none-any.whl → 0.11.0__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,
@@ -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,
         *,
@@ -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
@@ -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,

chatlas/_provider_ollama.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, Optional
 import orjson
 
 from ._chat import Chat
-from ._provider_openai import OpenAIProvider
+from ._provider_openai import ModelInfo, OpenAIProvider
 from ._utils import MISSING_TYPE, is_testing
 
 if TYPE_CHECKING:
@@ -90,18 +90,19 @@ def ChatOllama(
         raise RuntimeError("Can't find locally running ollama.")
 
     if model is None:
-        models = ollama_models(base_url)
+        models = ollama_model_info(base_url)
+        model_ids = [m["id"] for m in models]
         raise ValueError(
-            f"Must specify model. Locally installed models: {', '.join(models)}"
+            f"Must specify model. Locally installed models: {', '.join(model_ids)}"
         )
     if isinstance(seed, MISSING_TYPE):
         seed = 1014 if is_testing() else None
 
     return Chat(
-        provider=OpenAIProvider(
+        provider=OllamaProvider(
             api_key="ollama",  # ignored
             model=model,
-            base_url=f"{base_url}/v1",
+            base_url=base_url,
             seed=seed,
             name="Ollama",
             kwargs=kwargs,
@@ -110,10 +111,40 @@ def ChatOllama(
     )
 
 
-def ollama_models(base_url: str) -> list[str]:
-    res = urllib.request.urlopen(url=f"{base_url}/api/tags")
-    data = orjson.loads(res.read())
-    return [re.sub(":latest$", "", x["name"]) for x in data["models"]]
+class OllamaProvider(OpenAIProvider):
+    def __init__(self, *, api_key, model, base_url, seed, name, kwargs):
+        super().__init__(
+            api_key=api_key,
+            model=model,
+            base_url=f"{base_url}/v1",
+            seed=seed,
+            name=name,
+            kwargs=kwargs,
+        )
+        self.base_url = base_url
+
+    def list_models(self):
+        return ollama_model_info(self.base_url)
+
+
+def ollama_model_info(base_url: str) -> list[ModelInfo]:
+    response = urllib.request.urlopen(url=f"{base_url}/api/tags")
+    data = orjson.loads(response.read())
+    models = data.get("models", [])
+    if not models:
+        return []
+
+    res: list[ModelInfo] = []
+    for model in models:
+        # TODO: add capabilities
+        info: ModelInfo = {
+            "id": re.sub(":latest$", "", model["name"]),
+            "created_at": model["modified_at"],
+            "size": model["size"],
+        }
+        res.append(info)
+
+    return res
 
 
 def has_ollama(base_url):

chatlas/_provider_openai.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import base64
+from datetime import datetime
 from typing import TYPE_CHECKING, Any, Literal, Optional, cast, overload
 
 import orjson
@@ -23,8 +24,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, basemodel_to_param_schema
 from ._turn import Turn, user_turn
 from ._utils import MISSING, MISSING_TYPE, is_testing, split_http_client_kwargs
@@ -200,6 +201,32 @@ class OpenAIProvider(
         self._client = OpenAI(**sync_kwargs)  # type: ignore
         self._async_client = AsyncOpenAI(**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,
+                "owned_by": m.owned_by,
+                "input": pricing.get("input"),
+                "output": pricing.get("output"),
+                "cached_input": pricing.get("cached_input"),
+            }
+            # DeepSeek compatibility
+            if m.created is not None:
+                info["created_at"] = datetime.fromtimestamp(m.created).date()
+            res.append(info)
+
+        # More recent models first
+        res.sort(
+            key=lambda x: x.get("created_at", 0),
+            reverse=True,
+        )
+
+        return res
+
     @overload
     def chat_perform(
         self,