Skip to content

API reference

vizro_experimental.chat.popup.popup

Floating chat popup for Vizro dashboards.

Provides add_chat_popup() to inject a chatbot-style floating widget at the dashboard level. Call it after app.build(dashboard) and before app.run().

Example usage::

from vizro_experimental.chat.popup import add_chat_popup

app = Vizro()
app.build(dashboard)

add_chat_popup(title="Analytics Assistant")
app.run()

add_chat_popup 

add_chat_popup(
    generate_response=None,
    model=None,
    streaming=True,
    chat_id="chat_popup",
    placeholder="How can I help you?",
    title="Chat Assistant",
    color=None,
    reasoning_effort="medium",
)

Add a floating chat popup to a Vizro dashboard.

Call this after app.build(dashboard) and before app.run(). The popup appears as a floating button in the bottom-right corner. Clicking it opens a chat panel that works independently of dashboard pages.

When called without generate_response, automatically creates a data-aware dashboard agent that discovers datasets from data_manager and answers questions using an LLM.

Parameters:

  • generate_response (Callable | None, default: None ) –

    Optional function (messages, **kwargs) -> str | Iterator[str]. messages is parsed history: each dict has role and content (decoded JSON). Return a string for non-streaming, or yield strings for streaming. When omitted, a built-in dashboard agent is created automatically.

  • model –

    A PydanticAI model instance (e.g. OpenAIResponsesModel(...), AnthropicModel(...)) or a "provider:model" string accepted by :class:pydantic_ai.Agent. Only used when generate_response is not provided. Defaults to OpenAIResponsesModel("gpt-5.4-mini-2026-03-17") with the given reasoning_effort applied via :class:OpenAIResponsesModelSettings. Pass a pre-configured instance for a different provider, custom base URL, retries, or zero-retention settings (e.g. OpenAIResponsesModel(..., openai_store=False)).

  • streaming (bool, default: True ) –

    Set True when generate_response yields chunks.

  • chat_id (str, default: 'chat_popup' ) –

    Unique DOM ID prefix. Change if you need multiple popups.

  • placeholder (str, default: 'How can I help you?' ) –

    Placeholder text shown in the input field.

  • title (str, default: 'Chat Assistant' ) –

    Title displayed in the popup header bar.

  • color (str | None, default: None ) –

    Color for the floating toggle button (any CSS color or Mantine color). Defaults to Mantine's primary color if not set.

  • reasoning_effort (Literal['low', 'medium', 'high'], default: 'medium' ) –

    "low" | "medium" (default) | "high". Only used when both generate_response and model are None. Use "high" for complex multi-hop or causal questions; "low" for the snappiest interactive Q&A.

vizro_experimental.chat.popup.dashboard_agent

Dashboard-aware chat agent.

Provides a reusable agent that understands the Vizro dashboard's data and structure. Uses pydantic_ai.Agent with one tool (query_dataframe) and an OpenAI Responses model by default. The loop is just: user prompt → tool call(s) → final assistant text.

create_dashboard_agent 

create_dashboard_agent(
    model=None, *, reasoning_effort="medium"
)

Create a dashboard-aware chat agent.

Must be called after app.build(dashboard).

Uses :class:pydantic_ai.Agent with only the query_dataframe tool. The multi-tool / planning scaffolds that would otherwise apply (filesystem, subagents, todos, summarization) are not enabled — for a single-tool data analyst they would inflate TTFT without improving answer quality.

Parameters:

  • model (Model | str | None, default: None ) –

    A PydanticAI model instance (e.g. OpenAIResponsesModel(...), AnthropicModel(...)) or a provider:model string accepted by :class:pydantic_ai.Agent (e.g. "openai-responses:gpt-5.4-mini"). When omitted, defaults to OpenAIResponsesModel("gpt-5.4-mini-2026-03-17") with reasoning_effort applied via :class:OpenAIResponsesModelSettings. Pass your own configured model instance to override base URL, retries, store=False for zero retention, etc.

  • reasoning_effort (ReasoningEffort, default: 'medium' ) –

    "low" | "medium" (default) | "high". Only applied when model is None; if you pass your own model, set reasoning config on the model instance instead.

Returns:

  • Agent –

    Tuple of (agent, context) where agent is a configured PydanticAI Agent

  • dict[str, Any] –

    and context is the gathered dashboard metadata dict.

make_generate_response 

make_generate_response(agent)

Create a generate_response callable for :func:add_chat_popup.

The returned function converts parsed popup messages into PydanticAI's message-history shape, runs the agent with sync streaming, and yields text chunks (delta mode, so each yielded chunk is a new piece of text — matching the SSE wire format the popup clientside JS expects).

Parameters:

  • agent (Agent) –

    A configured PydanticAI agent (from :func:create_dashboard_agent).

Returns:

  • –

    A callable (messages, **kwargs) -> Iterator[str] expecting parsed messages.