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(code-mode): add capability discovery (#10399)

Péter Gyarmati75d1c9a9db36
diff --git a/marimo/_code_mode/__init__.py b/marimo/_code_mode/__init__.py
index 5d95450656..aed5884576 100644
--- a/marimo/_code_mode/__init__.py
+++ b/marimo/_code_mode/__init__.py
@@ -32,6 +32,10 @@ Usage::
from __future__ import annotations
+import sys
+from types import ModuleType
+
+from marimo._code_mode._capabilities import capabilities
from marimo._code_mode._context import (
AsyncCodeModeContext,
CellStatusType,
@@ -45,5 +49,37 @@ __all__ = [
"CellStatusType",
"NotebookCell",
"StaleCellError",
+ "capabilities",
"get_context",
]
+
+
+class _CodeModeModule(ModuleType):
+ @property
+ def __doc__(self) -> str | None:
+ doc = self.__dict__.get("__doc__")
+ if not isinstance(doc, str):
+ return None
+
+ installed = capabilities()
+ if not installed:
+ return doc
+
+ modules = "\n".join(
+ f" {name} import {module}"
+ for name, module in installed.items()
+ )
+ return (
+ f"{doc}\n\n"
+ "Installed capabilities:\n\n"
+ f"{modules}\n\n"
+ "Import a relevant module and call `help(module)` to learn "
+ "how to use it."
+ )
+
+ @__doc__.setter
+ def __doc__(self, value: str | None) -> None:
+ self.__dict__["__doc__"] = value
+
+
+sys.modules[__name__].__class__ = _CodeModeModule
diff --git a/marimo/_code_mode/_capabilities.py b/marimo/_code_mode/_capabilities.py
new file mode 100644
index 0000000000..de3312247b
--- /dev/null
+++ b/marimo/_code_mode/_capabilities.py
@@ -0,0 +1,22 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from marimo._entrypoints.ids import KnownEntryPoint
+from marimo._entrypoints.registry import get_entry_points
+
+_ENTRY_POINT_GROUP: KnownEntryPoint = "marimo.agent.capability"
+
+
+def capabilities() -> dict[str, str]:
+ """Return installed capability names mapped to importable modules."""
+ modules: dict[str, str] = {}
+ for entry_point in get_entry_points(_ENTRY_POINT_GROUP):
+ module = entry_point.module
+ registered = modules.get(entry_point.name)
+ if registered is not None and registered != module:
+ raise RuntimeError(
+ f"Multiple capability modules are registered as "
+ f"{entry_point.name!r}"
+ )
+ modules[entry_point.name] = module
+ return dict(sorted(modules.items()))
diff --git a/marimo/_entrypoints/ids.py b/marimo/_entrypoints/ids.py
index a51f377e2d..00b86b191c 100644
--- a/marimo/_entrypoints/ids.py
+++ b/marimo/_entrypoints/ids.py
@@ -5,6 +5,7 @@ from typing import Literal
# Internal entrypoints. Not user-facing as the API is not stable.
KnownEntryPoint = Literal[
+ "marimo.agent.capability",
"marimo.cell.executor",
"marimo.cache.store",
"marimo.kernel.lifespan",
diff --git a/tests/_code_mode/test_code_mode_capabilities.py b/tests/_code_mode/test_code_mode_capabilities.py
new file mode 100644
index 0000000000..6ed3c68d00
--- /dev/null
+++ b/tests/_code_mode/test_code_mode_capabilities.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import contextlib
+import io
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import marimo._code_mode as cm
+
+
+@patch("marimo._code_mode._capabilities.get_entry_points")
+def test_capabilities_lists_modules_without_loading(
+ get_entry_points: MagicMock,
+) -> None:
+ first = MagicMock(name="first")
+ first.name = "zeta"
+ first.module = "zeta.agent"
+ second = MagicMock(name="second")
+ second.name = "alpha"
+ second.module = "alpha.agent"
+ duplicate = MagicMock(name="duplicate")
+ duplicate.name = "alpha"
+ duplicate.module = "alpha.agent"
+ get_entry_points.return_value = [first, second, duplicate]
+
+ assert cm.capabilities() == {
+ "alpha": "alpha.agent",
+ "zeta": "zeta.agent",
+ }
+ get_entry_points.assert_called_once_with("marimo.agent.capability")
+ first.load.assert_not_called()
+ second.load.assert_not_called()
+ duplicate.load.assert_not_called()
+
+
+@patch("marimo._code_mode._capabilities.get_entry_points")
+def test_help_lists_installed_capability_modules_without_loading(
+ get_entry_points: MagicMock,
+) -> None:
+ entry_point = MagicMock()
+ entry_point.name = "lens"
+ entry_point.module = "marimo_lens.agent"
+ get_entry_points.return_value = [entry_point]
+
+ output = io.StringIO()
+ with contextlib.redirect_stdout(output):
+ help(cm)
+
+ assert "Installed capabilities:" in output.getvalue()
+ assert "lens import marimo_lens.agent" in output.getvalue()
+ assert "help(module)" in output.getvalue()
+ entry_point.load.assert_not_called()
+
+
+@patch("marimo._code_mode._capabilities.get_entry_points")
+def test_capabilities_rejects_conflicting_modules(
+ get_entry_points: MagicMock,
+) -> None:
+ first = MagicMock()
+ first.name = "lens"
+ first.module = "first.agent"
+ second = MagicMock()
+ second.name = "lens"
+ second.module = "second.agent"
+ get_entry_points.return_value = [first, second]
+
+ with pytest.raises(RuntimeError, match="Multiple capability modules"):
+ cm.capabilities()