Merge branch 'main' into surface-tool-calls

Author: cpsievert

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### New features
 
 * Added a `ChatSnowflake()` class to interact with [Snowflake Cortex LLM](https://docs.snowflake.com/en/user-guide/snowflake-cortex/llm-functions). (#54)
+* Added a `ChatAuto()` class, allowing for configuration of chat providers and models via environment variables. (#38, thanks @mconflitti-pbc)
 
 ### Improvements
 
@@ -21,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Bug fixes
 
+* Fixed an issue with content getting duplicated when it overflows in a `Live()` console. (#71)
 * Fix an issue with tool calls not working with `ChatVertex()`. (#61)
 
 

chatlas/__init__.py

@@ -1,5 +1,6 @@
 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
@@ -22,6 +23,7 @@
 
 __all__ = (
     "ChatAnthropic",
+    "ChatAuto",
     "ChatBedrockAnthropic",
     "ChatGithub",
     "ChatGoogle",

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/_display.py

@@ -6,6 +6,7 @@
 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 @@ def __init__(self, echo_options: "EchoOptions"):
         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/_live_render.py

@@ -0,0 +1,116 @@
+# A 'patched' version of LiveRender that adds the 'crop_above' vertical overflow method.
+# Derives from https://github.com/Textualize/rich/pull/3637
+import sys
+from typing import Optional, Tuple
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal  # pragma: no cover
+
+from rich._loop import loop_last
+from rich.console import Console, ConsoleOptions, RenderableType, RenderResult
+from rich.control import Control
+from rich.segment import ControlType, Segment
+from rich.style import StyleType
+from rich.text import Text
+
+VerticalOverflowMethod = Literal["crop", "crop_above", "ellipsis", "visible"]
+
+
+class LiveRender:
+    """Creates a renderable that may be updated.
+
+    Args:
+        renderable (RenderableType): Any renderable object.
+        style (StyleType, optional): An optional style to apply to the renderable. Defaults to "".
+    """
+
+    def __init__(
+        self,
+        renderable: RenderableType,
+        style: StyleType = "",
+        vertical_overflow: VerticalOverflowMethod = "ellipsis",
+    ) -> None:
+        self.renderable = renderable
+        self.style = style
+        self.vertical_overflow = vertical_overflow
+        self._shape: Optional[Tuple[int, int]] = None
+
+    def set_renderable(self, renderable: RenderableType) -> None:
+        """Set a new renderable.
+
+        Args:
+            renderable (RenderableType): Any renderable object, including str.
+        """
+        self.renderable = renderable
+
+    def position_cursor(self) -> Control:
+        """Get control codes to move cursor to beginning of live render.
+
+        Returns:
+            Control: A control instance that may be printed.
+        """
+        if self._shape is not None:
+            _, height = self._shape
+            return Control(
+                ControlType.CARRIAGE_RETURN,
+                (ControlType.ERASE_IN_LINE, 2),
+                *(
+                    (
+                        (ControlType.CURSOR_UP, 1),
+                        (ControlType.ERASE_IN_LINE, 2),
+                    )
+                    * (height - 1)
+                ),
+            )
+        return Control()
+
+    def restore_cursor(self) -> Control:
+        """Get control codes to clear the render and restore the cursor to its previous position.
+
+        Returns:
+            Control: A Control instance that may be printed.
+        """
+        if self._shape is not None:
+            _, height = self._shape
+            return Control(
+                ControlType.CARRIAGE_RETURN,
+                *((ControlType.CURSOR_UP, 1), (ControlType.ERASE_IN_LINE, 2)) * height,
+            )
+        return Control()
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        renderable = self.renderable
+        style = console.get_style(self.style)
+        lines = console.render_lines(renderable, options, style=style, pad=False)
+        shape = Segment.get_shape(lines)
+
+        _, height = shape
+        if height > options.size.height:
+            if self.vertical_overflow == "crop":
+                lines = lines[: options.size.height]
+                shape = Segment.get_shape(lines)
+            elif self.vertical_overflow == "crop_above":
+                lines = lines[-(options.size.height) :]
+                shape = Segment.get_shape(lines)
+            elif self.vertical_overflow == "ellipsis":
+                lines = lines[: (options.size.height - 1)]
+                overflow_text = Text(
+                    "...",
+                    overflow="crop",
+                    justify="center",
+                    end="",
+                    style="live.ellipsis",
+                )
+                lines.append(list(console.render(overflow_text)))
+                shape = Segment.get_shape(lines)
+        self._shape = shape
+
+        new_line = Segment.line()
+        for last, line in loop_last(lines):
+            yield from line
+            if not last:
+                yield new_line

docs/_quarto.yml

@@ -77,6 +77,7 @@ quartodoc:
       desc: Start a chat with a particular large language model (llm) provider.
       contents:
         - ChatAnthropic
+        - ChatAuto
         - ChatAzureOpenAI
         - ChatBedrockAnthropic
         - ChatGithub