chatlas 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

chatlas/_content.py

@@ -1,15 +1,11 @@
 from __future__ import annotations
 
-import textwrap
 from pprint import pformat
-from typing import TYPE_CHECKING, Any, Literal, Optional, Union
+from typing import Any, Literal, Optional, Union
 
 import orjson
 from pydantic import BaseModel, ConfigDict
 
-if TYPE_CHECKING:
-    from htmltools import TagChild
-
 ImageContentTypes = Literal[
     "image/png",
     "image/jpeg",
@@ -26,6 +22,8 @@ ContentTypeEnum = Literal[
     "image_inline",
     "tool_request",
     "tool_result",
+    "tool_result_image",
+    "tool_result_resource",
     "json",
     "pdf",
 ]
@@ -202,7 +200,10 @@ class ContentToolRequest(Content):
             return ", ".join(f"{k}={v}" for k, v in self.arguments.items())
         return str(self.arguments)
 
-    def tagify(self) -> "TagChild":
+    def __repr_html__(self) -> str:
+        return str(self.tagify())
+
+    def tagify(self):
         "Returns an HTML string suitable for passing to htmltools/shiny's `Chat()` component."
         try:
             from htmltools import HTML, TagList, head_content, tags
@@ -314,7 +315,7 @@ class ContentToolResult(Content):
         return res + ">"
 
     # Format the value for display purposes
-    def _get_display_value(self) -> object:
+    def _get_display_value(self):
         if self.error:
             return f"Tool call failed with error: '{self.error}'"
 
@@ -333,7 +334,7 @@ class ContentToolResult(Content):
                 # Not valid JSON, return as string
                 return val
 
-        return val
+        return str(val)
 
     def get_model_value(self) -> object:
         "Get the actual value sent to the model."
@@ -370,37 +371,62 @@ class ContentToolResult(Content):
 
         return orjson.dumps(value).decode("utf-8")
 
-    def tagify(self) -> "TagChild":
-        """
-        A method for rendering this object via htmltools/shiny.
-        """
+    def __repr_html__(self):
+        return str(self.tagify())
+
+    def tagify(self):
+        "A method for rendering this object via htmltools/shiny."
         try:
-            from htmltools import HTML
+            from htmltools import HTML, html_escape
         except ImportError:
             raise ImportError(
                 ".tagify() is only intended to be called by htmltools/shiny, ",
                 "but htmltools is not installed. ",
             )
 
+        # Helper function to format code blocks (optionally with labels for arguments).
+        def pre_code(code: str, label: str | None = None) -> str:
+            lbl = f"<span class='input-parameter-label'>{label}</span>" if label else ""
+            return f"<pre>{lbl}<code>{html_escape(code)}</code></pre>"
+
+        # Helper function to wrap content in a <details> block.
+        def details_block(summary: str, content: str, open_: bool = True) -> str:
+            open_attr = " open" if open_ else ""
+            return (
+                f"<details{open_attr}><summary>{summary}</summary>{content}</details>"
+            )
+
+        # First, format the input parameters.
+        args = self.arguments or {}
+        if isinstance(args, dict):
+            args = "".join(pre_code(str(v), label=k) for k, v in args.items())
+        else:
+            args = pre_code(str(args))
+
+        # Wrap the input parameters in an (open) details block.
+        if args:
+            params = details_block("<strong>Input parameters:</strong>", args)
+        else:
+            params = ""
+
+        # Also wrap the tool result in an (open) details block.
+        result = details_block(
+            "<strong>Result:</strong>",
+            pre_code(self._get_display_value()),
+        )
+
+        # Put both the result and parameters into a container
+        result_div = f'<div class="chatlas-tool-result-content">{result}{params}</div>'
+
+        # Header for the top-level result details block.
         if not self.error:
-            header = f"View result from <code>{self.name}</code>"
+            header = f"Result from tool call: <code>{self.name}</code>"
         else:
             header = f"❌ Failed to call tool <code>{self.name}</code>"
 
-        args = self._arguments_str()
-        content = self._get_display_value()
-
-        return HTML(
-            textwrap.dedent(f"""
-              <details class="chatlas-tool-result">
-                  <summary>{header}</summary>
-                  <div class="chatlas-tool-result-content">
-                      Result: <p><code>{content}</code></p>
-                      Arguments: <p><code>{args}</code></p>
-                  </div>
-              </details>
-            """)
-        )
+        res = details_block(header, result_div, open_=False)
+
+        return HTML(f'<div class="chatlas-tool-result">{res}</div>')
 
     def _arguments_str(self) -> str:
         if isinstance(self.arguments, dict):
@@ -408,6 +434,68 @@ class ContentToolResult(Content):
         return str(self.arguments)
 
 
+class ContentToolResultImage(ContentToolResult):
+    """
+    A tool result that contains an image.
+
+    This is a specialized version of ContentToolResult for returning images.
+    It requires the image data to be base64-encoded (as `value`) and
+    the MIME type of the image (as `mime_type`).
+
+    Parameters
+    ----------
+    value
+        The image data as a base64-encoded string.
+    mime_type
+        The MIME type of the image (e.g., "image/png").
+    """
+
+    value: str
+    model_format: Literal["auto", "json", "str", "as_is"] = "as_is"
+    mime_type: ImageContentTypes
+
+    content_type: ContentTypeEnum = "tool_result_image"
+
+    def __str__(self):
+        return f"<ContentToolResultImage mime_type='{self.mime_type}'>"
+
+    def _repr_markdown_(self):
+        return f"![](data:{self.mime_type};base64,{self.value})"
+
+
+class ContentToolResultResource(ContentToolResult):
+    """
+    A tool result that contains a resource.
+
+    This is a specialized version of ContentToolResult for returning resources
+    (e.g., images, files) as raw bytes. It requires the resource data to be
+    provided as bytes (as `value`) and the MIME type of the resource (as
+    `mime_type`).
+
+    Parameters
+    ----------
+    value
+        The resource data, in bytes.
+    mime_type
+        The MIME type of the image (e.g., "image/png").
+    """
+
+    value: bytes
+    model_format: Literal["auto", "json", "str", "as_is"] = "as_is"
+    mime_type: Optional[str]
+
+    content_type: ContentTypeEnum = "tool_result_resource"
+
+    def __str__(self):
+        return f"<ContentToolResultResource mime_type='{self.mime_type}'>"
+
+    def _repr_mimebundle_(self, include=None, exclude=None):
+        return {
+            self.mime_type: self.value,
+            "text/plain": f"<{self.mime_type} object>",
+        }
+
+
 class ContentJson(Content):
     """
     JSON content
@@ -468,6 +556,8 @@ ContentUnion = Union[
     ContentImageInline,
     ContentToolRequest,
     ContentToolResult,
+    ContentToolResultImage,
+    ContentToolResultResource,
     ContentJson,
     ContentPDF,
 ]
@@ -494,6 +584,10 @@ def create_content(data: dict[str, Any]) -> ContentUnion:
         return ContentToolRequest.model_validate(data)
     elif ct == "tool_result":
         return ContentToolResult.model_validate(data)
+    elif ct == "tool_result_image":
+        return ContentToolResultImage.model_validate(data)
+    elif ct == "tool_result_resource":
+        return ContentToolResultResource.model_validate(data)
     elif ct == "json":
         return ContentJson.model_validate(data)
     elif ct == "pdf":
@@ -536,11 +630,12 @@ TOOL_CSS = """
   vertical-align: middle;
 }
 
-.chatlas-tool-result[open] summary::after {
+.chatlas-tool-result details[open] summary::after {
   content: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='currentColor' class='bi bi-caret-down-fill' viewBox='0 0 16 16'%3E%3Cpath d='M7.247 11.14 2.451 5.658C1.885 5.013 2.345 4 3.204 4h9.592a1 1 0 0 1 .753 1.659l-4.796 5.48a1 1 0 0 1-1.506 0z'/%3E%3C/svg%3E");
 }
 
 .chatlas-tool-result-content {
+  position: relative;
   border: 1px solid var(--bs-border-color, #0066cc);
   width: 100%;
   padding: 1rem;
@@ -548,4 +643,29 @@ TOOL_CSS = """
   margin-top: 1rem;
   margin-bottom: 1rem;
 }
+
+.chatlas-tool-result-content pre, .chatlas-tool-result-content code {
+  background-color: var(--bs-body-bg, white) !important;
+}
+
+.chatlas-tool-result-content .input-parameter-label {
+  position: absolute;
+  top: 0;
+  width: 100%;
+  text-align: center;
+  font-weight: 300;
+  font-size: 0.8rem;
+  color: var(--bs-gray-600);
+  background-color: var(--bs-body-bg);
+  padding: 0.5rem;
+  font-family: var(--bs-font-monospace, monospace);
+}
+
+pre:has(> .input-parameter-label) {
+  padding-top: 1.5rem;
+}
+
+shiny-markdown-stream p:first-of-type:empty {
+  display: none;
+}
 """

chatlas/_databricks.py

@@ -5,7 +5,6 @@ from typing import TYPE_CHECKING, Optional
 from ._chat import Chat
 from ._logging import log_model_default
 from ._openai import OpenAIProvider
-from ._turn import Turn, normalize_turns
 
 if TYPE_CHECKING:
     from databricks.sdk import WorkspaceClient
@@ -18,7 +17,6 @@ def ChatDatabricks(
     *,
     system_prompt: Optional[str] = None,
     model: Optional[str] = None,
-    turns: Optional[list[Turn]] = None,
     workspace_client: Optional["WorkspaceClient"] = None,
 ) -> Chat["SubmitInputArgs", ChatCompletion]:
     """
@@ -68,13 +66,6 @@ def ChatDatabricks(
         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.
-    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.
     workspace_client
         A `databricks.sdk.WorkspaceClient()` to use for the connection. If not
         provided, a new client will be created.
@@ -92,10 +83,7 @@ def ChatDatabricks(
             model=model,
             workspace_client=workspace_client,
         ),
-        turns=normalize_turns(
-            turns or [],
-            system_prompt,
-        ),
+        system_prompt=system_prompt,
     )
 
 
@@ -104,6 +92,7 @@ class DatabricksProvider(OpenAIProvider):
         self,
         *,
         model: str,
+        name: str = "Databricks",
         workspace_client: Optional["WorkspaceClient"] = None,
     ):
         try:
@@ -117,7 +106,8 @@ class DatabricksProvider(OpenAIProvider):
         import httpx
         from openai import AsyncOpenAI
 
-        self._model = model
+        super().__init__(name=name, model=model)
+
         self._seed = None
 
         if workspace_client is None:

chatlas/_github.py

@@ -5,9 +5,8 @@ from typing import TYPE_CHECKING, Optional
 
 from ._chat import Chat
 from ._logging import log_model_default
-from ._openai import ChatOpenAI
-from ._turn import Turn
-from ._utils import MISSING, MISSING_TYPE
+from ._openai import OpenAIProvider
+from ._utils import MISSING, MISSING_TYPE, is_testing
 
 if TYPE_CHECKING:
     from ._openai import ChatCompletion
@@ -17,7 +16,6 @@ if TYPE_CHECKING:
 def ChatGithub(
     *,
     system_prompt: Optional[str] = None,
-    turns: Optional[list[Turn]] = None,
     model: Optional[str] = None,
     api_key: Optional[str] = None,
     base_url: str = "https://models.inference.ai.azure.com/",
@@ -48,7 +46,7 @@ def ChatGithub(
     import os
     from chatlas import ChatGithub
 
-    chat = ChatGithub(api_key=os.getenv("GITHUB_PAT"))
+    chat = ChatGithub(api_key=os.getenv("GITHUB_TOKEN"))
     chat.chat("What is the capital of France?")
     ```
 
@@ -56,20 +54,13 @@ def ChatGithub(
     ----------
     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.
     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 `GITHUB_PAT` environment variable.
+        this directly, but instead set the `GITHUB_TOKEN` environment variable.
     base_url
         The base URL to the endpoint; the default uses Github's API.
     seed
@@ -106,7 +97,7 @@ def ChatGithub(
 
     ```shell
     # .env
-    GITHUB_PAT=...
+    GITHUB_TOKEN=...
     ```
 
     ```python
@@ -122,20 +113,25 @@ def ChatGithub(
     before starting Python (maybe in a `.bashrc`, `.zshrc`, etc. file):
 
     ```shell
-    export GITHUB_PAT=...
+    export GITHUB_TOKEN=...
     ```
     """
     if model is None:
-        model = log_model_default("gpt-4o")
+        model = log_model_default("gpt-4.1")
     if api_key is None:
-        api_key = os.getenv("GITHUB_PAT")
-
-    return ChatOpenAI(
+        api_key = os.getenv("GITHUB_TOKEN", os.getenv("GITHUB_PAT"))
+
+    if isinstance(seed, MISSING_TYPE):
+        seed = 1014 if is_testing() else None
+
+    return Chat(
+        provider=OpenAIProvider(
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            seed=seed,
+            name="GitHub",
+            kwargs=kwargs,
+        ),
         system_prompt=system_prompt,
-        turns=turns,
-        model=model,
-        api_key=api_key,
-        base_url=base_url,
-        seed=seed,
-        kwargs=kwargs,
     )

chatlas/_google.py

@@ -16,17 +16,20 @@ from ._content import (
     ContentText,
     ContentToolRequest,
     ContentToolResult,
+    ContentToolResultImage,
+    ContentToolResultResource,
 )
 from ._logging import log_model_default
 from ._merge import merge_dicts
-from ._provider import Provider
+from ._provider import Provider, StandardModelParamNames, StandardModelParams
 from ._tokens import tokens_log
 from ._tools import Tool
-from ._turn import Turn, normalize_turns, user_turn
+from ._turn import Turn, user_turn
 
 if TYPE_CHECKING:
     from google.genai.types import Content as GoogleContent
     from google.genai.types import (
+        GenerateContentConfigDict,
         GenerateContentResponse,
         GenerateContentResponseDict,
         Part,
@@ -41,7 +44,6 @@ else:
 def ChatGoogle(
     *,
     system_prompt: Optional[str] = None,
-    turns: Optional[list[Turn]] = None,
     model: Optional[str] = None,
     api_key: Optional[str] = None,
     kwargs: Optional["ChatClientArgs"] = None,
@@ -80,13 +82,6 @@ def ChatGoogle(
     ----------
     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.
     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
@@ -140,24 +135,25 @@ def ChatGoogle(
     """
 
     if model is None:
-        model = log_model_default("gemini-2.0-flash")
+        model = log_model_default("gemini-2.5-flash")
 
     return Chat(
         provider=GoogleProvider(
             model=model,
             api_key=api_key,
+            name="Google/Gemini",
             kwargs=kwargs,
         ),
-        turns=normalize_turns(
-            turns or [],
-            system_prompt=system_prompt,
-        ),
+        system_prompt=system_prompt,
     )
 
 
 class GoogleProvider(
     Provider[
-        GenerateContentResponse, GenerateContentResponse, "GenerateContentResponseDict"
+        GenerateContentResponse,
+        GenerateContentResponse,
+        "GenerateContentResponseDict",
+        "SubmitInputArgs",
     ]
 ):
     def __init__(
@@ -165,6 +161,7 @@ class GoogleProvider(
         *,
         model: str,
         api_key: str | None,
+        name: str = "Google/Gemini",
         kwargs: Optional["ChatClientArgs"],
     ):
         try:
@@ -174,8 +171,7 @@ class GoogleProvider(
                 f"The {self.__class__.__name__} class requires the `google-genai` package. "
                 "Install it with `pip install google-genai`."
             )
-
-        self._model = model
+        super().__init__(name=name, model=model)
 
         kwargs_full: "ChatClientArgs" = {
             "api_key": api_key,
@@ -267,7 +263,7 @@ class GoogleProvider(
         from google.genai.types import Tool as GoogleTool
 
         kwargs_full: "SubmitInputArgs" = {
-            "model": self._model,
+            "model": self.model,
             "contents": cast("GoogleContent", self._google_contents(turns)),
             **(kwargs or {}),
         }
@@ -430,6 +426,13 @@ class GoogleProvider(
                 )
             )
         elif isinstance(content, ContentToolResult):
+            if isinstance(
+                content, (ContentToolResultImage, ContentToolResultResource)
+            ):
+                raise NotImplementedError(
+                    "Tool results with images or resources aren't supported by Google (Gemini). "
+                )
+
             if content.error:
                 resp = {"error": content.error}
             else:
@@ -524,6 +527,52 @@ class GoogleProvider(
             completion=message,
         )
 
+    def translate_model_params(self, params: StandardModelParams) -> "SubmitInputArgs":
+        config: "GenerateContentConfigDict" = {}
+        if "temperature" in params:
+            config["temperature"] = params["temperature"]
+
+        if "top_p" in params:
+            config["top_p"] = params["top_p"]
+
+        if "top_k" in params:
+            config["top_k"] = params["top_k"]
+
+        if "frequency_penalty" in params:
+            config["frequency_penalty"] = params["frequency_penalty"]
+
+        if "presence_penalty" in params:
+            config["presence_penalty"] = params["presence_penalty"]
+
+        if "seed" in params:
+            config["seed"] = params["seed"]
+
+        if "max_tokens" in params:
+            config["max_output_tokens"] = params["max_tokens"]
+
+        if "log_probs" in params:
+            config["logprobs"] = params["log_probs"]
+
+        if "stop_sequences" in params:
+            config["stop_sequences"] = params["stop_sequences"]
+
+        res: "SubmitInputArgs" = {"config": config}
+
+        return res
+
+    def supported_model_params(self) -> set[StandardModelParamNames]:
+        return {
+            "temperature",
+            "top_p",
+            "top_k",
+            "frequency_penalty",
+            "presence_penalty",
+            "seed",
+            "max_tokens",
+            "log_probs",
+            "stop_sequences",
+        }
+
 
 def ChatVertex(
     *,
@@ -532,7 +581,6 @@ def ChatVertex(
     location: Optional[str] = None,
     api_key: Optional[str] = None,
     system_prompt: Optional[str] = None,
-    turns: Optional[list[Turn]] = None,
     kwargs: Optional["ChatClientArgs"] = None,
 ) -> Chat["SubmitInputArgs", GenerateContentResponse]:
     """
@@ -569,13 +617,6 @@ def ChatVertex(
         GOOGLE_CLOUD_LOCATION environment variable will be used.
     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.
 
     Returns
     -------
@@ -605,16 +646,14 @@ def ChatVertex(
     kwargs["location"] = location
 
     if model is None:
-        model = log_model_default("gemini-2.0-flash")
+        model = log_model_default("gemini-2.5-flash")
 
     return Chat(
         provider=GoogleProvider(
             model=model,
             api_key=api_key,
+            name="Google/Vertex",
             kwargs=kwargs,
         ),
-        turns=normalize_turns(
-            turns or [],
-            system_prompt=system_prompt,
-        ),
+        system_prompt=system_prompt,
     )

chatlas/_groq.py

@@ -5,9 +5,8 @@ from typing import TYPE_CHECKING, Optional
 
 from ._chat import Chat
 from ._logging import log_model_default
-from ._openai import ChatOpenAI
-from ._turn import Turn
-from ._utils import MISSING, MISSING_TYPE
+from ._openai import OpenAIProvider
+from ._utils import MISSING, MISSING_TYPE, is_testing
 
 if TYPE_CHECKING:
     from ._openai import ChatCompletion
@@ -17,7 +16,6 @@ if TYPE_CHECKING:
 def ChatGroq(
     *,
     system_prompt: Optional[str] = None,
-    turns: Optional[list[Turn]] = None,
     model: Optional[str] = None,
     api_key: Optional[str] = None,
     base_url: str = "https://api.groq.com/openai/v1",
@@ -53,13 +51,6 @@ def ChatGroq(
     ----------
     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.
     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
@@ -123,15 +114,21 @@ def ChatGroq(
     """
     if model is None:
         model = log_model_default("llama3-8b-8192")
+
     if api_key is None:
         api_key = os.getenv("GROQ_API_KEY")
 
-    return ChatOpenAI(
+    if isinstance(seed, MISSING_TYPE):
+        seed = 1014 if is_testing() else None
+
+    return Chat(
+        provider=OpenAIProvider(
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            seed=seed,
+            name="Groq",
+            kwargs=kwargs,
+        ),
         system_prompt=system_prompt,
-        turns=turns,
-        model=model,
-        api_key=api_key,
-        base_url=base_url,
-        seed=seed,
-        kwargs=kwargs,
     )