Skip to content

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.

feat: add GetCellOutputs tool and get_llm_context for all UIElement classes (#6889)

Joaquin Coromina4eb45faabbdd
diff --git a/marimo/_ai/_tools/tools/cells.py b/marimo/_ai/_tools/tools/cells.py
index af6a05efb9..f812cd20e6 100644
--- a/marimo/_ai/_tools/tools/cells.py
+++ b/marimo/_ai/_tools/tools/cells.py
@@ -3,13 +3,16 @@ from __future__ import annotations
from dataclasses import dataclass, field
from enum import Enum
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Any, Optional
from marimo._ai._tools.base import ToolBase
from marimo._ai._tools.types import SuccessResult, ToolGuidelines
from marimo._ai._tools.utils.exceptions import ToolExecutionError
+from marimo._ai._tools.utils.output_cleaning import clean_output
from marimo._ast.models import CellData
-from marimo._messaging.ops import VariableValue
+from marimo._messaging.cell_output import CellChannel
+from marimo._messaging.errors import Error
+from marimo._messaging.ops import CellOp, VariableValue
from marimo._types.ids import CellId_t, SessionId
if TYPE_CHECKING:
@@ -98,6 +101,27 @@ class GetCellRuntimeDataOutput(SuccessResult):
)
+@dataclass
+class CellOutputData:
+ """Visual and console output from a cell execution."""
+
+ visual_output: Optional[str] = None
+ visual_mimetype: Optional[str] = None
+ stdout: list[str] = field(default_factory=list)
+ stderr: list[str] = field(default_factory=list)
+
+
+@dataclass
+class GetCellOutputArgs:
+ session_id: SessionId
+ cell_id: CellId_t
+
+
+@dataclass
+class GetCellOutputOutput(SuccessResult):
+ data: CellOutputData = field(default_factory=CellOutputData)
+
+
class GetLightweightCellMap(
ToolBase[GetLightweightCellMapArgs, GetLightweightCellMapOutput]
):
@@ -397,3 +421,99 @@ class GetCellRuntimeData(
cell_variables[var_name] = var_value
return cell_variables
+
+
+class GetCellOutputs(ToolBase[GetCellOutputArgs, GetCellOutputOutput]):
+ """Get cell execution output including visual display and console streams.
+
+ Returns comprehensive output data for a single cell:
+ - Visual output (HTML, charts, tables, etc.) with mimetype
+ - Console stdout and stderr messages
+
+ Args:
+ session_id: The session ID of the notebook from get_active_notebooks
+ cell_id: The specific cell ID from get_lightweight_cell_map
+
+ Returns:
+ A success result containing all output data from the cell execution.
+ """
+
+ guidelines = ToolGuidelines(
+ when_to_use=[
+ "When you need to see what a cell displayed or printed to the user",
+ "To review charts, visualizations, markdown, HTML, or console output from a cell",
+ ],
+ prerequisites=[
+ "You must have a valid session id from an active notebook",
+ "You must have a valid cell id from an active notebook",
+ ],
+ )
+
+ def handle(self, args: GetCellOutputArgs) -> GetCellOutputOutput:
+ session = self.context.get_session(args.session_id)
+ session_view = session.session_view
+ cell_id = args.cell_id
+ maybe_cell_op = session_view.cell_operations.get(cell_id)
+
+ visual_output, visual_mimetype = self._get_visual_output(maybe_cell_op)
+ stdout_messages, stderr_messages = self._get_console_outputs(
+ maybe_cell_op
+ )
+
+ return GetCellOutputOutput(
+ data=CellOutputData(
+ visual_output=visual_output,
+ visual_mimetype=visual_mimetype,
+ stdout=stdout_messages,
+ stderr=stderr_messages,
+ ),
+ next_steps=[
+ "Review visual_output to see what was displayed to the user",
+ "Check stdout/stderr for print statements and warnings",
+ ],
+ )
+
+ def _get_visual_output(
+ self, maybe_cell_op: Optional[CellOp]
+ ) -> tuple[Optional[str], Optional[str]]:
+ visual_output = None
+ visual_mimetype = None
+ if maybe_cell_op and maybe_cell_op.output:
+ data = maybe_cell_op.output.data
+ visual_output = self._get_str_output_data(data)
+ visual_mimetype = maybe_cell_op.output.mimetype
+ return visual_output, visual_mimetype
+
+ def _get_str_output_data(
+ self, data: str | list[Error] | dict[str, Any]
+ ) -> str:
+ if isinstance(data, str):
+ return data
+ else:
+ return str(data)
+
+ def _get_console_outputs(
+ self, maybe_cell_op: Optional[CellOp]
+ ) -> tuple[list[str], list[str]]:
+ stdout_messages: list[str] = []
+ stderr_messages: list[str] = []
+ if maybe_cell_op is None or maybe_cell_op.console is None:
+ return stdout_messages, stderr_messages
+
+ console_outputs = (
+ maybe_cell_op.console
+ if isinstance(maybe_cell_op.console, list)
+ else [maybe_cell_op.console]
+ )
+ for output in console_outputs:
+ if output is None:
+ continue
+ elif output.channel == CellChannel.STDOUT:
+ stdout_messages.append(str(output.data))
+ elif output.channel == CellChannel.STDERR:
+ stderr_messages.append(str(output.data))
+
+ cleaned_stdout_messages = clean_output(stdout_messages)
+ cleaned_stderr_messages = clean_output(stderr_messages)
+
+ return cleaned_stdout_messages, cleaned_stderr_messages
diff --git a/marimo/_ai/_tools/tools_registry.py b/marimo/_ai/_tools/tools_registry.py
index e30fd4d5ae..f71c3b6de4 100644
--- a/marimo/_ai/_tools/tools_registry.py
+++ b/marimo/_ai/_tools/tools_registry.py
@@ -5,6 +5,7 @@ from typing import Any
from marimo._ai._tools.base import ToolBase
from marimo._ai._tools.tools.cells import (
+ GetCellOutputs,
GetCellRuntimeData,
GetLightweightCellMap,
)
@@ -19,6 +20,7 @@ SUPPORTED_BACKEND_AND_MCP_TOOLS: list[type[ToolBase[Any, Any]]] = [
GetMarimoRules,
GetActiveNotebooks,
GetCellRuntimeData,
+ GetCellOutputs,
GetLightweightCellMap,
GetTablesAndVariables,
GetDatabaseTables,
diff --git a/marimo/_ai/_tools/utils/output_cleaning.py b/marimo/_ai/_tools/utils/output_cleaning.py
new file mode 100644
index 0000000000..b3ebb40c15
--- /dev/null
+++ b/marimo/_ai/_tools/utils/output_cleaning.py
@@ -0,0 +1,93 @@
+# Copyright 2025 Marimo. All rights reserved.
+
+from __future__ import annotations
+
+import re
+
+
+def clean_output(lines: list[str]) -> list[str]:
+ """Clean console output for LLM consumption."""
+ lines = normalize_progress_bars(lines)
+ lines = deduplicate_lines(lines)
+ lines = strip_ansi_codes(lines)
+ lines = truncate_output(lines)
+ return lines
+
+
+def strip_ansi_codes(lines: list[str]) -> list[str]:
+ """Remove ANSI escape sequences (colors, formatting) from text.
+
+ ANSI codes are used for terminal styling (colors, bold, cursor movement,
+ etc.) from libraries like rich, pytest, click, tqdm, colorama. These are
+ meaningless to LLMs and add noise to the output.
+ """
+ # Based on a widely cited Stack Overflow answer:
+ # https://stackoverflow.com/questions/14693701/how-can-i-remove-the-ansi-escape-sequences-from-a-string-in-python
+ # Covers all 7-bit ANSI C1 escape sequences.
+ ansi_pattern = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+ return [ansi_pattern.sub("", line) for line in lines]
+
+
+def deduplicate_lines(lines: list[str]) -> list[str]:
+ """Remove consecutive duplicate lines, replacing with a summary message.
+
+ Useful for cleaning repetitive training logs, warnings, and batch processing output.
+ """
+ if len(lines) <= 1:
+ return lines
+
+ deduped_lines: list[str] = []
+ prev_line = lines[0]
+ repeat_count = 1
+
+ for line in lines[1:]:
+ if line == prev_line:
+ repeat_count += 1
+ continue
+ # Flush previous group
+ deduped_lines.append(prev_line)
+ if repeat_count > 1:
+ deduped_lines.append(f"(repeated {repeat_count} times)")
+
+ # Start new group
+ prev_line = line
+ repeat_count = 1
+
+ # Handle last group
+ deduped_lines.append(prev_line)
+ if repeat_count > 1:
+ deduped_lines.append(f"(repeated {repeat_count} times)")
+
+ return deduped_lines
+
+
+def normalize_progress_bars(lines: list[str]) -> list[str]:
+ """Collapse carriage return sequences to show only final state.
+
+ Progress bars from tqdm, pandas.progress_apply(), dask, and Spark use
+ carriage returns to overwrite the same line repeatedly. This keeps only
+ the final state and removes empty lines.
+ """
+ normalized_lines: list[str] = []
+ for line in lines:
+ if "\r" in line:
+ line = line.split("\r")[-1]
+ if line.strip():
+ normalized_lines.append(line)
+ return normalized_lines
+
+
+def truncate_output(lines: list[str], max_lines: int = 500) -> list[str]:
+ """Keep first and last portions of output, truncating the middle."""
+ if len(lines) <= max_lines:
+ return lines
+
+ keep_head = max_lines // 2
+ keep_tail = max_lines - keep_head
+ removed = len(lines) - max_lines
+
+ return (
+ lines[:keep_head]
+ + [f"... [truncated {removed} lines] ..."]
+ + lines[-keep_tail:]
+ )
diff --git a/tests/_ai/tools/tools/test_cells.py b/tests/_ai/tools/tools/test_cells.py
index 4d1b6a3fa0..638c7f4fec 100644
--- a/tests/_ai/tools/tools/test_cells.py
+++ b/tests/_ai/tools/tools/test_cells.py
@@ -10,6 +10,7 @@ from marimo._ai._tools.tools.cells import (
CellErrors,
CellRuntimeMetadata,
CellVariables,
+ GetCellOutputs,
GetCellRuntimeData,
GetLightweightCellMap,
)
@@ -28,8 +29,9 @@ class MockCellOp:
@dataclass
class MockOutput:
- channel: object
- data: object
+ channel: object = None
+ data: object = None
+ mimetype: object = None
@dataclass
@@ -116,7 +118,7 @@ def test_get_cell_errors_dict_error():
cell_op = MockCellOp(output=output)
session = MockSession(MockSessionView(cell_operations={"c1": cell_op}))
- result = tool._get_cell_errors(session, "c1")
+ result = tool._get_cell_errors(session, CellId_t("c1"))
assert result.has_errors is True
assert result.error_details is not None
assert result.error_details[0].type == "ValueError"
@@ -218,3 +220,44 @@ def test_get_cell_runtime_data_invalid_cell():
with pytest.raises(ToolExecutionError) as exc_info:
tool.handle(args)
assert exc_info.value.code == "CELL_NOT_FOUND"
+
+
+def test_get_visual_output_with_html():
+ tool = GetCellOutputs(ToolContext())
+ output = MockOutput(data="<div>test</div>", mimetype="text/html")
+ cell_op = MockCellOp(output=output)
+
+ visual_output, mimetype = tool._get_visual_output(cell_op) # type: ignore[arg-type]
+ assert visual_output == "<div>test</div>"
+ assert mimetype == "text/html"
+
+
+def test_get_visual_output_no_output():
+ tool = GetCellOutputs(ToolContext())
+ cell_op = MockCellOp(output=None)
+
+ visual_output, mimetype = tool._get_visual_output(cell_op) # type: ignore[arg-type]
+ assert visual_output is None
+ assert mimetype is None
+
+
+def test_get_console_outputs_with_stdout_stderr():
+ tool = GetCellOutputs(ToolContext())
+ console = [
+ MockConsoleOutput(CellChannel.STDOUT, "hello"),
+ MockConsoleOutput(CellChannel.STDERR, "warning"),
+ ]
+ cell_op = MockCellOp(console=console)
+
+ stdout, stderr = tool._get_console_outputs(cell_op) # type: ignore[arg-type]
+ assert stdout == ["hello"]
+ assert stderr == ["warning"]
+
+
+def test_get_console_outputs_no_console():
+ tool = GetCellOutputs(ToolContext())
+ cell_op = MockCellOp(console=None)
+
+ stdout, stderr = tool._get_console_outputs(cell_op) # type: ignore[arg-type]
+ assert stdout == []
+ assert stderr == []
diff --git a/tests/_ai/tools/utils/test_output_cleaning.py b/tests/_ai/tools/utils/test_output_cleaning.py
new file mode 100644
index 0000000000..f7414a0ceb
--- /dev/null
+++ b/tests/_ai/tools/utils/test_output_cleaning.py
@@ -0,0 +1,193 @@
+# Copyright 2025 Marimo. All rights reserved.
+from __future__ import annotations
+
+from marimo._ai._tools.utils.output_cleaning import (
+ clean_output,
+ deduplicate_lines,
+ normalize_progress_bars,
+ strip_ansi_codes,
+ truncate_output,
+)
+
+
+class TestStripAnsiCodes:
+ def test_removes_color_codes(self) -> None:
+ lines = ["\x1b[31mError\x1b[0m", "\x1b[32mSuccess\x1b[0m"]
+ result = strip_ansi_codes(lines)
+ assert result == ["Error", "Success"]
+
+ def test_removes_bold_codes(self) -> None:
+ lines = ["\x1b[1mBold text\x1b[0m"]
+ result = strip_ansi_codes(lines)
+ assert result == ["Bold text"]
+
+ def test_removes_cursor_movement(self) -> None:
+ lines = ["\x1b[2JCleared\x1b[H"]
+ result = strip_ansi_codes(lines)
+ assert result == ["Cleared"]
+
+ def test_handles_no_ansi_codes(self) -> None:
+ lines = ["Plain text", "No codes here"]
+ result = strip_ansi_codes(lines)
+ assert result == ["Plain text", "No codes here"]
+
+ def test_empty_list(self) -> None:
+ assert strip_ansi_codes([]) == []
+
+
+class TestDeduplicateLines:
+ def test_single_line(self) -> None:
+ assert deduplicate_lines(["Hello"]) == ["Hello"]
+
+ def test_two_identical_lines(self) -> None:
+ result = deduplicate_lines(["Warning", "Warning"])
+ assert result == ["Warning", "(repeated 2 times)"]
+
+ def test_two_different_lines(self) -> None:
+ result = deduplicate_lines(["Line 1", "Line 2"])
+ assert result == ["Line 1", "Line 2"]
+
+ def test_multiple_groups(self) -> None:
+ lines = ["A", "A", "B", "B", "B", "C"]
+ result = deduplicate_lines(lines)
+ assert result == [
+ "A",
+ "(repeated 2 times)",
+ "B",
+ "(repeated 3 times)",
+ "C",
+ ]
+
+ def test_all_identical(self) -> None:
+ result = deduplicate_lines(["Same"] * 10)
+ assert result == ["Same", "(repeated 10 times)"]
+
+ def test_no_duplicates(self) -> None:
+ lines = ["A", "B", "C", "D"]
+ result = deduplicate_lines(lines)
+ assert result == ["A", "B", "C", "D"]
+
+ def test_empty_strings(self) -> None:
+ lines = ["", "", "Text", "", ""]
+ result = deduplicate_lines(lines)
+ assert result == [
+ "",
+ "(repeated 2 times)",
+ "Text",
+ "",
+ "(repeated 2 times)",
+ ]
+
+ def test_empty_list(self) -> None:
+ assert deduplicate_lines([]) == []
+
+
+class TestNormalizeProgressBars:
+ def test_simple_carriage_return(self) -> None:
+ lines = ["0%\r50%\r100%"]
+ result = normalize_progress_bars(lines)
+ assert result == ["100%"]
+
+ def test_mixed_lines(self) -> None:
+ lines = ["Start", "0%\r50%\r100%", "End"]
+ result = normalize_progress_bars(lines)
+ assert result == ["Start", "100%", "End"]
+
+ def test_removes_empty_lines(self) -> None:
+ lines = ["Text", "", " ", "More"]
+ result = normalize_progress_bars(lines)
+ assert result == ["Text", "More"]
+
+ def test_tqdm_style(self) -> None:
+ lines = [
+ " 0%| | 0/100\r 50%|█████ | 50/100\r100%|██████████| 100/100"
+ ]
+ result = normalize_progress_bars(lines)
+ assert result == ["100%|██████████| 100/100"]
+
+ def test_no_carriage_returns(self) -> None:
+ lines = ["Line 1", "Line 2"]
+ result = normalize_progress_bars(lines)
+ assert result == ["Line 1", "Line 2"]
+
+ def test_empty_list(self) -> None:
+ assert normalize_progress_bars([]) == []
+
+
+class TestTruncateOutput:
+ def test_no_truncation_when_under_limit(self) -> None:
+ lines = [f"Line {i}" for i in range(5)]
+ result = truncate_output(lines, max_lines=10)
+ assert result == lines
+
+ def test_truncates_middle(self) -> None:
+ lines = [f"Line {i}" for i in range(1, 11)]
+ result = truncate_output(lines, max_lines=5)
+ assert len(result) == 6
+ assert result[0] == "Line 1"
+ assert result[1] == "Line 2"
+ assert "truncated" in result[2]
+ assert result[-2] == "Line 9"
+ assert result[-1] == "Line 10"
+
+ def test_keeps_head_and_tail(self) -> None:
+ lines = [f"Epoch {i}" for i in range(1, 21)]
+ result = truncate_output(lines, max_lines=6)
+ assert result[0] == "Epoch 1"
+ assert result[1] == "Epoch 2"
+ assert result[2] == "Epoch 3"
+ assert "truncated 14 lines" in result[3]
+ assert result[-3] == "Epoch 18"
+ assert result[-2] == "Epoch 19"
+ assert result[-1] == "Epoch 20"
+
+ def test_shows_correct_count(self) -> None:
+ lines = ["x"] * 100
+ result = truncate_output(lines, max_lines=10)
+ assert any("truncated 90 lines" in line for line in result)
+
+ def test_empty_list(self) -> None:
+ assert truncate_output([]) == []
+
+
+class TestCleanOutput:
+ def test_full_pipeline_with_ansi_and_duplicates(self) -> None:
+ lines = [
+ "\x1b[32mStart\x1b[0m",
+ "\x1b[33mWarning\x1b[0m",
+ "\x1b[33mWarning\x1b[0m",
+ "\x1b[33mWarning\x1b[0m",
+ ]
+ result = clean_output(lines)
+ assert result == ["Start", "Warning", "(repeated 3 times)"]
+
+ def test_full_pipeline_with_progress_bars(self) -> None:
+ lines = [
+ "Training",
+ "0%\r50%\r100%",
+ "Complete",
+ ]
+ result = clean_output(lines)
+ assert result == ["Training", "100%", "Complete"]
+
+ def test_combined_ml_workflow(self) -> None:
+ lines = [
+ "\x1b[1mEpoch 1/10\x1b[0m",
+ "0%| | 0/100\r100%|██████████| 100/100",
+ "\x1b[34mLoss: 0.543\x1b[0m",
+ "\x1b[1mEpoch 2/10\x1b[0m",
+ "0%| | 0/100\r100%|██████████| 100/100",
+ "\x1b[34mLoss: 0.432\x1b[0m",
+ ]
+ result = clean_output(lines)
+ assert result == [
+ "Epoch 1/10",
+ "100%|██████████| 100/100",
+ "Loss: 0.543",
+ "Epoch 2/10",
+ "100%|██████████| 100/100",
+ "Loss: 0.432",
+ ]
+
+ def test_empty_list(self) -> None:
+ assert clean_output([]) == []