Metadata-Version: 2.4
Name: marimo-lens
Version: 0.0.7
Summary: Ground your agent's work in the code and context behind the result you select in a marimo notebook
Project-URL: Documentation, https://marimo-team.github.io/marimo-lens/
Project-URL: Issues, https://github.com/marimo-team/marimo-lens/issues
Project-URL: Source, https://github.com/marimo-team/marimo-lens
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Requires-Dist: agent-plugins==0.1.0
Requires-Dist: anywidget>=0.11.0
Requires-Dist: marimo>=0.24.0
Requires-Dist: pydantic>=2
Requires-Dist: traitlets>=5
Requires-Dist: typing-extensions>=4.4
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://marimo-team.github.io/marimo-lens/">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://marimo-team.github.io/marimo-lens/brand/marimo-lens-lockup-horizontal-dark.svg">
      <img alt="marimo-lens" src="https://marimo-team.github.io/marimo-lens/brand/marimo-lens-lockup-horizontal-light.svg" width="620">
    </picture>
  </a>
</p>

<p align="center">
  <a href="https://pypi.org/project/marimo-lens/"><img alt="PyPI" src="https://img.shields.io/pypi/v/marimo-lens.svg"></a>
  <a href="https://spdx.org/licenses/Apache-2.0.html"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-blue.svg"></a>
</p>

**Let your notebook agent see what you see.**

Point to a notebook result and say what should change. Lens gives your agent
the producing cell, related notebook context, and an annotated image to ground
its work in the result you marked.

While the agent works, Lens can show which cell it is changing or checking,
bring the result into view for review, and keep completed requests in
**History** for another pass.

[Read the user guide](https://marimo-team.github.io/marimo-lens/) for the
agent workflow.

## Quick start

Open a local marimo notebook with Lens available:

```sh
uvx --with marimo-lens marimo edit notebook.py
```

Mount Lens in one notebook cell:

```python
from marimo_lens import Lens

lens = Lens()
lens
```

Keep the cell mounted. Press **Select**, then click a point or drag a region
inside a rendered output. Add a note with what you want the agent to inspect or
change.

### Select additional page regions

Pass one CSS selector for page regions that should also receive feedback:

```python
lens = Lens(
    dom_selector="#app-shell :is(header, section, article)",
)
```

Notebook outputs remain selectable. Each additional selection keeps the
document path, an exact DOM locator, producer IDs inferred from generic runtime
metadata, and the marked PNG. Host integrations own the selector they pass to
Lens.

## Connect an agent

The `marimo-lens` package carries the Agent Skill that matches its Python API.
An agent that already executes code in the live notebook kernel can continue
directly with Lens.

To give the agent live kernel execution, install
[marimo Pair](https://github.com/marimo-team/marimo-pair/tree/main/skills/marimo-pair):

```console
npx skills add https://github.com/marimo-team/marimo-pair --skill marimo-pair
```

Use `$marimo-pair` to connect to or start the notebook, then resume
`$marimo-lens`. Inside code mode, Marimo advertises `marimo_lens.agent` as the
`lens` capability, and the module exposes the installed skill path:

```python
import marimo_lens.agent as lens_agent

print(lens_agent.agent_skill() / "SKILL.md")
```

After selecting an output and adding a note, ask the agent:

```text
Resolve my Lens request.
```

See [Agent workflow](https://marimo-team.github.io/marimo-lens/agents) to
start with existing code-mode access or enter code mode through Pair.

## Python API

The package exports `CellReference`, `Lens`, `LensContext`, `LensError`,
`LensReferences`, `NotebookReference`, `SelectionReference`,
`SelectionTargetReference`, and `__version__`. The version string comes from the
installed `marimo-lens` distribution metadata.

Agent integrations use five methods:

| Method                                                                        | Behavior                                                         |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `lens.context()`                                                              | Returns detached selection context with lazy notebook text       |
| `lens.start_activity(cell_id, *, duration_ms=None, label=None, message=None)` | Marks current work until stopped or its optional hold ends       |
| `lens.stop_activity(cell_id)`                                                 | Stops activity attached to that exact cell                       |
| `lens.reveal(cell_id, *, duration_ms, label=None, message=None)`              | Brings one verified or explanatory cell into view                |
| `lens.resolve(selection_ids, *, expected_revision, summary=None)`             | Moves one or more selections to History in one guarded operation |

The [Python API reference](https://marimo-team.github.io/marimo-lens/api)
documents return values, errors, limits, and lifecycle behavior.

## Project

- [Documentation](https://marimo-team.github.io/marimo-lens/)
- [Source](https://github.com/marimo-team/marimo-lens)
- [Example notebook](https://github.com/marimo-team/marimo-lens/blob/main/examples/lens.py)
- [Issue tracker](https://github.com/marimo-team/marimo-lens/issues)
- [Security policy](https://github.com/marimo-team/marimo-lens/security/policy)
- [Apache License 2.0](https://github.com/marimo-team/marimo-lens/blob/main/LICENSE)
