chatlas 0.11.1__py3-none-any.whl → 0.13.0__py3-none-any.whl

chatlas/__init__.py

@@ -1,5 +1,11 @@
 from . import types
 from ._auto import ChatAuto
+from ._batch_chat import (
+    batch_chat,
+    batch_chat_completed,
+    batch_chat_structured,
+    batch_chat_text,
+)
 from ._chat import Chat
 from ._content import (
     ContentToolRequest,
@@ -36,6 +42,10 @@ except ImportError:  # pragma: no cover
     __version__ = "0.0.0"  # stub value for docs
 
 __all__ = (
+    "batch_chat",
+    "batch_chat_completed",
+    "batch_chat_structured",
+    "batch_chat_text",
     "ChatAnthropic",
     "ChatAuto",
     "ChatBedrockAnthropic",

chatlas/_auto.py

@@ -1,32 +1,46 @@
 from __future__ import annotations
 
 import os
+import warnings
 from typing import Callable, Literal, Optional
 
 import orjson
 
 from ._chat import Chat
 from ._provider_anthropic import ChatAnthropic, ChatBedrockAnthropic
+from ._provider_cloudflare import ChatCloudflare
 from ._provider_databricks import ChatDatabricks
+from ._provider_deepseek import ChatDeepSeek
 from ._provider_github import ChatGithub
 from ._provider_google import ChatGoogle, ChatVertex
 from ._provider_groq import ChatGroq
+from ._provider_huggingface import ChatHuggingFace
+from ._provider_mistral import ChatMistral
 from ._provider_ollama import ChatOllama
 from ._provider_openai import ChatAzureOpenAI, ChatOpenAI
+from ._provider_openrouter import ChatOpenRouter
 from ._provider_perplexity import ChatPerplexity
+from ._provider_portkey import ChatPortkey
 from ._provider_snowflake import ChatSnowflake
+from ._utils import MISSING_TYPE as DEPRECATED_TYPE
 
 AutoProviders = Literal[
     "anthropic",
     "bedrock-anthropic",
+    "cloudflare",
     "databricks",
+    "deep-seek",
     "github",
     "google",
     "groq",
+    "hugging-face",
+    "mistral",
     "ollama",
     "openai",
     "azure-openai",
+    "open-router",
     "perplexity",
+    "portkey",
     "snowflake",
     "vertex",
 ]
@@ -34,41 +48,40 @@ AutoProviders = Literal[
 _provider_chat_model_map: dict[AutoProviders, Callable[..., Chat]] = {
     "anthropic": ChatAnthropic,
     "bedrock-anthropic": ChatBedrockAnthropic,
+    "cloudflare": ChatCloudflare,
     "databricks": ChatDatabricks,
+    "deep-seek": ChatDeepSeek,
     "github": ChatGithub,
     "google": ChatGoogle,
     "groq": ChatGroq,
+    "hugging-face": ChatHuggingFace,
+    "mistral": ChatMistral,
     "ollama": ChatOllama,
     "openai": ChatOpenAI,
     "azure-openai": ChatAzureOpenAI,
+    "open-router": ChatOpenRouter,
     "perplexity": ChatPerplexity,
+    "portkey": ChatPortkey,
     "snowflake": ChatSnowflake,
     "vertex": ChatVertex,
 }
 
+DEPRECATED = DEPRECATED_TYPE()
+
 
 def ChatAuto(
-    system_prompt: Optional[str] = None,
+    provider_model: Optional[str] = None,
     *,
-    provider: Optional[AutoProviders] = None,
-    model: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    provider: AutoProviders | DEPRECATED_TYPE = DEPRECATED,
+    model: str | DEPRECATED_TYPE = DEPRECATED,
     **kwargs,
 ) -> Chat:
     """
-    Use environment variables (env vars) to configure the Chat provider and model.
+    Chat with any provider.
 
-    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).
+    This is a generic interface to all the other `Chat*()` functions, allowing
+    you to pick the provider (and model) with a simple string.
 
     Prerequisites
     -------------
@@ -86,55 +99,101 @@ def ChatAuto(
     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
+    `ChatAuto()` makes it easy to switch between different chat providers and models.
+
+    ```python
+    import pandas as pd
+    from chatlas import ChatAuto
+
+    # Default provider (OpenAI) & model
+    chat = ChatAuto()
+    print(chat.provider.name)
+    print(chat.provider.model)
+
+    # Different provider (Anthropic) & default model
+    chat = ChatAuto("anthropic")
+
+    # List models available through the provider
+    models = chat.list_models()
+    print(pd.DataFrame(models))
+
+    # Choose specific provider/model (Claude Sonnet 4)
+    chat = ChatAuto("anthropic/claude-sonnet-4-0")
     ```
 
-    Then, you can use the `ChatAuto` function to create a Chat instance:
+    The default provider/model can also be controlled through an environment variable:
+
+    ```bash
+    export CHATLAS_CHAT_PROVIDER_MODEL="anthropic/claude-sonnet-4-0"
+    ```
 
     ```python
     from chatlas import ChatAuto
 
     chat = ChatAuto()
-    chat.chat("What is the capital of France?")
+    print(chat.provider.name)   # anthropic
+    print(chat.provider.model)  # claude-sonnet-4-0
+    ```
+
+    For application-specific configurations, consider defining your own environment variables:
+
+    ```bash
+    export MYAPP_PROVIDER_MODEL="google/gemini-2.5-flash"
+    ```
+
+    And passing them to `ChatAuto()` as an alternative way to configure the provider/model:
+
+    ```python
+    import os
+    from chatlas import ChatAuto
+
+    chat = ChatAuto(os.getenv("MYAPP_PROVIDER_MODEL"))
+    print(chat.provider.name)   # google
+    print(chat.provider.model)  # gemini-2.5-flash
     ```
 
     Parameters
     ----------
+    provider_model
+        The name of the provider and model to use in the format
+        `"{provider}/{model}"`. Providers are strings formatted in kebab-case,
+        e.g. to use `ChatBedrockAnthropic` set `provider="bedrock-anthropic"`,
+        and models are the provider-specific model names, e.g.
+        `"claude-3-7-sonnet-20250219"`. The `/{model}` portion may also be
+        omitted, in which case, the default model for that provider will be
+        used.
+
+        If no value is provided, the `CHATLAS_CHAT_PROVIDER_MODEL` environment
+        variable will be consulted for a fallback value. If this variable is also
+        not set, a default value of `"openai"` is used.
     system_prompt
         A system prompt to set the behavior of the assistant.
     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.
+        Deprecated; use `provider_model` instead.
     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.
+        Deprecated; use `provider_model` instead.
     **kwargs
-        Additional keyword arguments to pass to the Chat constructor. See the
+        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`.
+        environment variable as a JSON string. When any additional arguments are
+        provided to `ChatAuto()`, the env var is ignored.
+
+        Note that `system_prompt` and `turns` can't be set via environment variables.
+        They must be provided/set directly to/on `ChatAuto()`.
 
-        Note that `system_prompt` and `turns` in `kwargs` or in
-        `CHATLAS_CHAT_ARGS` are ignored.
+    Note
+    ----
+    If you want to work with a specific provider, but don't know what models are
+    available (or the exact model name), use
+    `ChatAuto('provider_name').list_models()` to list available models. Another
+    option is to use the provider more directly (e.g., `ChatAnthropic()`). There,
+    the `model` parameter may have type hints for available models.
 
     Returns
     -------
@@ -147,32 +206,85 @@ def ChatAuto(
         If no valid provider is specified either through parameters or
         environment variables.
     """
-    the_provider = os.environ.get("CHATLAS_CHAT_PROVIDER", provider)
+    if provider is not DEPRECATED:
+        warn_deprecated_param("provider")
+
+    if model is not DEPRECATED:
+        if provider is DEPRECATED:
+            raise ValueError(
+                "The `model` parameter is deprecated and cannot be used without the `provider` parameter. "
+                "Use `provider_model` instead."
+            )
+        warn_deprecated_param("model")
+
+    if provider_model is None:
+        provider_model = os.environ.get("CHATLAS_CHAT_PROVIDER_MODEL")
+
+    # Backwards compatibility: construct from old env vars as a fallback
+    if provider_model is None:
+        env_provider = get_legacy_env_var("CHATLAS_CHAT_PROVIDER", provider)
+        env_model = get_legacy_env_var("CHATLAS_CHAT_MODEL", model)
+
+        if env_provider:
+            provider_model = env_provider
+            if env_model:
+                provider_model += f"/{env_model}"
+
+    # Fall back to OpenAI if nothing is specified
+    if provider_model is None:
+        provider_model = "openai"
+
+    if "/" in provider_model:
+        the_provider, the_model = provider_model.split("/", 1)
+    else:
+        the_provider, the_model = provider_model, None
 
-    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}
-
-    if env_model := os.environ.get("CHATLAS_CHAT_MODEL"):
-        model = env_model
-
-    if model:
-        base_args["model"] = model
+    # `system_prompt`, `turns` and `model` always come from `ChatAuto()`
+    base_args = {
+        "system_prompt": system_prompt,
+        "turns": None,
+        "model": the_model,
+    }
 
+    # Environment kwargs, used only if no kwargs provided
     env_kwargs = {}
-    if env_kwargs_str := os.environ.get("CHATLAS_CHAT_ARGS"):
-        env_kwargs = orjson.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)
+    if not kwargs:
+        env_kwargs = orjson.loads(os.environ.get("CHATLAS_CHAT_ARGS", "{}"))
+
+    final_kwargs = {**env_kwargs, **kwargs, **base_args}
+    final_kwargs = {k: v for k, v in final_kwargs.items() if v is not None}
+
+    return _provider_chat_model_map[the_provider](**final_kwargs)
+
+
+def get_legacy_env_var(
+    env_var_name: str,
+    default: str | DEPRECATED_TYPE,
+) -> str | None:
+    env_value = os.environ.get(env_var_name)
+    if env_value:
+        warnings.warn(
+            f"The '{env_var_name}' environment variable is deprecated. "
+            "Use 'CHATLAS_CHAT_PROVIDER_MODEL' instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return env_value
+    elif isinstance(default, DEPRECATED_TYPE):
+        return None
+    else:
+        return default
+
+
+def warn_deprecated_param(param_name: str, stacklevel: int = 3) -> None:
+    warnings.warn(
+        f"The '{param_name}' parameter is deprecated. Use 'provider_model' instead.",
+        DeprecationWarning,
+        stacklevel=stacklevel,
+    )

chatlas/_batch_chat.py

@@ -0,0 +1,211 @@
+"""
+Batch chat processing for submitting multiple requests simultaneously.
+
+This module provides functionality for submitting multiple chat requests
+in batches to providers that support it (currently OpenAI and Anthropic).
+Batch processing can take up to 24 hours but offers significant cost savings
+(up to 50% less than regular requests).
+"""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+from typing import TypeVar, Union
+
+from pydantic import BaseModel
+
+from ._batch_job import BatchJob, ContentT
+from ._chat import Chat
+
+ChatT = TypeVar("ChatT", bound=Chat)
+BaseModelT = TypeVar("BaseModelT", bound=BaseModel)
+
+
+def batch_chat(
+    chat: ChatT,
+    prompts: list[ContentT] | list[list[ContentT]],
+    path: Union[str, Path],
+    wait: bool = True,
+) -> list[ChatT | None]:
+    """
+    Submit multiple chat requests in a batch.
+
+    This function allows you to submit multiple chat requests simultaneously
+    using provider batch APIs (currently OpenAI and Anthropic). Batch processing
+    can take up to 24 hours but offers significant cost savings.
+
+    Parameters
+    ----------
+    chat
+        Chat instance to use for the batch
+    prompts
+        List of prompts to process. Each can be a string or list of strings.
+    path
+        Path to file (with .json extension) to store batch state
+    wait
+        If True, wait for batch to complete. If False, return None if incomplete.
+
+    Returns
+    -------
+    List of Chat objects (one per prompt) if complete, None if wait=False and incomplete.
+    Individual Chat objects may be None if their request failed.
+
+    Example
+    -------
+
+    ```python
+    from chatlas import ChatOpenAI
+
+    chat = ChatOpenAI()
+    prompts = [
+        "What's the capital of France?",
+        "What's the capital of Germany?",
+        "What's the capital of Italy?",
+    ]
+
+    chats = batch_chat(chat, prompts, "capitals.json")
+    for i, result_chat in enumerate(chats):
+        if result_chat:
+            print(f"Prompt {i + 1}: {result_chat.get_last_turn().text}")
+    ```
+    """
+    job = BatchJob(chat, prompts, path, wait=wait)
+    job.step_until_done()
+
+    chats = []
+    assistant_turns = job.result_turns()
+    for user, assistant in zip(job.user_turns, assistant_turns):
+        if assistant is not None:
+            new_chat = copy.deepcopy(chat)
+            new_chat.add_turn(user)
+            new_chat.add_turn(assistant)
+            chats.append(new_chat)
+        else:
+            chats.append(None)
+
+    return chats
+
+
+def batch_chat_text(
+    chat: Chat,
+    prompts: list[ContentT] | list[list[ContentT]],
+    path: Union[str, Path],
+    wait: bool = True,
+) -> list[str | None]:
+    """
+    Submit multiple chat requests in a batch and return text responses.
+
+    This is a convenience function that returns just the text of the responses
+    rather than full Chat objects.
+
+    Parameters
+    ----------
+    chat
+        Chat instance to use for the batch
+    prompts
+        List of prompts to process
+    path
+        Path to file (with .json extension) to store batch state
+    wait
+        If True, wait for batch to complete
+
+    Return
+    ------
+    List of text responses (or None for failed requests)
+    """
+    chats = batch_chat(chat, prompts, path, wait=wait)
+
+    texts = []
+    for x in chats:
+        if x is None:
+            texts.append(None)
+            continue
+        last_turn = x.get_last_turn()
+        if last_turn is None:
+            texts.append(None)
+            continue
+        texts.append(last_turn.text)
+
+    return texts
+
+
+def batch_chat_structured(
+    chat: Chat,
+    prompts: list[ContentT] | list[list[ContentT]],
+    path: Union[str, Path],
+    data_model: type[BaseModelT],
+    wait: bool = True,
+) -> list[BaseModelT | None]:
+    """
+    Submit multiple structured data requests in a batch.
+
+    Parameters
+    ----------
+    chat
+        Chat instance to use for the batch
+    prompts
+        List of prompts to process
+    path
+        Path to file (with .json extension) to store batch state
+    data_model
+        Pydantic model class for structured responses
+    wait
+        If True, wait for batch to complete
+
+    Return
+    ------
+    List of structured data objects (or None for failed requests)
+    """
+    job = BatchJob(chat, prompts, path, data_model=data_model, wait=wait)
+    result = job.step_until_done()
+
+    if result is None:
+        return []
+
+    res: list[BaseModelT | None] = []
+    assistant_turns = job.result_turns()
+    for turn in assistant_turns:
+        if turn is None:
+            res.append(None)
+        else:
+            json = chat._extract_turn_json(turn)
+            model = data_model.model_validate(json)
+            res.append(model)
+
+    return res
+
+
+def batch_chat_completed(
+    chat: Chat,
+    prompts: list[ContentT] | list[list[ContentT]],
+    path: Union[str, Path],
+) -> bool:
+    """
+    Check if a batch job is completed without waiting.
+
+    Parameters
+    ----------
+    chat
+        Chat instance used for the batch
+    prompts
+        List of prompts used for the batch
+    path
+        Path to batch state file
+
+    Returns
+    -------
+    True if batch is complete, False otherwise
+    """
+    job = BatchJob(chat, prompts, path, wait=False)
+    stage = job.stage
+
+    if stage == "submitting":
+        return False
+    elif stage == "waiting":
+        status = job._poll()
+        return not status.working
+    elif stage == "retrieving" or stage == "done":
+        return True
+    else:
+        raise ValueError(f"Unknown batch stage: {stage}")