marimo-pmprov 0.1.0__tar.gz

marimo_pmprov-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: "CI"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout ⬇️
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up Python 🐍
+        uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Install uv 📦
+        uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Install dependencies 📦
+        run: uv sync --extra dev
+
+      - name: Run tests 🧪
+        run: uv run pytest
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    outputs:
+      already-published: ${{ steps.version-check.outputs.already-published }}
+    steps:
+      - name: Checkout ⬇️
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up Python 🐍
+        uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Install uv 📦
+        uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Check if version already published 🔍
+        id: version-check
+        run: |
+          NAME=$(python -c "import tomllib; d=tomllib.load(open('pyproject.toml','rb')); print(d['project']['name'])")
+          VERSION=$(python -c "import tomllib; d=tomllib.load(open('pyproject.toml','rb')); print(d['project']['version'])")
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://pypi.org/pypi/$NAME/$VERSION/json)
+          if [ "$STATUS" = "200" ]; then
+            echo "already-published=true" >> $GITHUB_OUTPUT
+          else
+            echo "already-published=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Build 🏗️
+        if: steps.version-check.outputs.already-published == 'false'
+        run: uv build
+
+      - name: Upload dist artifacts 📤
+        if: steps.version-check.outputs.already-published == 'false'
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    if: needs.build.outputs.already-published == 'false'
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download dist artifacts 📥
+        uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv 📦
+        uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Publish to PyPI 🚀
+        run: uv publish

marimo_pmprov-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+node_modules/
+dist/
+*.egg-info/
+.venv/
+__marimo__/
+docs/
+project/

marimo_pmprov-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: marimo-pmprov
+Version: 0.1.0
+Summary: A marimo anywidget for analytic provenance and annotation, decoupled from pmprov.
+Requires-Python: >=3.11
+Requires-Dist: anywidget>=0.9
+Requires-Dist: marimo>=0.9
+Requires-Dist: traitlets>=5.14
+Provides-Extra: dev
+Requires-Dist: altair; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: plotly; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: vl-convert-python; extra == 'dev'

marimo_pmprov-0.1.0/README.md

@@ -0,0 +1,130 @@
+# marimo-pmprov
+
+A marimo `anywidget` plugin that gives process-mining analysts a git-style
+"Source Control" sidebar for analytic provenance and annotation: a curated
+commit rail, a Miller-columns provenance tree with tag/artifact filters and
+an inline inspector, and a read-only Reviewer mode with tag-based state
+restore.
+
+This package ships fully decoupled from the `pmprov` library — it runs out
+of the box against a `MockProvenanceSource` whose data is shaped exactly
+like pmprov's real model (see `provenance_widget/interfaces.py`), so no
+`pmprov` install is required to try it or to develop against it.
+
+## Install
+
+```bash
+pip install "marimo-pmprov @ git+https://github.com/alvarobernal2412/marimo-pmprov.git"
+```
+
+Or, for local development:
+
+```bash
+git clone https://github.com/alvarobernal2412/marimo-pmprov.git
+cd marimo-pmprov
+pip install -e ".[dev]"
+```
+
+This installs the widget with its `MockProvenanceSource` demo backend. See
+`examples/demo_notebook.py` for a full runnable notebook (run it with
+`marimo edit examples/demo_notebook.py`).
+
+## Quickstart
+
+```python
+import marimo as mo
+from provenance_widget.mock_source import MockProvenanceSource
+from provenance_widget.widget import ProvenancePanel
+
+panel = ProvenancePanel(source=MockProvenanceSource(), mode="student")
+
+# mo.sidebar(...) must be the last bare expression in its own cell to render —
+# it cannot be assigned to a variable and displayed from a different cell.
+mo.sidebar(panel.sidebar())
+```
+
+The sidebar has three tabs:
+
+- **curated** — a chronological feed of committed annotations (oldest first,
+  newest appended at the bottom), plus a composer for writing new ones.
+- **tree** — a Miller-columns view of the full provenance history, with
+  filter chips for tags and linked artifacts (matching steps stay expanded,
+  the rest collapse to a single line) and an inspector pinned to the bottom
+  that opens automatically when you click a node.
+- **config** — switches between `student` (can annotate) and `reviewer`
+  (read-only, can request a restore to any tagged state) personas.
+
+### Tagging notebook outputs so they can be picked
+
+Any table or chart you want the sidebar's "Pick from notebook" picker (and
+the hover "+" gutter affordance) to be able to target needs to be wrapped
+with `show_table` / `show_chart`:
+
+```python
+from provenance_widget.display import show_table, show_chart
+
+# tables — picking refines down to a specific cell or column automatically
+annotated_table = show_table(
+    mo.ui.table(my_dataframe), artifact_id="art-event-log", artifact_name="event_log.csv"
+)
+annotated_table
+```
+
+```python
+# charts — matplotlib figures work via mo.as_html; any renderer that
+# produces an mo.Html works the same way (Altair, Plotly, etc.)
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+my_dataframe.groupby("activity")["duration"].mean().plot.bar(ax=ax)
+
+bar_chart = show_chart(mo.as_html(fig), artifact_id="art-duration-bar", artifact_name="Chart_DurationByActivity")
+bar_chart
+```
+
+`show_chart` works with any `mo.Html`-producing visualization, for example:
+
+| Visualization | How to produce the `mo.Html` |
+| --- | --- |
+| Bar chart | `mo.as_html(fig)` from a matplotlib `ax.bar(...)` / `.plot.bar()` figure |
+| Line chart | `mo.as_html(fig)` from a matplotlib `.plot.line()` figure |
+| Scatter plot | `mo.as_html(fig)` from a matplotlib `ax.scatter(...)` figure |
+| Histogram | `mo.as_html(fig)` from a matplotlib `ax.hist(...)` figure |
+| Heatmap | `mo.as_html(fig)` from a matplotlib `ax.imshow(...)` figure |
+
+See `examples/demo_notebook.py` for all five wired up against the same
+dataset.
+
+## Connecting a real pmprov-backed history
+
+The widget only depends on the `ProvenanceSource` protocol
+(`provenance_widget.interfaces.ProvenanceSource`) — it never imports
+`pmprov` directly. To back the sidebar with a real `pmprov.AnalysisHistory`
+instead of mock data:
+
+1. Implement a `PmprovAdapter` class with a `get_tree(self) -> ProvenanceTree`
+   method that translates `AnalysisHistory.list_states()` /
+   `ProvenanceTracker` data into the `ProvenanceTree` dataclasses in
+   `provenance_widget/interfaces.py` (field names already mirror pmprov's
+   model, per pmprov's `MODEL.md`). `Annotation`/`Tag` are new concepts not
+   present in pmprov — the adapter is where you decide how they're sourced
+   or persisted against a real history.
+2. Install `pmprov` alongside this package. PyPI doesn't allow published
+   packages to declare a direct VCS dependency, so there's no `pmprov`
+   extra — install it separately:
+
+   ```bash
+   pip install marimo-pmprov "pmprov @ git+https://github.com/alvarobernal2412/pmprov.git@main"
+   ```
+3. Pass your adapter instead of `MockProvenanceSource` to `ProvenancePanel`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+
+cd frontend
+npm install
+npm run build   # or: npm run watch
+```

marimo_pmprov-0.1.0/examples/demo_notebook.py

@@ -0,0 +1,226 @@
+import marimo
+
+__generated_with = "0.23.16"
+app = marimo.App(width="full")
+
+
+@app.cell
+def _():
+    import marimo as mo
+    import pandas as pd
+    import matplotlib
+    import altair as alt
+    import vl_convert as vlc
+    import plotly.express as px
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    from provenance_widget.display import show_chart, show_table
+    from provenance_widget.mock_source import MockProvenanceSource
+    from provenance_widget.widget import ProvenancePanel
+
+    return (
+        MockProvenanceSource,
+        ProvenancePanel,
+        alt,
+        mo,
+        pd,
+        plt,
+        px,
+        show_chart,
+        show_table,
+        vlc,
+    )
+
+
+@app.cell
+def _(MockProvenanceSource, ProvenancePanel):
+    # Persona (student/reviewer) is switched from the widget's own "config"
+    # tab, not a separate marimo control — this is just the initial value.
+    panel = ProvenancePanel(source=MockProvenanceSource(), mode="student")
+    return (panel,)
+
+
+@app.cell
+def _(mo, panel):
+    # mo.sidebar(...) must be the last bare expression in this cell to render —
+    # it cannot be assigned to a variable and displayed from a different cell.
+    mo.sidebar(panel.sidebar())
+    return
+
+
+@app.cell
+def _(mo, pd, show_table):
+    event_log = pd.DataFrame({
+        "case:concept:name": ["c1", "c1", "c2"],
+        "concept:name": ["Register", "Approve", "Register"],
+        "duration": [12.5, 40.2, 8.1],
+    })
+    table = mo.ui.table(event_log)
+    annotated_table = show_table(table, artifact_id="art-event-log", artifact_name="event_log.csv")
+    annotated_table
+    return (event_log,)
+
+
+@app.cell
+def _(event_log, mo, plt, show_chart):
+    # Five different visualization types, each picker-targetable at
+    # "chart_selection" granularity (see provenance_widget/display.py).
+
+    bar_fig, bar_ax = plt.subplots(figsize=(4, 3))
+    event_log.groupby("concept:name")["duration"].mean().plot.bar(ax=bar_ax, color="#0EA5E9")
+    bar_ax.set_title("Mean duration by activity")
+    bar_ax.set_ylabel("hours")
+    bar_chart = show_chart(
+        mo.as_html(bar_fig), artifact_id="art-duration-bar", artifact_name="Chart_DurationByActivity"
+    )
+
+    line_fig, line_ax = plt.subplots(figsize=(4, 3))
+    event_log["duration"].plot.line(ax=line_ax, color="#10B981", marker="o")
+    line_ax.set_title("Duration across events")
+    line_ax.set_ylabel("hours")
+    line_chart = show_chart(
+        mo.as_html(line_fig), artifact_id="art-duration-line", artifact_name="Chart_DurationTrend"
+    )
+
+    scatter_fig, scatter_ax = plt.subplots(figsize=(4, 3))
+    scatter_ax.scatter(range(len(event_log)), event_log["duration"], c="#F59E0B")
+    scatter_ax.set_title("Duration per event index")
+    scatter_ax.set_ylabel("hours")
+    scatter_chart = show_chart(
+        mo.as_html(scatter_fig), artifact_id="art-duration-scatter", artifact_name="Chart_DurationScatter"
+    )
+
+    hist_fig, hist_ax = plt.subplots(figsize=(4, 3))
+    hist_ax.hist(event_log["duration"], bins=5, color="#F43F5E")
+    hist_ax.set_title("Duration distribution")
+    hist_ax.set_xlabel("hours")
+    hist_chart = show_chart(
+        mo.as_html(hist_fig), artifact_id="art-duration-hist", artifact_name="Chart_DurationHistogram"
+    )
+
+    heatmap_fig, heatmap_ax = plt.subplots(figsize=(4, 3))
+    pivot = event_log.pivot_table(
+        index="case:concept:name", columns="concept:name", values="duration", aggfunc="mean"
+    )
+    im = heatmap_ax.imshow(pivot.fillna(0), cmap="viridis", aspect="auto")
+    heatmap_ax.set_xticks(range(len(pivot.columns)))
+    heatmap_ax.set_xticklabels(pivot.columns, rotation=45, ha="right")
+    heatmap_ax.set_yticks(range(len(pivot.index)))
+    heatmap_ax.set_yticklabels(pivot.index)
+    heatmap_ax.set_title("Duration by case x activity")
+    heatmap_fig.colorbar(im, ax=heatmap_ax)
+    heatmap_chart = show_chart(
+        mo.as_html(heatmap_fig), artifact_id="art-duration-heatmap", artifact_name="Chart_DurationHeatmap"
+    )
+
+    mo.vstack([
+        mo.hstack([bar_chart, line_chart], justify="start"),
+        mo.hstack([scatter_chart, hist_chart], justify="start"),
+        heatmap_chart,
+    ])
+    return
+
+
+@app.cell
+def _(alt, event_log, mo, show_chart, vlc):
+    # Unlike the matplotlib charts above (flat PNGs), Vega-Lite/Altair marks
+    # each bar with an aria-label carrying its data ("concept:name: Register;
+    # duration: 12.5; ..."), which the picker's "svg-mark" resolver
+    # (frontend/src/resolvers.ts) reads off directly — no extra wiring needed.
+    #
+    # marimo's default mo.as_html(chart) embeds Vega-Lite as an interactive
+    # <canvas> (or a rasterized <img>), neither of which has per-mark DOM
+    # nodes to click on — so here the chart is rendered straight to real
+    # inline SVG via vl-convert instead, which is what makes those
+    # aria-labeled <path> marks actually present in the page.
+    altair_chart = alt.Chart(event_log).mark_bar().encode(
+        x=alt.X(field="concept:name", type="nominal"),
+        y=alt.Y(field="duration", type="quantitative"),
+        color=alt.Color(field="case:concept:name", type="nominal"),
+    )
+    altair_svg = vlc.vegalite_to_svg(altair_chart.to_json())
+    annotated_altair_chart = show_chart(
+        mo.Html(altair_svg), artifact_id="art-duration-altair", artifact_name="Chart_DurationAltair"
+    )
+    annotated_altair_chart
+    return
+
+
+@app.cell
+def _(mo, show_chart):
+    # A hand-authored SVG, tagged by hand rather than relying on a charting
+    # library's own accessibility output. This is the general-purpose escape
+    # hatch: any visualization — a custom D3 diagram, a process map, a
+    # network graph — can be picked down to individual elements by putting
+    # data-pw-detail (and optionally data-pw-granularity) directly on the
+    # SVG nodes. The picker's "svg-mark" resolver (resolvers.ts) looks for
+    # exactly that attribute, so no picker code changes were needed for this.
+    #
+    # Reuses artifact_id="art-process-map" — the same artifact the "Baseline
+    # fitness" annotation in mock_source.py already references, so picking
+    # a node here and the tree's "Chart_ProcessMap" filter chip line up.
+    process_steps = ["Register", "Approve", "Archive"]
+    box_w, box_h, gap = 120, 48, 60
+    svg_width = len(process_steps) * box_w + (len(process_steps) - 1) * gap
+    svg_parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{svg_width}" height="{box_h + 20}" '
+        f'viewBox="0 0 {svg_width} {box_h + 20}">',
+        '<defs><marker id="pw-arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" '
+        'orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="#64748B" /></marker></defs>',
+    ]
+    for i, step in enumerate(process_steps):
+        x = i * (box_w + gap)
+        svg_parts.append(
+            f'<g data-pw-detail="{step}" data-pw-granularity="node" role="graphics-symbol" '
+            f'aria-label="Process step: {step}">'
+            f'<rect x="{x}" y="0" width="{box_w}" height="{box_h}" rx="6" '
+            f'fill="#EFF6FF" stroke="#0EA5E9" stroke-width="2" />'
+            f'<text x="{x + box_w / 2}" y="{box_h / 2}" text-anchor="middle" '
+            f'dominant-baseline="middle" font-family="sans-serif" font-size="13">{step}</text>'
+            f"</g>"
+        )
+        if i < len(process_steps) - 1:
+            line_x1, line_x2 = x + box_w, x + box_w + gap
+            svg_parts.append(
+                f'<line x1="{line_x1}" y1="{box_h / 2}" x2="{line_x2 - 8}" y2="{box_h / 2}" '
+                f'stroke="#64748B" stroke-width="2" marker-end="url(#pw-arrow)" />'
+            )
+    svg_parts.append("</svg>")
+    process_map_svg = "".join(svg_parts)
+
+    annotated_process_map = show_chart(
+        mo.Html(process_map_svg), artifact_id="art-process-map", artifact_name="Chart_ProcessMap"
+    )
+    annotated_process_map
+    return
+
+
+@app.cell
+def _(event_log, mo, px, show_chart):
+    # A fourth chart library, for contrast: mo.ui.plotly renders inline
+    # (a <marimo-plotly> custom element — not the CDN-loading <iframe> that
+    # mo.as_html(plotly_fig) produces), so at least "chart_selection"-level
+    # picking works out of the box like any other artifact. Plotly's own SVG
+    # marks don't carry the aria-label convention Vega-Lite does, so unlike
+    # the Altair chart above, per-bar picking isn't automatic here — it's
+    # exactly the kind of case that would need its own resolver (see
+    # frontend/src/resolvers.ts) reading Plotly's "plotly_click" event data
+    # instead of guessing from the DOM.
+    plotly_fig = px.bar(
+        event_log.groupby("concept:name", as_index=False)["duration"].mean(),
+        x="concept:name",
+        y="duration",
+        color="concept:name",
+        title="Mean duration by activity (Plotly)",
+    )
+    annotated_plotly_chart = show_chart(
+        mo.ui.plotly(plotly_fig), artifact_id="art-duration-plotly", artifact_name="Chart_DurationPlotly"
+    )
+    annotated_plotly_chart
+    return
+
+
+if __name__ == "__main__":
+    app.run()

marimo_pmprov-0.1.0/frontend/build.mjs

@@ -0,0 +1,22 @@
+import * as esbuild from "esbuild";
+
+const watch = process.argv.includes("--watch");
+
+const options = {
+  entryPoints: ["src/main.ts"],
+  bundle: true,
+  format: "esm",
+  outfile: "../provenance_widget/static/widget.js",
+  minify: !watch,
+  sourcemap: watch,
+  loader: { ".css": "css" },
+};
+
+if (watch) {
+  const ctx = await esbuild.context(options);
+  await ctx.watch();
+  console.log("watching...");
+} else {
+  await esbuild.build(options);
+  console.log("build complete");
+}