chatlas 0.11.1__tar.gz → 0.15.0__tar.gz

chatlas-0.15.0/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh issue view:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(uv run:*)",
+      "Bash(make:*)",
+      "Bash(uv sync:*)",
+      "Bash(TEST_OPENAI=false uv run python -m pytest:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

chatlas-0.15.0/.github/workflows/check-vcr-secrets.yml

@@ -0,0 +1,43 @@
+name: Check VCR Secrets
+
+# Scan VCR cassettes for leaked secrets when they change.
+# Uses Claude for thorough analysis of potential credential leaks.
+
+on:
+  pull_request:
+    paths:
+      - "tests/_vcr/**"
+  push:
+    branches: ["main"]
+    paths:
+      - "tests/_vcr/**"
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: read
+
+jobs:
+  check-secrets:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install the project
+        run: uv sync --python 3.12 --all-extras
+
+      - name: Scan for secrets with Claude
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          if [ -z "$ANTHROPIC_API_KEY" ]; then
+            echo "::warning::ANTHROPIC_API_KEY not set, skipping secret scan"
+            exit 0
+          fi
+          make check-vcr-secrets

chatlas-0.15.0/.github/workflows/test-live.yml

@@ -0,0 +1,66 @@
+name: Test (Live API)
+
+# This workflow runs tests against live APIs to verify VCR cassettes are up-to-date.
+# It requires API keys and runs less frequently than the main test workflow.
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  test-live:
+    runs-on: ubuntu-latest
+
+    env:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
+      CLOUDFLARE_API_KEY: ${{ secrets.CLOUDFLARE_API_KEY }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
+      DATABRICKS_TOKEN: ${{ secrets.DATABRICKS_TOKEN }}
+      DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}
+      GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+      GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HUGGINGFACE_API_KEY: ${{ secrets.HUGGINGFACE_API_KEY }}
+      MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install the project
+        run: uv sync --python 3.12 --all-extras
+
+      - name: Create Snowflake connections.toml file
+        run: |
+          mkdir -p ~/.ssh
+          echo '${{ secrets.SNOWFLAKE_SSH_PUBLIC_KEY }}' > ~/.ssh/snowflake_key.pub
+          echo '${{ secrets.SNOWFLAKE_SSH_PRIVATE_KEY }}' > ~/.ssh/snowflake_key.p8
+          chmod 644 ~/.ssh/snowflake_key.pub
+          chmod 600 ~/.ssh/snowflake_key.p8
+          chmod 700 ~/.ssh
+
+          mkdir -p ~/.snowflake
+          cat > ~/.snowflake/connections.toml << 'EOF'
+          [posit]
+          account="duloftf-posit-software-pbc-dev"
+          user="carson@posit.co"
+          private_key_file="/home/runner/.ssh/snowflake_key.p8"
+          private_key_file_pwd="${{ secrets.SNOWFLAKE_SSH_PRIVATE_KEY_PASSWORD }}"
+          EOF
+
+      - name: Check tests
+        run: make check-tests

chatlas-0.15.0/.github/workflows/test.yml

@@ -0,0 +1,46 @@
+name: Test
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main", "rc-*"]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    # Note: Dummy API keys for VCR replay testing are set in the Makefile.
+    # This workflow will not make any live API calls; those are reserved for
+    # the test-live.yml workflow.
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --python ${{ matrix.python-version }} --all-extras
+
+      - name: Check tests
+        run: make check-tests
+
+      - name: Check types
+        run: make check-types
+
+      - name: Check formatting
+        run: make check-format

{chatlas-0.11.1 → chatlas-0.15.0}/.gitignore

@@ -7,6 +7,7 @@ Untitled*.ipynb
 uv.lock
 
 sandbox/
+logs/
 
 /.luarc.json
 

{chatlas-0.11.1 → chatlas-0.15.0}/.vscode/settings.json

@@ -7,5 +7,12 @@
         },
         "editor.defaultFormatter": "charliermarsh.ruff",
     },
-    "flake8.args": ["--max-line-length=120"]
-}
+    "flake8.args": [
+      "--max-line-length=120"
+    ],
+    "python.testing.pytestArgs": [
+      "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

{chatlas-0.11.1 → chatlas-0.15.0}/CHANGELOG.md

@@ -7,6 +7,123 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 -->
 
+## [0.15.0] - 2026-01-06
+
+### New features
+
+* `ChatOpenAI()`, `ChatAnthropic()`, and `ChatGoogle()` gain a new `reasoning` parameter to easily opt-into, and fully customize, reasoning capabilities. (#202, #260)
+    * A new `ContentThinking` content type was added and captures the "thinking" portion of a reasoning model. (#192)
+* Added "built-in" web search and URL fetch tools `tool_web_search()` and `tool_web_fetch()`:
+    * `tool_web_search()` is supported by OpenAI, Claude (Anthropic), and Google (Gemini).
+    * `tool_web_fetch()` is supported by Claude (requires beta header) and Google.
+    * New content types `ContentToolRequestSearch`, `ContentToolResponseSearch`, `ContentToolRequestFetch`, and `ContentToolResponseFetch` capture web tool interactions.
+* Added `ToolBuiltIn` class to assist with specifying provider-specific built-in tools. This enables provider-specific functionality like OpenAI's image generation to be registered and used as tools. Built-in tools pass raw provider definitions directly to the API rather than wrapping Python functions. (#214)
+* `ChatOpenAI()` and `ChatAzureOpenAI()` gain a new `service_tier` parameter to request a specific service tier (e.g., `"flex"` for slower/cheaper or `"priority"` for faster/more expensive). (#204)
+* `ChatAuto()` now accepts `"claude"` as an alias for `"anthropic"`, reflecting Anthropic's rebranding of developer tools under the Claude name. (#239)
+
+### Changes
+
+* `repr()` now generally gives the same result as `str()` for many classes (`Chat`, `Turn`, `Content`, etc). This leads to a more human-readable result (and is closer to the result that gets `echo`ed by `.chat()`). (#245)
+* The `Chat.get_cost()` method's `options` parameter was renamed to `include`. (#244)
+* When supplying a `model` to `.register_tool(tool_func, model=ToolModel)`, the defaults for the `model` must match the `tool_func` defaults. Previously, if `tool_func` had defaults, but `ToolModel` didn't, those defaults would get silently ignored. (#253)
+
+### Improvements
+
+* `Chat` and `Turn` now have a `_repr_markdown_` method and an overall improved `repr()` experience. (#245)
+* `ChatSnowflake()` now sets the `application` config parameter for partner identification. Defaults to `"py_chatlas"` but can be overridden via the `SF_PARTNER` environment variable. (#209)
+
+### Bug fixes
+
+* Fixed structured data extraction with `ChatAnthropic()` failing for Pydantic models containing nested types (e.g., `list[NestedModel]`). The issue was that `$defs` (containing nested type definitions) was incorrectly placed inside the schema, breaking JSON `$ref` pointer references. (#100)
+* Fixed MCP tools failing with OpenAI providers due to strict mode schema validation. OpenAI's strict mode rejects standard JSON Schema features like `format: "uri"` and requires all properties in the `required` array. MCP tools now set `strict=false` to use standard JSON Schema conventions. (#255)
+* Fixed MCP tools not working with `ChatGoogle()`. (#257)
+* Tool functions parameters that are `typing.Annotated` with a `pydantic.Field` (e.g., `def add(x: Annotated[int, Field(description="First number")])`) are now handled correctly. (#251)
+
+
+## [0.14.0] - 2025-12-09
+
+### New features
+
+* `ChatOpenAI()` (and `ChatAzureOpenAI()`) gain access to latest models, built-in tools, etc. as a result of moving to the new [Responses API](https://platform.openai.com/docs/api-reference/responses). (#192)
+* Added new family of functions (`parallel_chat()`, `parallel_chat_text()`, and `parallel_chat_structured()`) for submitting multiple prompts at once with some basic rate limiting toggles. (#188)
+* Tools can now return image or PDF content types, with `content_image_file()` or `content_pdf_file()` (#231).
+    * As a result, the experimental `ContentToolResultImage` and `ContentToolResultResource` were removed since this new support for generally supporting `ContentImage` and `ContentPDF` renders those content types redundant.
+* Added support for systematic evaluation via [Inspect AI](https://inspect.aisi.org.uk/). This includes:
+    * A new `.export_eval()` method for exporting conversation history as an Inspect eval dataset sample. This supports multi-turn conversations, tool calls, images, PDFs, and structured data.
+    * A new `.to_solver()` method for translating chat instances into Inspect solvers that can be used with Inspect's evaluation framework.
+    * A new `Turn.to_inspect_messages()` method for converting turns to Inspect's message format.
+    * Comprehensive documentation in the [Evals guide](https://posit-dev.github.io/chatlas/misc/evals.html).
+* `ChatAnthropic()` and `ChatBedrockAnthropic()` gain new `cache` parameter to control caching. For `ChatAnthropic()`, it defaults to `"5m"`, which should (on average) reduce the cost of your chats. For `ChatBedrockAnthropic()`, it defaults to `"none"`, since caching isn't guaranteed to be widely supported (#215)
+* Added rudimentary support for a new `ContentThinking` type. (#192)
+
+### Changes
+
+* `ChatOpenAI()` (and `ChatAzureOpenAI()`) move from OpenAI's Completions API to [Responses API](https://platform.openai.com/docs/api-reference/responses). If this happens to break behavior, change `ChatOpenAI()` -> `ChatOpenAICompletions()` (or `ChatAzureOpenAI()` -> `ChatAzureOpenAICompletions()`). (#192)
+* The `Turn` class is now a base class with three specialized subclasses: `UserTurn`, `AssistantTurn`, and `SystemTurn`. Use these new classes to construct turns by hand. (#224)
+* The `.set_model_params()` method no longer accepts `kwargs`. Instead, use the new `chat.kwargs_chat` attribute to set chat input parameters that persist across the chat session. (#212)
+* `Provider` implementations now require an additional `.value_tokens()` method. Previously, it was assumed that token info was logged and attached to the `Turn` as part of the `.value_turn()` method. The logging and attaching is now handled automatically. (#194)
+
+### Improvements
+
+* `ChatAnthropic()` and `ChatBedrockAnthropic()` now default to Claude Sonnet 4.5.
+* `ChatGroq()` now defaults to llama-3.1-8b-instant.
+* `Chat.chat()`, `Chat.stream()`, and related methods now automatically complete dangling tool requests when a chat is interrupted during a tool call loop, allowing the conversation to be resumed without causing API errors (#230).
+* `content_pdf_file()` and `content_pdf_url()` now include relevant `filename` information. (#199)
+
+### Bug fixes
+
+* `.set_model_params()` now works correctly for `.*_async()` methods. (#198)
+* `.chat_structured()` results are now included correctly into the multi-turn conversation history. (#203)
+* `ChatAnthropic()` now drops empty assistant turns to avoid API errors when tools return side-effect only results. (#226)
+
+## [0.13.2] - 2025-10-02
+
+### Improvements
+
+* `ContentToolResult`'s `.get_model_value()` method now calls `.to_json(orient="record")` (instead of `.to_json()`) when relevant. As a result, if a tool call returns a Pandas `DataFrame` (or similar), the model now receives a less confusing (and smaller) JSON format. (#183)
+
+### Bug fixes
+
+* `ChatAzureOpenAI()` and `ChatDatabricks()` now work as expected when a `OPENAI_API_KEY` environment variable isn't present. (#185)
+
+## [0.13.1] - 2025-09-18
+
+### Bug fixes
+
+* `ChatGithub()` once again uses the appropriate `base_url` when generating reponses (problem introduced in v0.11.0). (#182)
+
+## [0.13.0] - 2025-09-10
+
+### New features
+
+* Added support for submitting multiple chats in one batch. With batch submission, results can take up to 24 hours to complete, but in return you pay ~50% less than usual. For more, see the [reference](https://posit-dev.github.io/chatlas/reference/) for `batch_chat()`, `batch_chat_text()`, `batch_chat_structured()` and `batch_chat_completed()`. (#177)
+* The `Chat` class gains new `.chat_structured()` (and `.chat_structured_async()`) methods. These methods supersede the now deprecated `.extract_data()` (and `.extract_data_async()`). The only difference is that the new methods return a `BaseModel` instance (instead of a `dict()`), leading to a better type hinting/checking experience.  (#175)
+* The `.get_turns()` method gains a `tool_result_role` parameter. Set `tool_result_role="assistant"` to collect tool result content (plus the surrounding assistant turn contents) into a single assistant turn. This is convenient for display purposes and more generally if you want the tool calling loop to be contained in a single turn. (#179) 
+
+### Improvements
+
+* The `.app()` method now:
+    * Enables bookmarking by default (i.e., chat session survives page reload). (#179)
+    * Correctly renders pre-existing turns that contain tool calls. (#179)
+
+## [0.12.0] - 2025-09-08
+
+### Breaking changes
+
+* `ChatAuto()`'s first (optional) positional parameter has changed from `system_prompt` to `provider_model`, and `system_prompt` is now a keyword parameter. As a result, you may need to change `ChatAuto("[system prompt]")` -> `ChatAuto(system_prompt="[system prompt]")`. In addition, the `provider` and `model` keyword arguments are now deprecated, but continue to work with a warning, as are the previous `CHATLAS_CHAT_PROVIDER` and `CHATLAS_CHAT_MODEL` environment variables. (#159)
+
+### New features
+
+* `ChatAuto()`'s new `provider_model` takes both provider and model in a single string in the format `"{provider}/{model}"`, e.g. `"openai/gpt-5"`. If not provided, `ChatAuto()` looks for the `CHATLAS_CHAT_PROVIDER_MODEL` environment variable, defaulting to `"openai"` if neither are provided. Unlike previous versions of `ChatAuto()`, the environment variables are now used *only if function arguments are not provided*. In other words, if `provider_model` is given, the `CHATLAS_CHAT_PROVIDER_MODEL` environment variable is ignored. Similarly, `CHATLAS_CHAT_ARGS` are only used if no `kwargs` are provided. This improves interactive use cases, makes it easier to introduce application-specific environment variables, and puts more control in the hands of the developer. (#159)
+* The `.register_tool()` method now: 
+  * Accepts a `Tool` instance as input. This is primarily useful for binding things like `annotations` to the `Tool` in one place, and registering it in another. (#172)
+  * Supports function parameter names that start with an underscore. (#174)
+* The `ToolAnnotations` type gains an `extra` key field -- providing a place for providing additional information that other consumers of tool annotations (e.g., [shinychat](https://posit-dev.github.io/shinychat/)) may make use of.
+
+### Bug fixes
+
+* `ChatAuto()` now supports recently added providers such as `ChatCloudflare()`, `ChatDeepseek()`, `ChatHuggingFace()`, etc. (#159)
+
 ## [0.11.1] - 2025-08-29
 
 ### New features
@@ -22,7 +139,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `.register_tool(annotations=annotations)` drops support for `mcp.types.ToolAnnotations()` and instead expects a dictionary of the same info. (#164)
 
-
 ## [0.11.0] - 2025-08-26
 
 ### New features
@@ -42,7 +158,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New features
 
-* Added `ChatCloudflare()` for chatting via [Cloudflare AI](https://developers.cloudflare.com/workers-ai/get-started/rest-api/). (#150) 
+* Added `ChatCloudflare()` for chatting via [Cloudflare AI](https://developers.cloudflare.com/workers-ai/get-started/rest-api/). (#150)
 * Added `ChatDeepSeek()` for chatting via [DeepSeek](https://www.deepseek.com/). (#147)
 * Added `ChatOpenRouter()` for chatting via [Open Router](https://openrouter.ai/). (#148)
 * Added `ChatHuggingFace()` for chatting via [Hugging Face](https://huggingface.co/). (#144)
@@ -78,7 +194,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New features
 
-* `Chat` gains a handful of new methods: 
+* `Chat` gains a handful of new methods:
     * `.register_mcp_tools_http_stream_async()` and `.register_mcp_tools_stdio_async()`: for registering tools from a [MCP server](https://modelcontextprotocol.io/). (#39)
     * `.get_tools()` and `.set_tools()`: for fine-grained control over registered tools. (#39)
     * `.set_model_params()`: for setting common LLM parameters in a model-agnostic fashion. (#127)
@@ -87,7 +203,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Tool functions passed to `.register_tool()` can now `yield` numerous results. (#39)
 * A `ContentToolResultImage` content class was added for returning images from tools. It is currently only works with `ChatAnthropic`. (#39)
 * A `Tool` can now be constructed from a pre-existing tool schema (via a new `__init__` method). (#39)
-* The `Chat.app()` method gains a `host` parameter. (#122) 
+* The `Chat.app()` method gains a `host` parameter. (#122)
 * `ChatGithub()` now supports the more standard `GITHUB_TOKEN` environment variable for storing the API key. (#123)
 
 ### Changes
@@ -149,7 +265,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.7.1] - 2025-05-10
 
-* Added `openai` as a hard dependency, making installation easier for a wide range of use cases. (#91) 
+* Added `openai` as a hard dependency, making installation easier for a wide range of use cases. (#91)
 
 ## [0.7.0] - 2025-04-22
 
@@ -159,7 +275,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * `.stream()` and `.stream_async()` gain a `content` argument. Set this to `"all"` to include `ContentToolResult`/`ContentToolRequest` objects in the stream. (#75)
 * `ContentToolResult`/`ContentToolRequest` are now exported to `chatlas` namespace. (#75)
 * `ContentToolResult`/`ContentToolRequest` gain a `.tagify()` method so they render sensibly in a Shiny app. (#75)
-* A tool can now return a `ContentToolResult`. This is useful for: 
+* A tool can now return a `ContentToolResult`. This is useful for:
     * Specifying the format used for sending the tool result to the chat model (`model_format`). (#87)
     * Custom rendering of the tool result (by overriding relevant methods in a subclass). (#75)
 * `Chat` gains a new `.current_display` property. When a `.chat()` or `.stream()` is currently active, this property returns an object with a `.echo()` method (to echo new content to the display). This is primarily useful for displaying custom content during a tool call. (#79)

{chatlas-0.11.1 → chatlas-0.15.0}/CLAUDE.md

@@ -7,13 +7,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 The project uses `uv` for package management and Make for common tasks:
 
 - **Setup environment**: `make setup` (installs all dependencies with `uv sync --all-extras`)
-- **Run tests**: `make check-tests` or `uv run pytest`
+- **Run tests**: `make check-tests` or `uv run pytest` (uses VCR cassettes by default)
 - **Type checking**: `make check-types` or `uv run pyright`
 - **Linting/formatting**: `make check-format` (check) or `make format` (fix)
 - **Full checks**: `make check` (runs format, type, and test checks)
 - **Build package**: `make build` (creates dist/ with built package)
 - **Run single test**: `uv run pytest tests/test_specific_file.py::TestClass::test_method -v`
 - **Update snapshots**: `make update-snaps` (for syrupy snapshot tests)
+- **Update VCR cassettes**: `make update-snaps-vcr` (re-records HTTP interactions, requires API keys)
+- **Check VCR secrets**: `make check-vcr-secrets` (scans cassettes for leaked credentials)
 - **Documentation**: `make docs` (build) or `make docs-preview` (serve locally)
 
 ## Project Architecture
@@ -49,6 +51,14 @@ The project uses `uv` for package management and Make for common tasks:
 4. **Content-Based Messaging**: All communication uses structured `Content` objects rather than raw strings
 5. **Tool Integration**: Seamless function calling with automatic JSON schema generation from Python type hints
 
+### Typing Best Practices
+
+This project prioritizes strong typing that leverages provider SDK types directly:
+
+- **Use provider SDK types**: Import and use types from `openai.types`, `anthropic.types`, `google.genai.types`, etc. rather than creating custom TypedDicts or dataclasses that mirror them. This ensures compatibility with SDK updates and provides better IDE support.
+- **Use `@overload` for provider-specific returns**: When a method returns different types based on a provider argument, use `@overload` with `Literal` types to give callers precise return type information.
+- **Explore SDK types interactively**: Use `python -c "from <sdk>.types import <Type>; print(<Type>.__annotations__)"` to inspect available fields and nested types when implementing provider-specific features.
+
 ### Testing Structure
 
 - Tests are organized by component (e.g., `test_provider_openai.py`, `test_tools.py`)
@@ -56,6 +66,46 @@ The project uses `uv` for package management and Make for common tasks:
 - MCP server tests use local test servers in `tests/mcp_servers/`
 - Async tests configured via `pytest.ini` with `asyncio_mode=strict`
 
+### VCR Testing (HTTP Recording/Replay)
+
+Tests use [pytest-recording](https://github.com/kiwicom/pytest-recording) (wrapping vcrpy) to record and replay HTTP interactions:
+
+- **Cassettes**: YAML files stored in `tests/_vcr/` organized by test module
+- **Default mode**: Tests replay cassettes without making live API calls
+- **Recording**: Use `make update-snaps-vcr` or `uv run pytest --record-mode=rewrite` (requires real API keys)
+- **Dummy credentials**: Auto-set by `conftest.py` when env vars are missing, enabling VCR replay without secrets
+
+**Adding VCR to tests**:
+```python
+from .conftest import make_vcr_config, VCR_MATCH_ON_WITHOUT_BODY
+
+# Most tests use default config (matches on request body)
+@pytest.mark.vcr
+def test_provider_simple():
+    ...
+
+# For tests with dynamic request bodies (temp files, generated IDs)
+@pytest.fixture(scope="module")
+def vcr_config():
+    return make_vcr_config(match_on=VCR_MATCH_ON_WITHOUT_BODY)
+```
+
+**Tests requiring live API** (skip in VCR mode):
+```python
+from .conftest import is_dummy_credential
+
+@pytest.mark.skipif(
+    is_dummy_credential("ANTHROPIC_API_KEY"),
+    reason="This test requires live API calls",
+)
+def test_multi_sample():
+    ...
+```
+
+**Providers incompatible with VCR**: Bedrock and Snowflake require live API tests due to auth mechanisms.
+
+See `docs/dev/vcr-tests.md` for comprehensive documentation.
+
 ### Documentation
 
 Documentation is built with Quarto and quartodoc:
@@ -112,18 +162,31 @@ When implementing a new LLM provider, follow this systematic approach:
    ```python
    import os
    import pytest
-   
+
    do_test = os.getenv("TEST_[NAME]", "true")
    if do_test.lower() == "false":
        pytest.skip("Skipping [Name] tests", allow_module_level=True)
    ```
-3. **Use standard test patterns**:
+3. **Add VCR support** (for most providers):
+   ```python
+   @pytest.mark.vcr
+   def test_[name]_simple_request():
+       ...
+   ```
+   For async tests, put `@pytest.mark.vcr` before `@pytest.mark.asyncio`.
+4. **Use standard test patterns**:
    - `test_[name]_simple_request()`
-   - `test_[name]_simple_streaming_request()`  
+   - `test_[name]_simple_streaming_request()`
    - `test_[name]_respects_turns_interface()`
    - `test_[name]_tool_variations()` (if supported)
    - `test_data_extraction()`
    - `test_[name]_images()` (if vision supported)
+5. **Record VCR cassettes**:
+   ```bash
+   # Set real API key, then record
+   export [PROVIDER]_API_KEY="..."
+   uv run pytest tests/test_provider_[name].py -v --record-mode=rewrite
+   ```
 
 ### 4. Package Integration
 1. **Update `chatlas/__init__.py`**:
@@ -133,8 +196,9 @@ When implementing a new LLM provider, follow this systematic approach:
 2. **Run validation**:
    ```bash
    uv run pyright chatlas/_provider_[name].py
-   TEST_[NAME]=false uv run pytest tests/test_provider_[name].py -v
+   uv run pytest tests/test_provider_[name].py -v  # Replays VCR cassettes
    uv run python -c "from chatlas import Chat[Name]; print('Import successful')"
+   make check-vcr-secrets  # Ensure no secrets leaked in cassettes
    ```
 
 ### 5. Provider-Specific Customizations
@@ -164,4 +228,12 @@ When implementing a new LLM provider, follow this systematic approach:
 
 ## Connections to ellmer
 
-This project is the Python equivalent of the R package ellmer. The source code for ellmer is available in a sibling directory to this project. Before implementing new features or bug fixes in chatlas, it may be useful to consult  the ellmer codebase to: (1) check whether the feature/fix already exists on the R side and (2) make sure the projects are aligned in terms of stylistic approaches. Note also that ellmer itself has a CLAUDE.md file which has a useful overview of the project. 
+This project is the Python equivalent of the R package ellmer. The source code for ellmer is available in a sibling directory to this project. Before implementing new features or bug fixes in chatlas, it may be useful to consult  the ellmer codebase to: (1) check whether the feature/fix already exists on the R side and (2) make sure the projects are aligned in terms of stylistic approaches. Note also that ellmer itself has a CLAUDE.md file which has a useful overview of the project. 
+
+## Differences from ellmer
+
+One important difference to note is that in `ellmer::chat_openai()` uses the completions API, while `chatlas.ChatOpenAI()` uses the responses API. Look to `ellmer::chat_openai_responses()` and `chatlas.ChatOpenAICompletions()` for the "non-default" API.
+
+## Access to gh CLI
+
+If ellmer or chatlas issues or PRs are referenced, try using the `gh` CLI tool to gain necessary context. They live at `tidyverse/ellmer` and `posit-dev/chatlas`

{chatlas-0.11.1 → chatlas-0.15.0}/Makefile

@@ -66,6 +66,16 @@ update-snaps:
 	@echo "📸 Updating pytest snapshots"
 	uv run pytest --snapshot-update
 
+.PHONY: update-snaps-vcr
+update-snaps-vcr:
+	@echo "📼 Updating VCR cassettes"
+	uv run pytest --record-mode=rewrite
+
+.PHONY: check-vcr-secrets
+check-vcr-secrets:  ## [py] Scan VCR cassettes for leaked secrets using Claude
+	@echo "🤖 Running Claude-based secret scan..."
+	uv run python scripts/check_vcr_secrets.py
+
 .PHONY: update-types
 update-types:
 	@echo "📝 Updating chat provider types"

{chatlas-0.11.1 → chatlas-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatlas
-Version: 0.11.1
+Version: 0.15.0
 Summary: A simple and consistent interface for chatting with LLMs
 Project-URL: Homepage, https://posit-dev.github.io/chatlas
 Project-URL: Documentation, https://posit-dev.github.io/chatlas
@@ -13,11 +13,11 @@ License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.9
 Requires-Dist: jinja2
 Requires-Dist: openai
@@ -38,12 +38,16 @@ Requires-Dist: databricks-sdk; extra == 'dev'
 Requires-Dist: google-genai>=1.14.0; extra == 'dev'
 Requires-Dist: htmltools; extra == 'dev'
 Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: narwhals; extra == 'dev'
 Requires-Dist: numpy>1.24.4; extra == 'dev'
 Requires-Dist: openai; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
 Requires-Dist: pillow; extra == 'dev'
+Requires-Dist: polars; extra == 'dev'
 Requires-Dist: python-dotenv; extra == 'dev'
 Requires-Dist: ruff>=0.6.5; extra == 'dev'
 Requires-Dist: shiny; extra == 'dev'
+Requires-Dist: shinychat; extra == 'dev'
 Requires-Dist: snowflake-ml-python>=1.8.4; extra == 'dev'
 Requires-Dist: tenacity; extra == 'dev'
 Requires-Dist: tiktoken; extra == 'dev'
@@ -59,6 +63,8 @@ Requires-Dist: pandas; extra == 'docs'
 Requires-Dist: pyyaml; extra == 'docs'
 Requires-Dist: quartodoc>=0.7; extra == 'docs'
 Requires-Dist: sentence-transformers; extra == 'docs'
+Provides-Extra: eval
+Requires-Dist: inspect-ai; (python_version >= '3.10') and extra == 'eval'
 Provides-Extra: github
 Provides-Extra: google
 Requires-Dist: google-genai>=1.14.0; extra == 'google'
@@ -73,8 +79,10 @@ Requires-Dist: snowflake-ml-python<=1.9.0; extra == 'snowflake'
 Provides-Extra: test
 Requires-Dist: pyright>=1.1.379; extra == 'test'
 Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest-recording>=0.13; extra == 'test'
 Requires-Dist: pytest>=8.3.2; extra == 'test'
 Requires-Dist: syrupy>=4; extra == 'test'
+Requires-Dist: vcrpy>=6.0.0; extra == 'test'
 Provides-Extra: vertex
 Requires-Dist: google-genai>=1.14.0; extra == 'vertex'
 Description-Content-Type: text/markdown