marimo-lens

marimo Lens を使う

Lens を使うと、ライブノートブックで視覚的な共同作業ができます。ノートブックの結果をたどる Trail を表示したり、選択した画面をそのソース、コンテキスト、キャプチャ画像に関連付けたりできます。アクティブなコードモードの連携機能が、ノートブックの確認、編集、実行を担います。

ワークフローを選ぶ

ユーザーの意図	アクション
「Lens を追加して」または「Lens が見えない」	既存のインスタンスを再利用するか、Lens を追加します。
「このノートブックを順に説明して」または「この結果を説明して」	関連するセルを確認して、Trail を表示します。
「これを変更して」または「選択した項目に対応して」	選択されたリクエストを読み取り、結果を検証して解決します。

ユーザーのリクエストに基づいて進め方を選びます。選択項目がなくても、全般的な説明には Trail を利用できます。選択項目があっても、明示的なウォークスルーの依頼が、それらを編集または解決する許可に変わるわけではありません。

この基本スキルには、通常のマウントと Trail のワークフローがすべて含まれています。タスクまたは例外に該当する場合に限り、リファレンスを読みます。

このスキル内の各 Python ブロックは、ライブノートブックのカーネルで 1 回の呼び出しとして実行します。ターミナルから実行する場合は、標準入力にブロックを渡して marimo pair execute を 1 回実行します。出力された結果は JSON の stdout に届きます。marimo pair で Lens を実行するには、対象の指定、エラー、並行処理について記載されています。エディターのコードモードのサイドバーでは、各ブロックが 1 回の execute_code 呼び出しに相当します。同じ環境と Lens のインストールについて、すでに読み込まれた手順を再利用します。

チャット、アクティビティ、ポップオーバー、要約では、同僚に話すような口調を使います。変更した内容や見つけたこと、それを裏付ける根拠を説明します。具体的なラベルと短い補足メッセージを使います。読み取り専用のツアーでは、既存の調査結果を説明します。依頼された場合は、教えるような口調で説明します。

依頼された作業から始める

marimo pair の help(cm) など、連携機能で必須とされる最初の呼び出しの後は、接続と最初の有用な操作をまとめます。追加リクエストでは利用可能かどうかを確認し、Trail では関連するセルと値を確認し、選択項目がある場合は現在の選択スナップショットを読み取ります。ID だけを出力する独立した呼び出しは不要です。

connect(ctx) は、作成済みおよび自動マウントされたインスタンスを再利用します。ブラウザーで使用可能な Lens が表示中のドックを 1 つ所有している場合、コンテキストにほかの Lens オブジェクトが含まれていても、その Lens が選択されます。複数回の呼び出しにまたがる作業では、その不透明な ID を保持します。各呼び出しではスクラッチパッドが新しくなるため、後続の呼び出しでは cm と marimo_lens を再インポートし、コンテキストを再取得して、identity= を使って同じ Lens を選択します。

lens_ambiguous の場合は、marimo_lens.agent.discover(ctx) を調べ、リクエストと表示中の画面に一致する ID を選びます。その手掛かりでインスタンスを特定できない場合は、ユーザーに確認します。

Lens がない場合に追加する

マウント呼び出し中に利用可能か確認します。Lens のセルまたはホストマウントがまだ作成中、あるいはレンダリング中の場合に限り、接続できないときは再試行します。Lens が存在せず、マウントも保留中でないと確認できたら、すぐに追加します。

マウントが保留中でない通常のノートブックでは、利用可能な Lens を再利用するか、セルを 1 つキューに追加します。

import marimo._code_mode as cm
import marimo_lens

async with cm.get_context() as ctx:
    available = marimo_lens.agent.discover(ctx)
    if available:
        print({"identities": [mounted.identity for mounted in available]})
    else:
        print({"cell_id": marimo_lens.agent.add_lens_cell(ctx)})

呼び出しを終了して、キューに追加したセルを実行し、ブラウザーでドックをレンダリングできるようにします。新しい呼び出しで再接続し、ドックが利用可能であることを確認します。ヘルパーは、以前に追加した Lens セルを再利用し、実行中の Lens がない場合は再実行します。カスタムのマウントポリシーを持つホストでは、setup で説明されているように、独自の統合を通じて Lens をマウントします。

サーバーの再起動後など、新しいカーネルでノートブックを再度開くと、すべてのセルが未実行として表示されることがあります。どのセルも実行されていないため、Lens は存在せず、以前のカーネルからの選択内容も失われています。コードモードの呼び出しでノートブックのセルを実行できるのは、ctx.run_cell() を通じてのみです。Lens をマウントするセルを実行します。これは、marimo をインポートするセルか、作成者が用意した Lens セルです。それ以外の場合は、ヘルパーを使用します。

ユーザーが Lens の追加だけを求めている場合は、準備ができたことを伝えて終了します。依頼に Trail または選択ワークフローが含まれる場合は、続けて対応します。

Trail でノートブックを説明する

Trail は、ノートブックのセルに付与する順序付きの説明です。各ステップでは、ラベルとメッセージを添えて結果を表示します。ユーザーがその場で根拠を追えるように、概要説明、ウォークスルー、解説に使用します。

会話で確認済みの情報を再利用します。経路が不明な場合は、接続して ctx.cells の簡潔な概要（ID、名前、ステータス、コードの先頭行）を 1 回の呼び出しで確認します。関連する主要セルとそのエラー、および ctx.globals にある必要な実行時の値をまとめて読み取ります。質問、根拠、主な結果、次のステップをノートブックの順序に沿って説明します。確認が完了したら、Trail を 1 つ送信して制御を返します。

実行可能なグラフに含まれるセルは、ctx.graph.cells で確認します。そのグラフの外にある説明用セルは解説の参考にはできますが、表示対象にはできません。結果を提示する前に、その情報源と値を確認し、対象セルがアイドル状態で、関連するエラーがないことを確かめます。

結果を確認したら、短い経路を選びます。inputs、analysis、summary という名前のセルがあるノートブックでは、この呼び出しで Trail 全体を表示できます。実際のセル名と、その値で裏付けられる説明に置き換えてください。

import marimo._code_mode as cm
import marimo_lens

ctx = cm.get_context()
mounted = marimo_lens.agent.connect(ctx)
route = [
    ("inputs", "Inputs", "Start with the values used by this notebook."),
    ("analysis", "Calculation", "Follow how the inputs become a result."),
    ("summary", "Conclusion", "Review the result and what it supports."),
]
steps = []
for name, label, message in route:
    cell = ctx.cells[name]
    if cell.id not in ctx.graph.cells or cell.status != "idle" or cell.errors:
        raise RuntimeError(f"Verify {name} before revealing it")
    steps.append({"target": cell.id, "label": label, "message": message})
mounted.reveal(steps, duration_ms=None)

各ステップのメッセージには、ノートブックから得られた具体的な結果を使って説明を記載します。reveal() は順序付きのステップを 1～16 個受け付け、None を返します。各ステップには対象があり、最大 40 UTF-16 単位の任意のラベルと、最大 1,000 単位の任意のメッセージを指定できます。ユーザーは自分のペースでポップオーバーを操作します。経路を表示したら制御を返します。テキストやデータのウォークスルーには、選択スナップショット、PNG キャプチャ、解像度、タイミングループは必要ありません。セルの編集や再実行は、依頼された場合に限って行います。

Trail は一時的なものです。閉じる、更新する、別のアテンションイベントが発生する、または参照先のセルや上流の入力が変更されると終了します。有限の duration_ms を指定すると、経路全体の時間が制限され、ナビゲーションによってタイマーがリセットされることはありません。結果が変更された場合は、別の Trail を表示する前に確認します。

選択範囲に対応する

開いている選択範囲とそのメモを、1 回の呼び出しで読み取ります。選択範囲は snapshot.references["selections"] にあり、snapshot.current は「これ」や「ここ」の 指示対象である可能性が高いものです。

import json

import marimo._code_mode as cm
import marimo_lens

mounted = marimo_lens.agent.connect(cm.get_context())
snapshot = mounted.context()
print(
    json.dumps(
        {
            "identity": mounted.identity,
            "revision": snapshot.revision,
            "currentId": (snapshot.current or {}).get("id"),
            "selections": [
                {"id": s["id"], "label": s["label"], "note": s["note"]}
                for s in snapshot.references["selections"]
            ],
        },
        ensure_ascii=False,
    )
)

リストが空の場合、このノートブックには開いている選択範囲がありません。エディターの コードモードのサイドバーからアクセスできるのは、そのサイドバー自身のノートブックのみです。 そのことをユーザーに伝え、別のノートブックにあるメモには、そのノートブックのサイドバーか marimo pair を通じて対応するよう案内してください。

完全なライフサイクルについては、選択範囲への対応 に従ってください。 コンテキストを読み取り、根拠を確認し、作業を開始し、依頼された変更を適用し、 検証して、表示し、解決します。次の境界を守ってください。

• 保存された SelectionReference と、キャプチャされたリビジョンを表示対象として使用します。 その生成セルは出所と編集箇所を示すものです。DOM ターゲットの生成セルは 0 個の場合も 複数の場合もあります。
• 選択されたマークについて視覚的な主張をする前に、キャプチャされた画像を確認します。 変更は、新しいランタイムとブラウザーの根拠に照らして検証します。画像を確認できない場合は、 対応範囲の限界を報告してください。
• 検証が完了するまで、作業中の状態を表示したままにします。表示すると、その状態は置き換えられます。 同じキャプチャ済みリビジョンを使って、1 回のカーネル呼び出しで resolve() の前に reveal() を呼び出し、その後ブラウザーに制御を戻します。
• 結果と検証内容を具体的にまとめて解決します。曖昧な選択範囲、ブロックされた選択範囲、 未検証の選択範囲は開いたままにします。リビジョンの競合が発生した場合は、自分が開始した 作業を停止し、再接続して、新しいコンテキストを再評価します。
• Lens は 1 つのノートブックセッションに属します。接続中の Lens にユーザーが言及した 選択範囲がない場合は、別のノートブック内の選択範囲 の説明に従って、ほかのノートブックを確認します。

$marimo-lens address は、各メモとその根拠を含め、開いているすべての選択範囲に対応します。 それ以外の依頼については、ユーザーの指示を以前の選択範囲のメモより優先します。 選択範囲リストが空でも、概要や手順の説明を求める依頼には対応できます。

さらに詳しく

パッケージが見つからない場合やノートブックに接続できない場合は セットアップ を、 選択可能な HTML やウィジェットを作成する場合は ターゲットの作成 を、 画像転送、呼び出し間のフィードバック、復旧については コードモードのレシピ を 参照してください。

選択範囲への対応については、ノートブック内でリファレンスを読み取ってください。

import marimo_lens

print(
    marimo_lens.agent.skill()
    .file("references/selections.md")
    .read_text(encoding="utf-8")
)

正確な操作仕様については、help(mounted) または help(mounted.reveal) を使用してください。 ドキュメントのインデックス から、 より幅広い例や API ガイダンスを確認できます。公開されている API が、インストール済みの バージョンに対応しているか確認してください。