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

chatlas/{_groq.py → _provider_groq.py}

@@ -5,11 +5,11 @@ from typing import TYPE_CHECKING, Optional
 
 from ._chat import Chat
 from ._logging import log_model_default
-from ._openai import OpenAIProvider
+from ._provider_openai import OpenAIProvider
 from ._utils import MISSING, MISSING_TYPE, is_testing
 
 if TYPE_CHECKING:
-    from ._openai import ChatCompletion
+    from ._provider_openai import ChatCompletion
     from .types.openai import ChatClientArgs, SubmitInputArgs
 
 

chatlas/_provider_huggingface.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Optional
+
+from ._chat import Chat
+from ._logging import log_model_default
+from ._provider_openai import OpenAIProvider
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletion
+
+    from .types.openai import ChatClientArgs, SubmitInputArgs
+
+
+def ChatHuggingFace(
+    *,
+    system_prompt: Optional[str] = None,
+    model: Optional[str] = None,
+    api_key: Optional[str] = None,
+    kwargs: Optional["ChatClientArgs"] = None,
+) -> Chat["SubmitInputArgs", ChatCompletion]:
+    """
+    Chat with a model hosted on Hugging Face Inference API.
+
+    [Hugging Face](https://huggingface.co/) hosts a variety of open-source
+    and proprietary AI models available via their Inference API.
+    To use the Hugging Face API, you must have an Access Token, which you can obtain
+    from your [Hugging Face account](https://huggingface.co/settings/tokens).
+    Ensure that at least "Make calls to Inference Providers" and
+    "Make calls to your Inference Endpoints" is checked.
+
+    Prerequisites
+    --------------
+
+    ::: {.callout-note}
+    ## API key
+
+    You will need to create a Hugging Face account and generate an API token
+    from your [account settings](https://huggingface.co/settings/tokens).
+    Make sure to enable "Make calls to Inference Providers" permission.
+    :::
+
+    Examples
+    --------
+    ```python
+    import os
+    from chatlas import ChatHuggingFace
+
+    chat = ChatHuggingFace(api_key=os.getenv("HUGGINGFACE_API_KEY"))
+    chat.chat("What is the capital of France?")
+    ```
+
+    Parameters
+    ----------
+    system_prompt
+        A system prompt to set the behavior of the assistant.
+    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 `HUGGINGFACE_API_KEY` environment
+        variable.
+    kwargs
+        Additional arguments to pass to the underlying OpenAI client
+        constructor.
+
+    Returns
+    -------
+    Chat
+        A chat object that retains the state of the conversation.
+
+    Known limitations
+    -----------------
+
+    * Some models do not support the chat interface or parts of it, for example
+      `google/gemma-2-2b-it` does not support a system prompt. You will need to
+      carefully choose the model.
+    * Tool calling support varies by model - many models do not support it.
+
+    Note
+    ----
+    This function is a lightweight wrapper around [](`~chatlas.ChatOpenAI`), with
+    the defaults tweaked for Hugging Face.
+
+    Note
+    ----
+    Pasting an API key into a chat constructor (e.g., `ChatHuggingFace(api_key="...")`)
+    is the simplest way to get started, and is fine for interactive use, but is
+    problematic for code that may be shared with others.
+
+    Instead, consider using environment variables or a configuration file to manage
+    your credentials. One popular way to manage credentials is to use a `.env` file
+    to store your credentials, and then use the `python-dotenv` package to load them
+    into your environment.
+
+    ```shell
+    pip install python-dotenv
+    ```
+
+    ```shell
+    # .env
+    HUGGINGFACE_API_KEY=...
+    ```
+
+    ```python
+    from chatlas import ChatHuggingFace
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    chat = ChatHuggingFace()
+    chat.console()
+    ```
+
+    Another, more general, solution is to load your environment variables into the shell
+    before starting Python (maybe in a `.bashrc`, `.zshrc`, etc. file):
+
+    ```shell
+    export HUGGINGFACE_API_KEY=...
+    ```
+    """
+    if api_key is None:
+        api_key = os.getenv("HUGGINGFACE_API_KEY")
+
+    if model is None:
+        model = log_model_default("meta-llama/Llama-3.1-8B-Instruct")
+
+    return Chat(
+        provider=HuggingFaceProvider(
+            api_key=api_key,
+            model=model,
+            kwargs=kwargs,
+        ),
+        system_prompt=system_prompt,
+    )
+
+
+class HuggingFaceProvider(OpenAIProvider):
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        model: str,
+        kwargs: Optional["ChatClientArgs"] = None,
+    ):
+        # https://huggingface.co/docs/inference-providers/en/index?python-clients=requests#http--curl
+        super().__init__(
+            name="HuggingFace",
+            model=model,
+            api_key=api_key,
+            base_url="https://router.huggingface.co/v1",
+            kwargs=kwargs,
+        )

chatlas/_provider_mistral.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Optional
+
+from ._chat import Chat
+from ._logging import log_model_default
+from ._provider_openai import OpenAIProvider
+from ._utils import MISSING, MISSING_TYPE, is_testing
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletion
+
+    from .types.openai import ChatClientArgs, SubmitInputArgs
+
+
+def ChatMistral(
+    *,
+    system_prompt: Optional[str] = None,
+    model: Optional[str] = None,
+    api_key: Optional[str] = None,
+    base_url: str = "https://api.mistral.ai/v1/",
+    seed: int | None | MISSING_TYPE = MISSING,
+    kwargs: Optional["ChatClientArgs"] = None,
+) -> Chat["SubmitInputArgs", ChatCompletion]:
+    """
+    Chat with a model hosted on Mistral's La Plateforme.
+
+    Mistral AI provides high-performance language models through their API platform.
+
+    Prerequisites
+    -------------
+
+    ::: {.callout-note}
+    ## API credentials
+
+    Get your API key from https://console.mistral.ai/api-keys.
+    :::
+
+    Examples
+    --------
+    ```python
+    import os
+    from chatlas import ChatMistral
+
+    chat = ChatMistral(api_key=os.getenv("MISTRAL_API_KEY"))
+    chat.chat("Tell me three jokes about statisticians")
+    ```
+
+    Known limitations
+    -----------------
+
+    * Tool calling may be unstable.
+    * Images require a model that supports vision.
+
+    Parameters
+    ----------
+    system_prompt
+        A system prompt to set the behavior of the assistant.
+    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 `MISTRAL_API_KEY` environment
+        variable.
+    base_url
+        The base URL to the endpoint; the default uses Mistral AI.
+    seed
+        Optional integer seed that Mistral uses to try and make output more
+        reproducible.
+    kwargs
+        Additional arguments to pass to the `openai.OpenAI()` client
+        constructor (Mistral uses OpenAI-compatible API).
+
+    Returns
+    -------
+    Chat
+        A chat object that retains the state of the conversation.
+
+    Note
+    ----
+    Pasting an API key into a chat constructor (e.g., `ChatMistral(api_key="...")`)
+    is the simplest way to get started, and is fine for interactive use, but is
+    problematic for code that may be shared with others.
+
+    Instead, consider using environment variables or a configuration file to manage
+    your credentials. One popular way to manage credentials is to use a `.env` file
+    to store your credentials, and then use the `python-dotenv` package to load them
+    into your environment.
+
+    ```shell
+    pip install python-dotenv
+    ```
+
+    ```shell
+    # .env
+    MISTRAL_API_KEY=...
+    ```
+
+    ```python
+    from chatlas import ChatMistral
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    chat = ChatMistral()
+    chat.console()
+    ```
+
+    Another, more general, solution is to load your environment variables into the shell
+    before starting Python (maybe in a `.bashrc`, `.zshrc`, etc. file):
+
+    ```shell
+    export MISTRAL_API_KEY=...
+    ```
+    """
+    if isinstance(seed, MISSING_TYPE):
+        seed = 1014 if is_testing() else None
+
+    if model is None:
+        model = log_model_default("mistral-large-latest")
+
+    if api_key is None:
+        api_key = os.getenv("MISTRAL_API_KEY")
+
+    return Chat(
+        provider=MistralProvider(
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            seed=seed,
+            kwargs=kwargs,
+        ),
+        system_prompt=system_prompt,
+    )
+
+
+class MistralProvider(OpenAIProvider):
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        model: str,
+        base_url: str = "https://api.mistral.ai/v1/",
+        seed: Optional[int] = None,
+        name: str = "Mistral",
+        kwargs: Optional["ChatClientArgs"] = None,
+    ):
+        super().__init__(
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            seed=seed,
+            name=name,
+            kwargs=kwargs,
+        )
+
+    # Mistral is essentially OpenAI-compatible, with a couple small differences.
+    # We _could_ bring in the Mistral SDK and use it directly for more precise typing,
+    # etc., but for now that doesn't seem worth it.
+    def _chat_perform_args(
+        self, stream, turns, tools, data_model=None, kwargs=None
+    ) -> "SubmitInputArgs":
+        # Get the base arguments from OpenAI provider
+        kwargs2 = super()._chat_perform_args(stream, turns, tools, data_model, kwargs)
+
+        # Mistral doesn't support stream_options
+        if "stream_options" in kwargs2:
+            del kwargs2["stream_options"]
+
+        # Mistral wants random_seed, not seed
+        if seed := kwargs2.pop("seed", None):
+            if isinstance(seed, int):
+                kwargs2["extra_body"] = {"random_seed": seed}
+            elif seed is not None:
+                raise ValueError(
+                    "MistralProvider only accepts an integer seed, or None."
+                )
+
+        return kwargs2

chatlas/{_ollama.py → _provider_ollama.py}

@@ -7,11 +7,11 @@ from typing import TYPE_CHECKING, Optional
 import orjson
 
 from ._chat import Chat
-from ._openai import OpenAIProvider
+from ._provider_openai import OpenAIProvider
 from ._utils import MISSING_TYPE, is_testing
 
 if TYPE_CHECKING:
-    from ._openai import ChatCompletion
+    from ._provider_openai import ChatCompletion
     from .types.openai import ChatClientArgs, SubmitInputArgs
 
 

chatlas/{_openai.py → _provider_openai.py}

@@ -310,8 +310,7 @@ class OpenAIProvider(
                 del kwargs_full["tools"]
 
         if stream and "stream_options" not in kwargs_full:
-            if self.__class__.__name__ != "DatabricksProvider":
-                kwargs_full["stream_options"] = {"include_usage": True}
+            kwargs_full["stream_options"] = {"include_usage": True}
 
         return kwargs_full
 
@@ -411,7 +410,9 @@ class OpenAIProvider(
                     if isinstance(x, ContentText):
                         content_parts.append({"type": "text", "text": x.text})
                     elif isinstance(x, ContentJson):
-                        content_parts.append({"type": "text", "text": ""})
+                        content_parts.append(
+                            {"type": "text", "text": "<structured data/>"}
+                        )
                     elif isinstance(x, ContentToolRequest):
                         tool_calls.append(
                             {
@@ -450,7 +451,7 @@ class OpenAIProvider(
                     if isinstance(x, ContentText):
                         contents.append({"type": "text", "text": x.text})
                     elif isinstance(x, ContentJson):
-                        contents.append({"type": "text", "text": ""})
+                        contents.append({"type": "text", "text": "<structured data/>"})
                     elif isinstance(x, ContentPDF):
                         contents.append(
                             {
@@ -522,7 +523,10 @@ class OpenAIProvider(
         contents: list[Content] = []
         if message.content is not None:
             if has_data_model:
-                data = orjson.loads(message.content)
+                data = message.content
+                # Some providers (e.g., Cloudflare) may already provide a dict
+                if not isinstance(data, dict):
+                    data = orjson.loads(data)
                 contents = [ContentJson(value=data)]
             else:
                 contents = [ContentText(text=message.content)]
@@ -531,6 +535,8 @@ class OpenAIProvider(
 
         if tool_calls is not None:
             for call in tool_calls:
+                if call.type != "function":
+                    continue
                 func = call.function
                 if func is None:
                     continue
@@ -557,14 +563,27 @@ class OpenAIProvider(
 
         usage = completion.usage
         if usage is None:
-            tokens = (0, 0)
+            tokens = (0, 0, 0)
         else:
-            tokens = usage.prompt_tokens, usage.completion_tokens
+            if usage.prompt_tokens_details is not None:
+                cached_tokens = (
+                    usage.prompt_tokens_details.cached_tokens
+                    if usage.prompt_tokens_details.cached_tokens
+                    else 0
+                )
+            else:
+                cached_tokens = 0
+            tokens = (
+                usage.prompt_tokens - cached_tokens,
+                usage.completion_tokens,
+                cached_tokens,
+            )
 
         # For some reason ChatGroq() includes tokens under completion.x_groq
+        # Groq does not support caching, so we set cached_tokens to 0
         if usage is None and hasattr(completion, "x_groq"):
             usage = completion.x_groq["usage"]  # type: ignore
-            tokens = usage["prompt_tokens"], usage["completion_tokens"]
+            tokens = usage["prompt_tokens"], usage["completion_tokens"], 0
 
         tokens_log(self, tokens)
 
@@ -703,7 +722,7 @@ class OpenAIAzureProvider(OpenAIProvider):
         api_version: Optional[str] = None,
         api_key: Optional[str] = None,
         seed: int | None = None,
-        name: str = "OpenAIAzure",
+        name: str = "Azure/OpenAI",
         model: Optional[str] = "UnusedValue",
         kwargs: Optional["ChatAzureClientArgs"] = None,
     ):

chatlas/_provider_openrouter.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Optional
+
+from ._chat import Chat
+from ._logging import log_model_default
+from ._provider_openai import OpenAIProvider
+from ._utils import MISSING, MISSING_TYPE, is_testing
+
+if TYPE_CHECKING:
+    from ._provider_openai import ChatCompletion
+    from .types.openai import ChatClientArgs, SubmitInputArgs
+
+
+def ChatOpenRouter(
+    *,
+    system_prompt: Optional[str] = None,
+    model: Optional[str] = None,
+    api_key: Optional[str] = None,
+    base_url: str = "https://openrouter.ai/api/v1",
+    seed: Optional[int] | MISSING_TYPE = MISSING,
+    kwargs: Optional["ChatClientArgs"] = None,
+) -> Chat["SubmitInputArgs", ChatCompletion]:
+    """
+    Chat with one of the many models hosted on OpenRouter.
+
+    OpenRouter provides access to a wide variety of language models from different providers
+    through a unified API. Support for features depends on the underlying model that you use.
+
+    Prerequisites
+    -------------
+
+    ::: {.callout-note}
+    ## API key
+
+    Sign up at <https://openrouter.ai> to get an API key.
+    :::
+
+    Examples
+    --------
+
+    ```python
+    import os
+    from chatlas import ChatOpenRouter
+
+    chat = ChatOpenRouter(api_key=os.getenv("OPENROUTER_API_KEY"))
+    chat.chat("What is the capital of France?")
+    ```
+
+    Parameters
+    ----------
+    system_prompt
+        A system prompt to set the behavior of the assistant.
+    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. See <https://openrouter.ai/models>
+        for available models.
+    api_key
+        The API key to use for authentication. You generally should not supply
+        this directly, but instead set the `OPENROUTER_API_KEY` environment variable.
+    base_url
+        The base URL to the endpoint; the default uses OpenRouter's API.
+    seed
+        Optional integer seed that the model uses to try and make output more
+        reproducible.
+    kwargs
+        Additional arguments to pass to the `openai.OpenAI()` client constructor.
+
+    Returns
+    -------
+    Chat
+        A chat object that retains the state of the conversation.
+
+    Note
+    ----
+    This function is a lightweight wrapper around [](`~chatlas.ChatOpenAI`) with
+    the defaults tweaked for OpenRouter.
+
+    Note
+    ----
+    Pasting an API key into a chat constructor (e.g., `ChatOpenRouter(api_key="...")`)
+    is the simplest way to get started, and is fine for interactive use, but is
+    problematic for code that may be shared with others.
+
+    Instead, consider using environment variables or a configuration file to manage
+    your credentials. One popular way to manage credentials is to use a `.env` file
+    to store your credentials, and then use the `python-dotenv` package to load them
+    into your environment.
+
+    ```shell
+    pip install python-dotenv
+    ```
+
+    ```shell
+    # .env
+    OPENROUTER_API_KEY=...
+    ```
+
+    ```python
+    from chatlas import ChatOpenRouter
+    from dotenv import load_dotenv
+
+    load_dotenv()
+    chat = ChatOpenRouter()
+    chat.console()
+    ```
+
+    Another, more general, solution is to load your environment variables into the shell
+    before starting Python (maybe in a `.bashrc`, `.zshrc`, etc. file):
+
+    ```shell
+    export OPENROUTER_API_KEY=...
+    ```
+    """
+    if model is None:
+        model = log_model_default("gpt-4.1")
+
+    if api_key is None:
+        api_key = os.getenv("OPENROUTER_API_KEY")
+
+    if isinstance(seed, MISSING_TYPE):
+        seed = 1014 if is_testing() else None
+
+    kwargs2 = add_default_headers(kwargs or {})
+
+    return Chat(
+        provider=OpenAIProvider(
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            seed=seed,
+            name="OpenRouter",
+            kwargs=kwargs2,
+        ),
+        system_prompt=system_prompt,
+    )
+
+
+def add_default_headers(kwargs: "ChatClientArgs") -> "ChatClientArgs":
+    headers = kwargs.get("default_headers", None)
+    # https://openrouter.ai/docs/api-keys
+    default_headers = {
+        "HTTP-Referer": "https://posit-dev.github.io/chatlas",
+        "X-Title": "chatlas",
+        **(headers or {}),
+    }
+    return {"default_headers": default_headers, **kwargs}

chatlas/{_perplexity.py → _provider_perplexity.py}

@@ -5,11 +5,11 @@ from typing import TYPE_CHECKING, Optional
 
 from ._chat import Chat
 from ._logging import log_model_default
-from ._openai import OpenAIProvider
+from ._provider_openai import OpenAIProvider
 from ._utils import MISSING, MISSING_TYPE, is_testing
 
 if TYPE_CHECKING:
-    from ._openai import ChatCompletion
+    from ._provider_openai import ChatCompletion
     from .types.openai import ChatClientArgs, SubmitInputArgs