chatlas 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

chatlas/__init__.py

@@ -1,21 +1,29 @@
 from . import types
 from ._anthropic import ChatAnthropic, ChatBedrockAnthropic
+from ._auto import ChatAuto
 from ._chat import Chat
 from ._content_image import content_image_file, content_image_plot, content_image_url
 from ._github import ChatGithub
-from ._google import ChatGoogle
+from ._google import ChatGoogle, ChatVertex
 from ._groq import ChatGroq
 from ._interpolate import interpolate, interpolate_file
 from ._ollama import ChatOllama
 from ._openai import ChatAzureOpenAI, ChatOpenAI
 from ._perplexity import ChatPerplexity
 from ._provider import Provider
+from ._snowflake import ChatSnowflake
 from ._tokens import token_usage
 from ._tools import Tool
 from ._turn import Turn
 
+try:
+    from ._version import version as __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0.0.0"  # stub value for docs
+
 __all__ = (
     "ChatAnthropic",
+    "ChatAuto",
     "ChatBedrockAnthropic",
     "ChatGithub",
     "ChatGoogle",
@@ -24,6 +32,8 @@ __all__ = (
     "ChatOpenAI",
     "ChatAzureOpenAI",
     "ChatPerplexity",
+    "ChatSnowflake",
+    "ChatVertex",
     "Chat",
     "content_image_file",
     "content_image_plot",

chatlas/_anthropic.py

@@ -72,7 +72,7 @@ def ChatAnthropic(
     ::: {.callout-note}
     ## API key
 
-    Note that a Claude Prop membership does not give you the ability to call
+    Note that a Claude Pro membership does not give you the ability to call
     models via the API. You will need to go to the [developer
     console](https://console.anthropic.com/account/keys) to sign up (and pay
     for) a developer account that will give you an API key that you can use with
@@ -82,7 +82,7 @@ def ChatAnthropic(
     ::: {.callout-note}
     ## Python requirements
 
-    `ChatAnthropic` requires the `anthropic` package (e.g., `pip install anthropic`).
+    `ChatAnthropic` requires the `anthropic` package: `pip install "chatlas[anthropic]"`.
     :::
 
     Examples
@@ -164,7 +164,7 @@ def ChatAnthropic(
     """
 
     if model is None:
-        model = log_model_default("claude-3-5-sonnet-latest")
+        model = log_model_default("claude-3-7-sonnet-latest")
 
     return Chat(
         provider=AnthropicProvider(
@@ -311,7 +311,8 @@ class AnthropicProvider(Provider[Message, RawMessageStreamEvent, Message]):
             if stream:
                 stream = False
                 warnings.warn(
-                    "Anthropic does not support structured data extraction in streaming mode."
+                    "Anthropic does not support structured data extraction in streaming mode.",
+                    stacklevel=2,
                 )
 
         kwargs_full: "SubmitInputArgs" = {
@@ -371,10 +372,7 @@ class AnthropicProvider(Provider[Message, RawMessageStreamEvent, Message]):
 
         return completion
 
-    def stream_turn(self, completion, has_data_model, stream) -> Turn:
-        return self._as_turn(completion, has_data_model)
-
-    async def stream_turn_async(self, completion, has_data_model, stream) -> Turn:
+    def stream_turn(self, completion, has_data_model) -> Turn:
         return self._as_turn(completion, has_data_model)
 
     def value_turn(self, completion, has_data_model) -> Turn:
@@ -574,8 +572,8 @@ def ChatBedrockAnthropic(
     ::: {.callout-note}
     ## Python requirements
 
-    `ChatBedrockAnthropic`, requires the `anthropic` package with the `bedrock` extras
-    (e.g., `pip install anthropic[bedrock]`).
+    `ChatBedrockAnthropic`, requires the `anthropic` package with the `bedrock` extras:
+    `pip install "chatlas[bedrock-anthropic]"`
     :::
 
     Examples

chatlas/_auto.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Callable, Literal, Optional
+
+from ._anthropic import ChatAnthropic, ChatBedrockAnthropic
+from ._chat import Chat
+from ._github import ChatGithub
+from ._google import ChatGoogle, ChatVertex
+from ._groq import ChatGroq
+from ._ollama import ChatOllama
+from ._openai import ChatAzureOpenAI, ChatOpenAI
+from ._perplexity import ChatPerplexity
+from ._snowflake import ChatSnowflake
+from ._turn import Turn
+
+AutoProviders = Literal[
+    "anthropic",
+    "bedrock-anthropic",
+    "github",
+    "google",
+    "groq",
+    "ollama",
+    "openai",
+    "azure-openai",
+    "perplexity",
+    "snowflake",
+    "vertex",
+]
+
+_provider_chat_model_map: dict[AutoProviders, Callable[..., Chat]] = {
+    "anthropic": ChatAnthropic,
+    "bedrock-anthropic": ChatBedrockAnthropic,
+    "github": ChatGithub,
+    "google": ChatGoogle,
+    "groq": ChatGroq,
+    "ollama": ChatOllama,
+    "openai": ChatOpenAI,
+    "azure-openai": ChatAzureOpenAI,
+    "perplexity": ChatPerplexity,
+    "snowflake": ChatSnowflake,
+    "vertex": ChatVertex,
+}
+
+
+def ChatAuto(
+    system_prompt: Optional[str] = None,
+    turns: Optional[list[Turn]] = None,
+    *,
+    provider: Optional[AutoProviders] = None,
+    model: Optional[str] = None,
+    **kwargs,
+) -> Chat:
+    """
+    Use environment variables (env vars) to configure the Chat provider and model.
+
+    Creates a `:class:~chatlas.Chat` instance based on the specified provider.
+    The provider may be specified through the `provider` parameter and/or the
+    `CHATLAS_CHAT_PROVIDER` env var. If both are set, the env var takes
+    precedence. Similarly, the provider's model may be specified through the
+    `model` parameter and/or the `CHATLAS_CHAT_MODEL` env var. Also, additional
+    configuration may be provided through the `kwargs` parameter and/or the
+    `CHATLAS_CHAT_ARGS` env var (as a JSON string). In this case, when both are
+    set, they are merged, with the env var arguments taking precedence.
+
+    As a result, `ChatAuto()` provides a convenient way to set a default
+    provider and model in your Python code, while allowing you to override
+    these settings through env vars (i.e., without modifying your code).
+
+    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
+    --------
+    First, set the environment variables for the provider, arguments, and API key:
+
+    ```bash
+    export CHATLAS_CHAT_PROVIDER=anthropic
+    export CHATLAS_CHAT_MODEL=claude-3-haiku-20240229
+    export CHATLAS_CHAT_ARGS='{"kwargs": {"max_retries": 3}}'
+    export ANTHROPIC_API_KEY=your_api_key
+    ```
+
+    Then, you can use the `ChatAuto` function to create a Chat instance:
+
+    ```python
+    from chatlas import ChatAuto
+
+    chat = ChatAuto()
+    chat.chat("What is the capital of France?")
+    ```
+
+    Parameters
+    ----------
+    provider
+        The name of the default chat provider to use. Providers are strings
+        formatted in kebab-case, e.g. to use `ChatBedrockAnthropic` set
+        `provider="bedrock-anthropic"`.
+
+        This value can also be provided via the `CHATLAS_CHAT_PROVIDER`
+        environment variable, which takes precedence over `provider`
+        when set.
+    model
+        The name of the default model to use. This value can also be provided
+        via the `CHATLAS_CHAT_MODEL` environment variable, which takes
+        precedence over `model` when set.
+    system_prompt
+        A system prompt to set the behavior of the assistant.
+    turns
+        A list of turns to start the chat with (i.e., continuing a previous
+        conversation). If not provided, the conversation begins from scratch. Do
+        not provide non-`None` values for both `turns` and `system_prompt`. Each
+        message in the list should be a dictionary with at least `role` (usually
+        `system`, `user`, or `assistant`, but `tool` is also possible). Normally
+        there is also a `content` field, which is a string.
+    **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 provided, the options
+        in the `CHATLAS_CHAT_ARGS` envvar take precedence over the options
+        passed to `kwargs`.
+
+        Note that `system_prompt` and `turns` in `kwargs` or in
+        `CHATLAS_CHAT_ARGS` are ignored.
+
+    Returns
+    -------
+    Chat
+        A chat instance using the specified provider.
+
+    Raises
+    ------
+    ValueError
+        If no valid provider is specified either through parameters or
+        environment variables.
+    """
+    the_provider = os.environ.get("CHATLAS_CHAT_PROVIDER", provider)
+
+    if the_provider is None:
+        raise ValueError(
+            "Provider name is required as parameter or `CHATLAS_CHAT_PROVIDER` must be set."
+        )
+    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` and `turns` always come from `ChatAuto()`
+    base_args = {"system_prompt": system_prompt, "turns": turns}
+
+    if env_model := os.environ.get("CHATLAS_CHAT_MODEL"):
+        model = env_model
+
+    if model:
+        base_args["model"] = model
+
+    env_kwargs = {}
+    if env_kwargs_str := os.environ.get("CHATLAS_CHAT_ARGS"):
+        env_kwargs = json.loads(env_kwargs_str)
+
+    kwargs = {**kwargs, **env_kwargs, **base_args}
+    kwargs = {k: v for k, v in kwargs.items() if v is not None}
+
+    return _provider_chat_model_map[the_provider](**kwargs)

chatlas/_chat.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import inspect
 import os
+import sys
 from pathlib import Path
 from threading import Thread
 from typing import (
@@ -40,7 +42,7 @@ from ._provider import Provider
 from ._tools import Tool
 from ._turn import Turn, user_turn
 from ._typing_extensions import TypedDict
-from ._utils import html_escape
+from ._utils import html_escape, wrap_async
 
 
 class AnyTypeDict(TypedDict, total=False):
@@ -388,6 +390,7 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         port: int = 0,
         launch_browser: bool = True,
         bg_thread: Optional[bool] = None,
+        echo: Optional[Literal["text", "all", "none"]] = None,
         kwargs: Optional[SubmitInputArgsT] = None,
     ):
         """
@@ -404,6 +407,10 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         bg_thread
             Whether to run the app in a background thread. If `None`, the app will
             run in a background thread if the current environment is a notebook.
+        echo
+            Whether to echo text content, all content (i.e., tool calls), or no
+            content. Defaults to `"none"` when `stream=True` and `"text"` when
+            `stream=False`.
         kwargs
             Additional keyword arguments to pass to the method used for requesting
             the response.
@@ -438,10 +445,22 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
                     return
                 if stream:
                     await chat.append_message_stream(
-                        self.stream(user_input, kwargs=kwargs)
+                        await self.stream_async(
+                            user_input,
+                            kwargs=kwargs,
+                            echo=echo or "none",
+                        )
                     )
                 else:
-                    await chat.append_message(str(self.chat(user_input, kwargs=kwargs)))
+                    await chat.append_message(
+                        str(
+                            self.chat(
+                                user_input,
+                                kwargs=kwargs,
+                                echo=echo or "text",
+                            )
+                        )
+                    )
 
         app = App(app_ui, server)
 
@@ -948,11 +967,11 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         is_html = filename.suffix == ".html"
 
         # Get contents from each turn
-        contents = ""
+        content_arr: list[str] = []
         for turn in turns:
             turn_content = "\n\n".join(
                 [
-                    str(content)
+                    str(content).strip()
                     for content in turn.contents
                     if include == "all" or isinstance(content, ContentText)
                 ]
@@ -963,7 +982,8 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
                 turn_content = f"<shiny-{msg_type}-message content='{content_attr}'></shiny-{msg_type}-message>"
             else:
                 turn_content = f"## {turn.role.capitalize()}\n\n{turn_content}"
-            contents += f"{turn_content}\n\n"
+            content_arr.append(turn_content)
+        contents = "\n\n".join(content_arr)
 
         # Shiny chat message components requires container elements
         if is_html:
@@ -1093,7 +1113,6 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             turn = self.provider.stream_turn(
                 result,
                 has_data_model=data_model is not None,
-                stream=response,
             )
 
             if echo == "all":
@@ -1154,10 +1173,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
                     yield text
                 result = self.provider.stream_merge_chunks(result, chunk)
 
-            turn = await self.provider.stream_turn_async(
+            turn = self.provider.stream_turn(
                 result,
                 has_data_model=data_model is not None,
-                stream=response,
             )
 
             if echo == "all":
@@ -1210,7 +1228,12 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         for x in turn.contents:
             if isinstance(x, ContentToolRequest):
                 tool_def = self._tools.get(x.name, None)
-                func = tool_def.func if tool_def is not None else None
+                func = None
+                if tool_def:
+                    if tool_def._is_async:
+                        func = tool_def.func
+                    else:
+                        func = wrap_async(tool_def.func)
                 results.append(await self._invoke_tool_async(func, x.arguments, x.id))
 
         if not results:
@@ -1225,7 +1248,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         id_: str,
     ) -> ContentToolResult:
         if func is None:
-            return ContentToolResult(id_, None, "Unknown tool")
+            return ContentToolResult(id_, value=None, error="Unknown tool")
+
+        name = func.__name__
 
         try:
             if isinstance(arguments, dict):
@@ -1233,10 +1258,10 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             else:
                 result = func(arguments)
 
-            return ContentToolResult(id_, result, None)
+            return ContentToolResult(id_, value=result, error=None, name=name)
         except Exception as e:
-            log_tool_error(func.__name__, str(arguments), e)
-            return ContentToolResult(id_, None, str(e))
+            log_tool_error(name, str(arguments), e)
+            return ContentToolResult(id_, value=None, error=str(e), name=name)
 
     @staticmethod
     async def _invoke_tool_async(
@@ -1245,7 +1270,9 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
         id_: str,
     ) -> ContentToolResult:
         if func is None:
-            return ContentToolResult(id_, None, "Unknown tool")
+            return ContentToolResult(id_, value=None, error="Unknown tool")
+
+        name = func.__name__
 
         try:
             if isinstance(arguments, dict):
@@ -1253,10 +1280,10 @@ class Chat(Generic[SubmitInputArgsT, CompletionT]):
             else:
                 result = await func(arguments)
 
-            return ContentToolResult(id_, result, None)
+            return ContentToolResult(id_, value=result, error=None, name=name)
         except Exception as e:
             log_tool_error(func.__name__, str(arguments), e)
-            return ContentToolResult(id_, None, str(e))
+            return ContentToolResult(id_, value=None, error=str(e), name=name)
 
     def _markdown_display(
         self, echo: Literal["text", "all", "none"]
@@ -1373,7 +1400,7 @@ class ChatResponse:
 
     @property
     def consumed(self) -> bool:
-        return self._generator.gi_frame is None
+        return inspect.getgeneratorstate(self._generator) == inspect.GEN_CLOSED
 
     def __str__(self) -> str:
         return self.get_content()
@@ -1423,7 +1450,11 @@ class ChatResponseAsync:
 
     @property
     def consumed(self) -> bool:
-        return self._generator.ag_frame is None
+        if sys.version_info < (3, 12):
+            raise NotImplementedError(
+                "Checking for consumed state is only supported in Python 3.12+"
+            )
+        return inspect.getasyncgenstate(self._generator) == inspect.AGEN_CLOSED
 
 
 # ----------------------------------------------------------------------------

chatlas/_content.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass
+from pprint import pformat
 from typing import Any, Literal, Optional
 
 ImageContentTypes = Literal[
@@ -154,7 +155,7 @@ class ContentToolRequest(Content):
         args_str = self._arguments_str()
         func_call = f"{self.name}({args_str})"
         comment = f"# tool request ({self.id})"
-        return f"\n```python\n{comment}\n{func_call}\n```\n"
+        return f"```python\n{comment}\n{func_call}\n```\n"
 
     def _repr_markdown_(self):
         return self.__str__()
@@ -187,19 +188,35 @@ class ContentToolResult(Content):
         The unique identifier of the tool request.
     value
         The value returned by the tool/function.
+    name
+        The name of the tool/function that was called.
     error
         An error message if the tool/function call failed.
     """
 
     id: str
     value: Any = None
+    name: Optional[str] = None
     error: Optional[str] = None
 
+    def _get_value(self, pretty: bool = False) -> str:
+        if self.error:
+            return f"Tool calling failed with error: '{self.error}'"
+        if not pretty:
+            return str(self.value)
+        try:
+            json_val = json.loads(self.value)  # type: ignore
+            return pformat(json_val, indent=2, sort_dicts=False)
+        except:  # noqa: E722
+            return str(self.value)
+
+    # Primarily used for `echo="all"`...
     def __str__(self):
         comment = f"# tool result ({self.id})"
-        val = self.get_final_value()
-        return f"""\n```python\n{comment}\n"{val}"\n```\n"""
+        value = self._get_value(pretty=True)
+        return f"""```python\n{comment}\n{value}\n```"""
 
+    # ... and for displaying in the notebook
     def _repr_markdown_(self):
         return self.__str__()
 
@@ -210,10 +227,9 @@ class ContentToolResult(Content):
             res += f" error='{self.error}'"
         return res + ">"
 
+    # The actual value to send to the model
     def get_final_value(self) -> str:
-        if self.error:
-            return f"Tool calling failed with error: '{self.error}'"
-        return str(self.value)
+        return self._get_value()
 
 
 @dataclass
@@ -236,7 +252,7 @@ class ContentJson(Content):
         return json.dumps(self.value, indent=2)
 
     def _repr_markdown_(self):
-        return f"""\n```json\n{self.__str__()}\n```\n"""
+        return f"""```json\n{self.__str__()}\n```"""
 
     def __repr__(self, indent: int = 0):
         return " " * indent + f"<ContentJson value={self.value}>"

chatlas/_display.py

@@ -6,6 +6,7 @@ from uuid import uuid4
 from rich.live import Live
 from rich.logging import RichHandler
 
+from ._live_render import LiveRender
 from ._logging import logger
 from ._typing_extensions import TypedDict
 
@@ -44,13 +45,22 @@ class LiveMarkdownDisplay(MarkdownDisplay):
         from rich.console import Console
 
         self.content: str = ""
-        self.live = Live(
+        live = Live(
             auto_refresh=False,
-            vertical_overflow="visible",
             console=Console(
                 **echo_options["rich_console"],
             ),
         )
+
+        # Monkeypatch LiveRender() with our own version that add "crop_above"
+        # https://github.com/Textualize/rich/blob/43d3b047/rich/live.py#L87-L89
+        live.vertical_overflow = "crop_above"
+        live._live_render = LiveRender(  # pyright: ignore[reportAttributeAccessIssue]
+            live.get_renderable(), vertical_overflow="crop_above"
+        )
+
+        self.live = live
+
         self._markdown_options = echo_options["rich_markdown"]
 
     def update(self, content: str):

chatlas/_github.py

@@ -43,7 +43,7 @@ def ChatGithub(
     ::: {.callout-note}
     ## Python requirements
 
-    `ChatGithub` requires the `openai` package (e.g., `pip install openai`).
+    `ChatGithub` requires the `openai` package: `pip install "chatlas[github]"`.
     :::