A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat(ai): experimental in-notebook code mode (#9956)
Shahmir Varqha95ecfca656c8
diff --git a/frontend/src/components/chat/chat-panel.tsx b/frontend/src/components/chat/chat-panel.tsxindex 95a7d9388b..70bbd86b30 100644--- a/frontend/src/components/chat/chat-panel.tsx+++ b/frontend/src/components/chat/chat-panel.tsx@@ -23,6 +23,7 @@ import {PlusIcon,SparklesIcon,SettingsIcon,+ CodeIcon,} from "lucide-react";import { memo, useEffect, useRef, useState } from "react";import useEvent from "react-use-event-hook";@@ -268,24 +269,32 @@ const ChatInputFooter: React.FC<ChatInputFooterProps> = memo({value: "ask",label: "Ask",- subtitle:- "Use AI with access to read-only tools like documentation search",+ subtitle: "AI with access to read-only tools like documentation search",Icon: NotebookText,},{value: "agent",- label: "Agent (beta)",- subtitle: "Use AI with access to read and write tools",+ label: "Agent",+ subtitle: "AI with access to read and write tools",Icon: HatGlasses,},];+ if (import.meta.env.DEV) {+ modeOptions.push({+ value: "code_mode",+ label: "Code Mode (experimental)",+ subtitle: "AI with access to the notebook's kernel. Use with caution.",+ Icon: CodeIcon,+ });+ }+const isAttachmentSupported =PROVIDERS_THAT_SUPPORT_ATTACHMENTS.has(currentProvider);- const CurrentModeIcon = modeOptions.find(- (o) => o.value === currentMode,- )?.Icon;+ const currentModeOption = modeOptions.find((o) => o.value === currentMode);+ const CurrentModeIcon = currentModeOption?.Icon;+ const CurrentModeLabel = currentModeOption?.label;return (<TooltipProvider>@@ -294,7 +303,7 @@ const ChatInputFooter: React.FC<ChatInputFooterProps> = memo(<Select value={currentMode} onValueChange={saveModeChange}><SelectTrigger className="h-6 text-xs border-border shadow-none! ring-0! bg-muted hover:bg-muted/30 py-0 px-2 gap-1.5">{CurrentModeIcon && <CurrentModeIcon className="h-3 w-3" />}- <span className="capitalize">{currentMode}</span>+ <span>{CurrentModeLabel}</span></SelectTrigger><SelectContent><SelectGroup>diff --git a/frontend/src/core/config/config-schema.ts b/frontend/src/core/config/config-schema.tsindex 7274dd9b63..a9dba1c12e 100644--- a/frontend/src/core/config/config-schema.ts+++ b/frontend/src/core/config/config-schema.ts@@ -45,7 +45,12 @@ export const DEFAULT_AI_MODEL = "openai/gpt-4o";const AUTO_DOWNLOAD_FORMATS = ["html", "markdown", "ipynb"] as const;export type CopilotMode = NonNullable<schemas["AiConfig"]["mode"]>;-export const COPILOT_MODES: CopilotMode[] = ["manual", "ask", "agent"];+export const COPILOT_MODES: CopilotMode[] = [+ "manual",+ "ask",+ "agent",+ "code_mode",+];const AiConfigSchema = z.object({diff --git a/marimo/_config/config.py b/marimo/_config/config.pyindex 9c394a2b3e..2e8cdcfee7 100644--- a/marimo/_config/config.py+++ b/marimo/_config/config.py@@ -267,7 +267,7 @@ class PackageManagementConfig(TypedDict):manager: Literal["pip", "rye", "uv", "poetry", "pixi"]-CopilotMode = Literal["ask", "manual", "agent"]+CopilotMode = Literal["ask", "manual", "agent", "code_mode"]@mddocdiff --git a/marimo/_server/ai/prompts.py b/marimo/_server/ai/prompts.pyindex a79f56e68c..0376060cb2 100644--- a/marimo/_server/ai/prompts.py+++ b/marimo/_server/ai/prompts.py@@ -2,6 +2,7 @@from __future__ import annotationsfrom marimo._config.config import CopilotMode+from marimo._server.ai.skills.utils import load_skillfrom marimo._server.models.completion import (AiCompletionContext,Language,@@ -45,6 +46,14 @@ language_rules_multiple_cells: dict[Language, list[str]] = {}+def format_context(context: AiCompletionContext) -> str:+ return (+ _format_plain_text(context.plain_text)+ + _format_variables(context.variables)+ + _format_schema_info(context.schema)+ )++def _format_schema_info(tables: list[SchemaTable] | None) -> str:"""Helper to format schema information from context"""if not tables:@@ -195,9 +204,7 @@ def get_refactor_or_insert_notebook_cell_system_prompt(system_prompt += f"\n\n## Additional rules:\n{custom_rules}"if context:- system_prompt += _format_plain_text(context.plain_text)- system_prompt += _format_variables(context.variables)- system_prompt += _format_schema_info(context.schema)+ system_prompt += format_context(context)if other_cell_codes:system_prompt += "\n\n" + _tag(@@ -263,6 +270,11 @@ def _get_mode_intro_message(mode: CopilotMode) -> str:"## Limitations\n""- You must always explain to the user why you are using a tool before invoking it.\n")+ elif mode == "code_mode":+ return (+ f"{base_intro}"+ "You are in code mode - you have access to the notebook's kernel and can execute code."+ )def _get_session_info(session_id: SessionId) -> str:@@ -272,19 +284,50 @@ def _get_session_info(session_id: SessionId) -> str:)-def get_chat_system_prompt(+def _single_cell_language_rules() -> str:+ """Per-language rules for chat modes that emit one cell at a time."""+ out = ""+ for language in language_rules:+ if not language_rules[language]:+ continue+ out += (+ f"\n\n## Rules for {language}:\n{_rules(language_rules[language])}"+ )+ return out+++def _multi_cell_language_rules() -> str:+ """Per-language rules for agent mode, which can insert multiple cells."""+ out = ""+ for lang in LANGUAGES:+ rules = language_rules_multiple_cells.get(+ lang, language_rules.get(lang, [])+ )+ if rules:+ out += f"\n\n## Rules for {lang}:\n{_rules(rules)}"+ return out+++def _common_chat_sections(*,custom_rules: str | None,- context: AiCompletionContext | None,include_other_code: str,- mode: CopilotMode,- session_id: SessionId,+ context: AiCompletionContext | None,) -> str:- system_prompt: str = f"""-{_get_mode_intro_message(mode)}-{_get_session_info(session_id)}+ """Trailing sections shared by every chat mode."""+ out = ""+ if custom_rules and custom_rules.strip():+ out += f"\n\n## Additional rules:\n{custom_rules}"+ if include_other_code:+ out += "\n\n" + _tag("code_from_other_cells", include_other_code)+ if context:+ out += format_context(context)+ return out-Your goal is to do one of the following two things:++# Static guide describing marimo's reactive model, UI elements, and examples.+# Shared by all non-code-mode chat prompts.+_NOTEBOOK_GUIDE = """Your goal is to do one of the following two things:1. Help users answer questions related to their notebook.2. Answer general-purpose questions unrelated to their particular notebook.@@ -386,13 +429,13 @@ n_points # Display the sliderx = np.random.rand(n_points.value)y = np.random.rand(n_points.value)-df = pl.DataFrame({{"x": x, "y": y}})+df = pl.DataFrame({"x": x, "y": y})chart = alt.Chart(df).mark_circle(opacity=0.7).encode(x=alt.X('x', title='X axis'),y=alt.Y('y', title='Y axis')).properties(- title=f"Scatter plot with {{n_points.value}} points",+ title=f"Scatter plot with {n_points.value} points",width=400,height=300)@@ -400,42 +443,52 @@ chart = alt.Chart(df).mark_circle(opacity=0.7).encode(chart</example>"""- if mode == "agent":- # In agent-mode, we can add how to insert cells into the notebook.- for lang in LANGUAGES:- # check if multiple_cells rules are present for this language- rule_to_add = language_rules_multiple_cells.get(- lang, language_rules.get(lang, [])- )- if rule_to_add:- system_prompt += (- f"\n\n## Rules for {lang}:\n{_rules(rule_to_add)}"- )+def get_chat_system_prompt(+ *,+ custom_rules: str | None,+ context: AiCompletionContext | None,+ include_other_code: str,+ mode: CopilotMode,+ session_id: SessionId,+) -> str:+ # Code mode runs against the live kernel, so it leans on the marimo-pair+ # skill instead of the static notebook guide.+ if mode == "code_mode":+ skill_md = load_skill("marimo-pair")+ intro = _get_mode_intro_message(mode)+ skill_section = (+ "The following information explains how to work with marimo "+ f"notebooks:\n\n{skill_md}"+ )+ system_prompt = f"{intro}\n\n{skill_section}"+ system_prompt += _single_cell_language_rules()+ return system_prompt + _common_chat_sections(+ custom_rules=custom_rules,+ include_other_code=include_other_code,+ context=context,+ )++ system_prompt = (+ f"\n{_get_mode_intro_message(mode)}\n{_get_session_info(session_id)}"+ f"\n\n{_NOTEBOOK_GUIDE}"+ )++ if mode == "agent":+ # Agent mode can emit multiple cells, so it gets the multi-cell rules+ # plus guidance on how to wrap each cell type.+ system_prompt += _multi_cell_language_rules()system_prompt += "\n\n## Rules for inserting cells:\n"system_prompt += 'For markdown cells, use `mo.md(f"""{content}""")`\n'system_prompt += 'For sql cells, use `mo.sql(f"""{content}""")`. If a database engine is specified, use `mo.sql(f"""{content}""", engine=engine)` instead.\n'else:- for language in language_rules:- if len(language_rules[language]) == 0:- continue-- system_prompt += f"\n\n## Rules for {language}:\n{_rules(language_rules[language])}"+ system_prompt += _single_cell_language_rules()- if custom_rules and custom_rules.strip():- system_prompt += f"\n\n## Additional rules:\n{custom_rules}"-- if include_other_code:- system_prompt += "\n\n" + _tag(- "code_from_other_cells", include_other_code- )-- if context:- system_prompt += _format_plain_text(context.plain_text)- system_prompt += _format_variables(context.variables)- system_prompt += _format_schema_info(context.schema)-- return system_prompt+ return system_prompt + _common_chat_sections(+ custom_rules=custom_rules,+ include_other_code=include_other_code,+ context=context,+ )def _tag(text: str, children: str) -> str:diff --git a/marimo/_server/ai/providers.py b/marimo/_server/ai/providers.pyindex 93ba093d86..049956ecd2 100644--- a/marimo/_server/ai/providers.py+++ b/marimo/_server/ai/providers.py@@ -61,8 +61,11 @@ if TYPE_CHECKING:from pydantic_ai.providers.openai import OpenAIProvider as PydanticOpenAIfrom pydantic_ai.settings import ModelSettings, ThinkingLevelfrom pydantic_ai.ui.vercel_ai.request_types import UIMessage, UIMessagePart+ from starlette.requests import Requestfrom starlette.responses import StreamingResponse+ from marimo._session import Session+LOGGER = _loggers.marimo_logger()@@ -220,6 +223,49 @@ class PydanticProvider(ABC, Generic[ProviderT]):return str(result.output)+ async def stream_completion_harness(+ self,+ messages: list[ServerUIMessage],+ *,+ system_prompt: str,+ session: Session,+ request: Request,+ max_tokens: int | None,+ stream_options: StreamOptions | None,+ ) -> StreamingResponse:+ """Experimental method to return code-mode streaming responses"""+ from pydantic_ai import Agent+ from pydantic_ai.ui.vercel_ai import VercelAIAdapter+ from pydantic_ai.ui.vercel_ai.request_types import SubmitMessage++ from marimo._server.ai.tools.code_mode import (+ build_execute_code_toolset,+ )++ model = self.create_model(max_tokens=max_tokens)+ agent = Agent(+ model,+ model_settings=self._build_agent_settings(model),+ toolsets=[build_execute_code_toolset(session, request)],+ instructions=system_prompt,+ )++ run_input = SubmitMessage(+ id=generate_id("submit-message"),+ trigger="submit-message",+ messages=self.convert_messages(messages),+ )++ stream_options = stream_options or StreamOptions()+ adapter = VercelAIAdapter(+ agent=agent,+ run_input=run_input,+ accept=stream_options.accept,+ sdk_version=AI_SDK_VERSION,+ )+ event_stream = adapter.run_stream()+ return adapter.streaming_response(event_stream)+def _get_toolsets_and_output_type(self, tools: list[ToolDefinition]) -> tuple[FunctionToolset, OutputSpec[str | DeferredToolRequests]]:diff --git a/marimo/_server/ai/skills/marimo-pair/SKILL.md b/marimo/_server/ai/skills/marimo-pair/SKILL.mdnew file mode 100644index 0000000000..2da0eac4f1--- /dev/null+++ b/marimo/_server/ai/skills/marimo-pair/SKILL.md@@ -0,0 +1,263 @@+---+name: marimo-pair+description: >-+ Work inside the user's live marimo notebook from the code editor: run Python+ in the same kernel the user does, inspect live notebook state, and commit+ durable notebook changes through code mode. Use whenever you create, analyze,+ or improve the user's marimo notebook.+---++marimo is a reactive Python runtime for building reproducible Python programs+(marimo notebooks). Cells are connected by the variables they define and+reference. Running a cell re-executes dependents in dataflow order. The active+runtime holds the kernel namespace, cell state, and dataflow graph. The+notebook (`.py` file) is the artifact the kernel writes from that state while a+session is running.++A user interacts with the same runtime via a notebook UI with cells, outputs,+and widgets.++**WARNING. The active runtime is the source of truth.** You are working inside+the user's live notebook session. The kernel — not the `.py` file on disk —+holds the truth about cells, variables, and the dataflow graph. Make every+notebook change through `marimo._code_mode` (`cm`); direct file edits WILL NOT+reach the live kernel or user, and the kernel may overwrite them on save.+Reading disk is fine, but prefer `ctx.cells[...].code` for current cell code.++**WARNING. Every notebook edit goes through code mode — no exceptions.** When+the user asks you to change the notebook (add, edit, delete, or run a cell;+rename; change a value or a package), you MUST make that change through+`marimo._code_mode` (`cm`) by running it with the `execute_code` tool. There is+no separate file-editing path — `execute_code` + `cm` is the only way to reach+the user's running session. Running ad-hoc Python with `execute_code` to+explore or test is fine; _persisting any change to the notebook_ is only ever+done via `cm`.++## Running Code in the Kernel++You are already attached to the user's running notebook — there is nothing to+connect to or start. Use the `execute_code` tool to run Python in that kernel,+passing your Python as the `code` argument. Everything you do — inspecting+state, testing transformations, and persisting changes via `cm` — runs through+`execute_code` in the scratchpad (see below).++## Scratchpad Scope++`execute_code` evaluates Python in marimo's scratchpad: a temporary namespace+with a shallow copy of the kernel globals. Notebook variables are available by+name, but new top-level bindings and rebindings are discarded after each call.+In-place mutations to notebook-owned objects can persist because those names+still reference live objects.++Each call reports stdout and stderr from the scratchpad, plus console output+from notebook cells it causes to run, including reactive descendants.++### Ordinary Python++Use ordinary Python in the scratchpad to inspect variables, sample data, test+transformations, probe APIs, check imports, and read widget state.++```python+print(df.head())++x = 10+print(x)+```++Here `df` comes from notebook globals, while `x` is a scratchpad-local binding.+`x` exists for this call only and WILL NOT be added to notebook globals.++### Persist with `cm`++Top-level scratchpad assignments and rebindings are temporary. To persist work,+including new variables, you MUST submit changes through `marimo._code_mode`+(`cm`).++`marimo._code_mode` is a PRIVATE, UNSTABLE agent API (note the leading+underscore). It exists for tools like this skill to drive a live kernel from+the scratchpad. DO NOT import it from notebook cells, library code, or+anything a user would run — methods can change or disappear across marimo+versions and kernels. Treat every `import marimo._code_mode as cm` as+scratchpad-only.++At session start, inspect what `cm` exposes in the active kernel:++```python+import marimo._code_mode as cm++help(cm)+```++Open a code-mode context to queue notebook changes.++```python+import marimo._code_mode as cm++async with cm.get_context() as ctx:+ cid = ctx.create_cell("x = df.head()")+ ctx.run_cell(cid)+```++The scratchpad supports top-level async code. Use `async with` directly;+wrapping it in `asyncio.run(...)` is unnecessary and can conflict with the+kernel's event loop.++After this block exits and the new cell runs, `x` is notebook state. Later+scratchpad calls can read `x` by name. Code later in the same scratchpad call+should read `ctx.globals["x"]`, because the scratchpad namespace was copied+before the cell ran.++Inside the context, queued mutation methods are synchronous. Call them+directly; do not `await` them. Each call queues an operation for marimo to+apply when the context exits normally. If the block raises, the queue is+discarded.++On clean exit, marimo applies packages, validates and applies structural cell+changes, runs queued cells, then may run dependents. Validation is only+structural since queued cell runs can still error. `create_cell` and+`edit_cell` change notebook structure only. Use `run_cell` to execute.++`create_cell` currently defaults to `hide_code=True`, which collapses the code+editor in the UI. Pass `hide_code=False` if the user wants created cells to+be visible without manually expanding them.++## Marimo Rules++marimo imposes a small contract on notebook code so it can keep the notebook as+a directed acyclic graph (DAG):++- **No cycles** - cells cannot depend on each other in a cycle.+- **No public redefinitions across cells** - each name has one owning cell.+- **No wildcard imports** - `import *` prevents static analysis of definitions.++These rules keep the kernel, UI, and saved artifact consistent.++When `cm` submits a cell body, marimo parses its top-level definitions and+references. A top-level name enters the graph unless it is private with a+leading underscore.++```python+# Public definitions: values, total, i, value, mean+values = np.array([1, 2, 3])+total = 0+for i, value in enumerate(values):+ total += value+mean = total / len(values)+mean+```++```python+# Public definition: mean+_values = np.array([1, 2, 3])+_total = 0+for _i, _value in enumerate(_values):+ _total += _value+mean = _total / len(_values)+mean+```++Use private names for intermediates that no other cell should read. Public+names define the notebook-level dataflow. If a `cm` edit violates the contract,+marimo rejects the structural change and returns the validation error.++## The Notebook's Shape++A notebook is an ordered collection of cells. `ctx.cells` is the document view+and `ctx.graph` is the dataflow view.++```python+for cell in ctx.cells:+ cell # .id, .code, .name, .config, .status, .errors++ctx.cells["setup"] # by name+ctx.cells[0] # by position+list(ctx.cells.keys()) # all IDs, in notebook order+```++Cell IDs are opaque strings which can be queried from the notebook or captured+from `cm` return values:++```python+cid = ctx.create_cell("df = pd.read_csv('data.csv')")+print(cid) # e.g. 'Hbol'+```++Alternatively, cells can be assigned and referenced by `name`. The graph can be+used to understand its role in the dataflow.++```python+for cid, impl in ctx.graph.cells.items():+ impl # .defs, .refs (sets of public names)++ctx.graph.descendants(cid) # cells that re-run when this one changes+ctx.graph.ancestors(cid) # cells this one depends on+```++In marimo, deletes are _destructive_ so it can be useful to query the+descendants prior to deleting to understand it's impact.++## Writing Notebook Changes++The graph contract keeps marimo able to run and save the notebook. Passing+those checks alone does not guarantee a useful artifact. Committed cells should+still be readable, rerunnable, and editable.++Make durable edits that reuse the notebook's existing names, imports,+dependencies, and UI model. Don't be lazy. Avoid one-off workarounds that pass+`cm` validation but leave a brittle notebook.++### Cell Bodies++Submit the code that belongs in the cell.++- **Submit cell contents** - `create_cell` and `edit_cell` take cell contents,+ not saved-file `@app.cell` wrappers.+- **Read before replacing** - for now, another editor may change a cell between+ scratchpad calls. Before `edit_cell`, read the current body from+ `ctx.cells[...]` and submit the full replacement.+- **Reuse notebook imports** - if `np` already exists, use it or edit the owning+ import cell. DO NOT add `import numpy as _np` just to bypass the graph.+- **Define public names intentionally** - use public names for values later+ cells should reference. Use private `_name` bindings or function locals for+ same-cell intermediates.+- **Define each public name once** - a public name has one owning cell.+ Reassigning it in another cell fails with `Multiply-defined names`; edit the+ owning cell or give the result a new name. See+ [gotchas.md](references/gotchas.md).+- **Run cells deliberately** - `create_cell` and `edit_cell` change structure+ only. Queue `ctx.run_cell(...)` when the cell should execute.++### Prefer `cm`-Managed Changes++Use `cm` APIs when they exist. Avoid direct file edits, shell package commands,+and scratchpad-only state for changes that should persist.++- **Persist only through `cm`** - never try to change the notebook by writing+ the `.py` file; `execute_code` + `cm` is the only path that reaches the live+ session. Use `ctx.edit_cell(...)` even for small changes.+- **Manage packages through `cm`** - use `ctx.packages.add()` or+ `ctx.packages.remove()` instead of direct `uv` or `pip`; confirm+ non-obvious dependency changes.+- **Avoid transient paths** - persisted cells should not depend on `/tmp/...`+ unless the work is intentionally transient.+- **Delete deliberately** - deleting a cell removes globals it defines. Reuse+ empty cells when convenient and delete cells left empty after edits.++### UI and Widgets++Inspect the object before changing it. Different UI objects update through+different paths.++- **Set `mo.ui.*` through `cm`** - use `ctx.set_ui_value(element, value)` inside+ `cm.get_context()`.+- **Set anywidget traitlets directly** - synced traitlets are Python+ attributes, for example `widget.value = 5`.++For designing custom visual or interactive output, see+[rich-representations.md](references/rich-representations.md).++## References++- [gotchas.md](references/gotchas.md) — name redefinition, cached module proxies, and notebook traps+- [rich-representations.md](references/rich-representations.md) — custom widgets and visualizations+- [notebook-improvements.md](references/notebook-improvements.md) — improving existing notebooksdiff --git a/marimo/_server/ai/skills/utils.py b/marimo/_server/ai/skills/utils.pynew file mode 100644index 0000000000..c2d86808f9--- /dev/null+++ b/marimo/_server/ai/skills/utils.py@@ -0,0 +1,15 @@+# Copyright 2026 Marimo. All rights reserved.++import functools+from pathlib import Path+from typing import Literal++SKILL_NAMES: list[str] = ["marimo-pair"]++[email protected]_cache(maxsize=1)+def load_skill(skill_name: Literal["marimo-pair"]) -> str:+ """Read the bundled skill SKILL.md once and cache it."""+ return (Path(__file__).parent / skill_name / "SKILL.md").read_text(+ encoding="utf-8"+ )diff --git a/marimo/_server/api/endpoints/ai.py b/marimo/_server/api/endpoints/ai.pyindex 51a1a0dd5c..300f1872b0 100644--- a/marimo/_server/api/endpoints/ai.py+++ b/marimo/_server/api/endpoints/ai.py@@ -13,7 +13,7 @@ from starlette.responses import (from marimo import _loggersfrom marimo._ai._pydantic_ai_utils import create_simple_prompt, generate_id-from marimo._config.config import AiConfig, MarimoConfig+from marimo._config.config import AiConfig, CopilotMode, MarimoConfigfrom marimo._server.ai.config import (AnyProviderConfig,get_autocomplete_model,@@ -183,7 +183,7 @@ async def ai_chat($ref: "#/components/schemas/ChatRequest""""app_state = AppState(request)- app_state.require_current_session()+ session = app_state.require_current_session()session_id = app_state.require_current_session_id()accept = request.headers.get("accept", SSE_CONTENT_TYPE)config = app_state.app_config_manager.get_config(hide_secrets=False)@@ -193,12 +193,12 @@ async def ai_chat(ai_config = get_ai_config(config)custom_rules = ai_config.get("rules", None)- # Get the system prompt+ mode: CopilotMode = ai_config.get("mode", "manual")system_prompt = get_chat_system_prompt(custom_rules=custom_rules,context=body.context,include_other_code=body.include_other_code,- mode=ai_config.get("mode", "manual"),+ mode=mode,session_id=session_id,)@@ -215,6 +215,16 @@ async def ai_chat(format_stream=True, text_only=False, accept=accept)+ if mode == "code_mode":+ return await provider.stream_completion_harness(+ messages=body.ui_messages,+ system_prompt=system_prompt,+ session=session,+ request=request,+ max_tokens=max_tokens,+ stream_options=stream_options,+ )+return await provider.stream_completion(messages=body.ui_messages,system_prompt=system_prompt,diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex e95b64a7c3..47b24c0b1f 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -134,6 +134,7 @@ components:enum:- agent- ask+ - code_mode- manualmodels:$ref: '#/components/schemas/AiModelConfig'@@ -5257,6 +5258,7 @@ components:enum:- agent- ask+ - code_mode- manualtype: arrayname:diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.tsindex 71332372e6..035f4cb7ad 100644--- a/packages/openapi/src/api.ts+++ b/packages/openapi/src/api.ts@@ -3463,7 +3463,7 @@ export interface components {inline_tooltip?: boolean;max_tokens?: number;/** @enum {unknown} */- mode?: "agent" | "ask" | "manual";+ mode?: "agent" | "ask" | "code_mode" | "manual";models?: components["schemas"]["AiModelConfig"];ollama?: components["schemas"]["OpenAiConfig"];open_ai?: components["schemas"]["OpenAiConfig"];@@ -6621,7 +6621,7 @@ export interface components {*/ToolDefinition: {description: string;- mode: ("agent" | "ask" | "manual")[];+ mode: ("agent" | "ask" | "code_mode" | "manual")[];name: string;parameters: Record<string, any>;/** @enum {unknown} */diff --git a/tests/_server/ai/skills/test_skills_utils.py b/tests/_server/ai/skills/test_skills_utils.pynew file mode 100644index 0000000000..4464e5b46e--- /dev/null+++ b/tests/_server/ai/skills/test_skills_utils.py@@ -0,0 +1,21 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from marimo._server.ai.skills.utils import SKILL_NAMES, load_skill+++def test_load_skill_returns_skill_contents() -> None:+ content = load_skill("marimo-pair")+ assert content.strip()+ # The bundled skill carries its frontmatter name.+ assert "name: marimo-pair" in content+++def test_load_skill_is_cached() -> None:+ # lru_cache returns the identical object on repeated calls.+ assert load_skill("marimo-pair") is load_skill("marimo-pair")+++def test_all_declared_skills_are_loadable() -> None:+ for skill_name in SKILL_NAMES:+ assert load_skill(skill_name).strip()diff --git a/tests/_server/ai/test_prompts.py b/tests/_server/ai/test_prompts.pyindex c03a824e85..3be1bdd043 100644--- a/tests/_server/ai/test_prompts.py+++ b/tests/_server/ai/test_prompts.py@@ -3,15 +3,22 @@ from __future__ import annotationsfrom typing import cast+import pytest+from marimo._ast.visitor import Language+from marimo._config.config import CopilotModefrom marimo._server.ai.prompts import (FIM_SUFFIX_TAG,+ _common_chat_sections,_format_plain_text,+ _format_schema_info,_format_variables,+ _get_mode_intro_message,get_chat_system_prompt,get_inline_system_prompt,get_refactor_or_insert_notebook_cell_system_prompt,)+from marimo._server.ai.skills.utils import load_skillfrom marimo._server.models.completion import (AiCompletionContext,SchemaColumn,@@ -440,3 +447,129 @@ def test_format_plain_text():_format_plain_text("Hello, world!")== "If the prompt mentions @kind://name, use the following context to help you answer the question:\n\nHello, world!")+++def test_format_schema_info():+ assert _format_schema_info(None) == ""+ assert _format_schema_info([]) == ""++ result = _format_schema_info(+ [+ SchemaTable(+ name="df_1",+ columns=[+ SchemaColumn("age", "int", sample_values=["1", "2"]),+ SchemaColumn("name", "str", sample_values=[]),+ ],+ )+ ]+ )+ assert "## Available schema:" in result+ assert "- Table: df_1" in result+ assert "- Column: age" in result+ assert "- Type: int" in result+ assert "- Sample values: 1, 2" in result+ # Column without sample values omits the sample line+ assert "- Column: name" in result+ assert "Sample values: \n" not in result++[email protected]("mode", ["manual", "ask", "agent", "code_mode"])+def test_mode_intro_messages_share_base(mode: CopilotMode):+ message = _get_mode_intro_message(mode)+ assert "You are Marimo Copilot" in message+ assert "reactive programming model" in message+++def test_common_chat_sections_empty():+ assert (+ _common_chat_sections(+ custom_rules=None, include_other_code="", context=None+ )+ == ""+ )+ # Whitespace-only custom rules are treated as empty.+ assert (+ _common_chat_sections(+ custom_rules=" ", include_other_code="", context=None+ )+ == ""+ )+++def test_common_chat_sections_full():+ result = _common_chat_sections(+ custom_rules="Be concise.",+ include_other_code="import polars as pl",+ context=AiCompletionContext(variables=["var1"]),+ )+ assert "## Additional rules:\nBe concise." in result+ assert "<code_from_other_cells>" in result+ assert "import polars as pl" in result+ assert "## Available variables from other cells:" in result+++def test_chat_system_prompt_code_mode():+ prompt = get_chat_system_prompt(+ custom_rules=None,+ include_other_code="",+ context=None,+ mode="code_mode",+ session_id=SessionId("s_test"),+ )+ # Code mode uses its own intro and embeds the marimo-pair skill.+ assert _get_mode_intro_message("code_mode") in prompt+ assert "how to work with marimo" in prompt+ assert load_skill("marimo-pair") in prompt+ # Code mode includes single-cell language rules.+ assert "## Rules for python:" in prompt+++def test_chat_system_prompt_code_mode_includes_extras():+ prompt = get_chat_system_prompt(+ custom_rules="Always be polite.",+ include_other_code="import pandas as pd\n",+ context=AiCompletionContext(variables=["var1", "var2"]),+ mode="code_mode",+ session_id=SessionId("s_test"),+ )+ assert "## Additional rules:\nAlways be polite." in prompt+ assert "<code_from_other_cells>" in prompt+ assert "import pandas as pd" in prompt+ assert "## Available variables from other cells:" in prompt+++def test_chat_system_prompt_non_code_mode_includes_session_info():+ for mode in ("manual", "ask", "agent"):+ prompt = get_chat_system_prompt(+ custom_rules=None,+ include_other_code="",+ context=None,+ mode=cast(CopilotMode, mode),+ session_id=SessionId("s_abc"),+ )+ assert "Current notebook session ID: s_abc" in prompt+ assert "Your goal is to do one of the following two things" in prompt+ # The marimo-pair skill is only embedded in code mode.+ assert "how to work with marimo notebooks" not in prompt+++def test_chat_system_prompt_agent_mode_inserts_cell_rules():+ agent_prompt = get_chat_system_prompt(+ custom_rules=None,+ include_other_code="",+ context=None,+ mode="agent",+ session_id=SessionId("s_test"),+ )+ manual_prompt = get_chat_system_prompt(+ custom_rules=None,+ include_other_code="",+ context=None,+ mode="manual",+ session_id=SessionId("s_test"),+ )+ # Agent mode adds guidance for inserting cells; manual mode does not.+ assert "## Rules for inserting cells:" in agent_prompt+ assert 'mo.md(f"""{content}""")' in agent_prompt+ assert "## Rules for inserting cells:" not in manual_promptdiff --git a/tests/_server/ai/test_providers.py b/tests/_server/ai/test_providers.pyindex d7e238a9c7..5ca88d3067 100644--- a/tests/_server/ai/test_providers.py+++ b/tests/_server/ai/test_providers.py@@ -666,3 +666,52 @@ def test_custom_provider_known_name_not_overridden_by_base_url() -> None:AiModelId.from_model("openrouter/some-model"), config)assert provider._provider_name == "openrouter"++[email protected]("pydantic_ai")+async def test_stream_completion_harness_wires_execute_code_toolset() -> None:+ """The code-mode harness builds an agent with the execute_code toolset,+ passes the system prompt as instructions, and returns the adapter's+ streaming response."""+ config = AnyProviderConfig(api_key="test-key", base_url="http://test-url")+ provider = OpenAIProvider("gpt-4", config)++ session = MagicMock(name="session")+ request = MagicMock(name="request")+ toolset = MagicMock(name="toolset")+ streaming_response = MagicMock(name="streaming_response")+ adapter: MagicMock = MagicMock(name="adapter")+ adapter.streaming_response = MagicMock(return_value=streaming_response)++ with (+ patch.object(provider, "create_model", return_value=MagicMock()),+ patch.object(provider, "_build_agent_settings", return_value={}),+ patch.object(provider, "convert_messages", return_value=[]),+ patch(+ "marimo._server.ai.tools.code_mode.build_execute_code_toolset",+ return_value=toolset,+ ) as mock_build_toolset,+ patch("pydantic_ai.Agent") as mock_agent,+ patch(+ "pydantic_ai.ui.vercel_ai.VercelAIAdapter",+ return_value=adapter,+ ),+ ):+ result = await provider.stream_completion_harness(+ messages=[],+ system_prompt="SYSTEM PROMPT WITH SKILL",+ session=session,+ request=request,+ max_tokens=1234,+ stream_options=None,+ )++ assert result is streaming_response+ # The toolset is bound to the caller's session and request.+ mock_build_toolset.assert_called_once_with(session, request)++ # The agent is constructed with that toolset and the system prompt as+ # instructions (which now carries the marimo-pair skill).+ agent_kwargs = mock_agent.call_args.kwargs+ assert agent_kwargs["toolsets"] == [toolset]+ assert agent_kwargs["instructions"] == "SYSTEM PROMPT WITH SKILL"diff --git a/tests/_server/ai/tools/test_code_mode.py b/tests/_server/ai/tools/test_code_mode.pynew file mode 100644index 0000000000..be1b3dd430--- /dev/null+++ b/tests/_server/ai/tools/test_code_mode.py@@ -0,0 +1,64 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from collections.abc import Awaitable, Callable+from typing import cast+from unittest.mock import AsyncMock, MagicMock, patch++import pytest++[email protected]("pydantic_ai")+def test_build_execute_code_toolset_exposes_single_execute_code_tool() -> None:+ from marimo._server.ai.tools.code_mode import build_execute_code_toolset++ toolset = build_execute_code_toolset(MagicMock(), MagicMock())++ assert list(toolset.tools.keys()) == ["execute_code"]+ tool = toolset.tools["execute_code"]+ # The model is told how to use the tool via its description.+ assert tool.description+ assert "scratchpad" in tool.description++[email protected]("pydantic_ai")+async def test_execute_code_tool_routes_to_scratchpad_with_credentials() -> (+ None+):+ from marimo._server.ai.tools.code_mode import build_execute_code_toolset++ session = MagicMock()+ request = MagicMock()+ sentinel_result = MagicMock(name="CodeExecutionResult")++ with (+ patch(+ "marimo._server.ai.tools.code_mode.get_code_mode_credentials",+ return_value=("http://localhost:2718", "secret-token"),+ ) as mock_creds,+ patch(+ "marimo._server.ai.tools.code_mode.run_scratchpad_code",+ new_callable=AsyncMock,+ return_value=sentinel_result,+ ) as mock_run,+ patch("marimo._server.ai.tools.code_mode.AppState") as mock_app_state,+ ):+ app_state_instance = cast(MagicMock, mock_app_state.return_value)+ toolset = build_execute_code_toolset(session, request)+ execute_code = cast(+ Callable[[str], Awaitable[object]],+ toolset.tools["execute_code"].function,+ )++ result = await execute_code("print('hi')")++ assert result is sentinel_result+ # Credentials are derived from the bound request, not model input.+ mock_creds.assert_called_once_with(app_state_instance, request)+ mock_run.assert_awaited_once_with(+ session,+ request,+ code="print('hi')",+ server_url="http://localhost:2718",+ auth_token="secret-token",+ )diff --git a/tests/_server/api/endpoints/test_ai.py b/tests/_server/api/endpoints/test_ai.pyindex 6ecf68f16b..d6c787a153 100644--- a/tests/_server/api/endpoints/test_ai.py+++ b/tests/_server/api/endpoints/test_ai.py@@ -555,7 +555,7 @@ class TestGoogleAiEndpoints:)-def _openai_config():+def _openai_config() -> dict[str, Any]:return {"ai": {"open_ai": {@@ -727,6 +727,66 @@ def test_chat_with_code(mock_stream_completion.assert_called_once()+def _openai_config_code_mode() -> dict[str, Any]:+ config: dict[str, Any] = _openai_config()+ config["ai"]["mode"] = "code_mode"+ return config++[email protected]("openai", "pydantic_ai")+@with_session(SESSION_ID)+@patch("marimo._server.ai.providers.OpenAIProvider.stream_completion")+@patch("marimo._server.ai.providers.OpenAIProvider.stream_completion_harness")+def test_chat_code_mode_routes_to_harness(+ client: TestClient,+ mock_harness: MagicMock,+ mock_stream_completion: MagicMock,+) -> None:+ """In code mode the chat endpoint routes to the code-mode harness+ (which can execute code) instead of the plain completion stream."""+ user_config_manager = get_session_config_manager(client)++ from starlette.responses import StreamingResponse++ async def mock_stream():+ yield b"done"++ mock_harness.return_value = StreamingResponse(+ content=mock_stream(),+ media_type="text/event-stream",+ )++ with patch.object(+ user_config_manager,+ "get_config",+ return_value=_openai_config_code_mode(),+ ):+ response = client.post(+ "/api/ai/chat",+ headers=HEADERS,+ json={+ "messages": _create_messages("Add a cell"),+ "uiMessages": _create_messages("Add a cell"),+ "model": "gpt-4-turbo",+ "variables": [],+ "includeOtherCode": "",+ "context": {},+ "id": "123",+ },+ )++ assert response.status_code == 200, response.text+ mock_harness.assert_called_once()+ mock_stream_completion.assert_not_called()++ # The harness receives the live session and the assembled system prompt+ # (which embeds the marimo-pair skill; building it also exercises the+ # skill-loading path).+ kwargs = mock_harness.call_args.kwargs+ assert kwargs["session"] is not None+ assert "how to work with marimo" in kwargs["system_prompt"]++# Tool invocation tests (provider-agnostic)class TestInvokeToolEndpoint:"""Tests for the /invoke_tool endpoint."""