feat(ai): add capabilities, docs, caching

[Light2Dark]

📝 Summary

• Enable provider-adaptive web search, fetch, and X search in the chat panel via pydantic-ai capabilities, using local DuckDuckGo/markdownify fallbacks when installed or provider-native tools when the model supports them
• Consolidate agent creation and per-provider model settings so code mode and other chat modes share the same path, including OpenRouter/Bedrock caching settings
• Document chat tool availability by mode, code mode's execute_code toolset, and how to enable web capabilities
• Add caching to supported providers

📋 Pre-Review Checklist

• For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
• Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
• Video or media evidence is provided for any visual changes (optional).

✅ Merge Checklist

• I have read the contributor guidelines.
• Documentation has been updated where applicable, including docstrings for API changes.
• Tests have been added for the changes made.

Made with Cursor

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Jul 7, 2026 3:53am

[cubic-dev-ai]

1 issue found across 9 files

Architecture diagram

sequenceDiagram
    participant Client as Browser / Chat UI
    participant Route as API Route (stream_completion)
    participant Provider as CompletionProvider
    participant CapRes as CapabilityResolver
    participant Agent as Pydantic Agent
    participant Model as Provider Model
    participant Local as Local Fallback (ddgs/markdownify)
    participant Native as Native Provider Tool

    Note over Client,Native: Chat Completion with Capabilities & Caching

    Client->>Route: POST /api/ai/completion (messages, mode, model, max_tokens)
    Route->>Provider: stream_completion(messages, system_prompt, max_tokens, span_info)

    Provider->>Provider: create_agent(name, max_tokens, tools, system_prompt)

    Provider->>Provider: _build_model_settings(model, max_tokens)
    alt Anthropic / OpenRouter / Bedrock provider
        Provider->>Provider: Set caching flags (anthropic_cache, bedrock_cache, openrouter_route)
    else Other providers
        Provider->>Provider: No caching flags
    end

    Provider->>CapRes: _build_agent_capabilities(model)
    CapRes->>CapRes: Check installed packages (ddgs, markdownify)
    alt Local packages installed
        CapRes->>Local: Use DuckDuckGo/Markdownify as capabilities
    else No local packages
        CapRes->>CapRes: Check provider profile for native support
        alt Provider supports native web search/fetch
            CapRes->>Native: Use provider-native WebFetch, WebSearch, XSearch
        else No native support
            CapRes->>CapRes: No web capabilities enabled
        end
    end
    CapRes-->>Provider: List of AbstractCapability

    Provider->>Agent: Agent(model, model_settings, toolsets, capabilities, instructions)
    Agent->>Model: Model with settings (max_tokens, caching, thinking)

    Provider->>Provider: Stream response via VercelAIAdapter

    alt Streaming path
        Provider->>Agent: run_stream(messages)
        Agent->>Agent: Process conversation, invoke capabilities as needed
        Agent-->>Provider: Stream of events
    else Completion path (non-streaming)
        Provider->>Agent: run(messages)
        Agent-->>Provider: Result object
    end

    Provider-->>Route: StreamingResponse or result
    Route-->>Client: SSE events or JSON response

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Copilot]

Pull request overview

This PR expands marimo’s AI chat integration by adding provider-adaptive web capabilities (search/fetch/X), consolidating agent/model configuration so all chat modes share the same provider path, and documenting tool availability and code mode behavior. It also introduces provider-specific caching settings and updates tests/docs to reflect the new settings/capabilities model.

Changes:

• Refactors providers to build request settings via _build_model_settings(...), adds provider-adaptive capabilities, and updates telemetry tool counting to include capabilities.
• Adds provider caching settings (Anthropic/OpenRouter/Bedrock) and makes custom provider construction more generic via signature inspection.
• Updates docs and skill reference copy, and extends test coverage for capabilities, caching, and custom-provider behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/_server/ai/test_providers.py	Updates/extends provider tests for model settings, caching, capability-aware telemetry, and custom provider behavior.
tests/_server/ai/skills/test_skills_utils.py	Updates assertions to match new “loaded on demand” reference wording.
marimo/_server/ai/skills/marimo-pair/references/rich-representations.md	Removes “do not read from disk” phrasing; keeps capability-loading note.
marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md	Same reference copy adjustment for on-demand loading.
marimo/_server/ai/skills/marimo-pair/references/gotchas.md	Same reference copy adjustment for on-demand loading.
marimo/_server/ai/providers.py	Core refactor: unified agent creation path, provider-adaptive capabilities, caching settings, and custom provider instantiation changes.
marimo/_dependencies/dependencies.py	Adds optional deps (ddgs, markdownify) used for local web search/fetch fallbacks.
docs/guides/editor_features/tools.md	Documents per-mode tool availability plus web capability enablement and code mode toolset.
docs/guides/editor_features/ai_completion.md	Updates chat mode descriptions, including manual-mode web capability behavior and code mode entry.

[akshayka]

execute_code is a low-level concept that we shouldn't expose in the docs.

Gives the assistant access to the notebook kernel, which allows the assistant to inspect the marimo runtime and manipulate the notebook in powerful ways.

@manzt may have other wordsmithing suggestions

[github-actions]

🚀 Development release published. You may be able to view the changes at https://marimo.app?v=0.23.14-dev21