Deploy H2EPR-Bench Explorer Space

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --upgrade pip && pip install -r /app/requirements.txt
+
+COPY . /app
+
+EXPOSE 7860
+
+CMD streamlit run app.py --server.port=7860 --server.address=0.0.0.0

README.md

@@ -1,10 +1,32 @@
 ---
-title: H2EPR Bench Explorer
-emoji: 👀
+title: H2EPR-Bench Explorer
 colorFrom: gray
-colorTo: indigo
+colorTo: blue
 sdk: docker
 pinned: false
+license: cc-by-nc-4.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# H²EPR-Bench Explorer
+
+H²EPR-Bench Explorer is the planned interactive browsing layer for `AgenticFinLab/H2EPR-Bench`. It is separate from the canonical dataset repository: the dataset repo remains the release package, while this Docker Space runs a Streamlit app for search, event detail, stage inspection, public FinalCascade JSON browsing, and Gantt-style timelines.
+
+**Release boundary:** public records are intended for browsing, reuse, and presentation. Official scoring uses the [manual-gated Gold companion](https://huggingface.co/datasets/AgenticFinLab/H2EPR-Bench-Gold). Public FinalCascade and Gantt views are supplementary inspection assets, not official scoring references.
+
+## Data Sources
+
+| Source | Role |
+|---|---|
+| `AgenticFinLab/H2EPR-Bench` | Public event catalog, stage table, public sanitized FinalCascade, and Gantt artifact paths. |
+| `AgenticFinLab/H2EPR-Bench-Gold` | Manual-gated Gold companion for official scoring references. Linked for users who need scoring access; not loaded by this app. |
+
+## Local Development
+
+The app can run from a local staged dataset package before upload:
+
+```bash
+export H2EPR_EXPLORER_LOCAL_DATASET_DIR=../../build/hf_dataset_repo_staging/eventmycelium-v1_1000-public
+streamlit run app.py
+```
+
+Without `H2EPR_EXPLORER_LOCAL_DATASET_DIR`, the app downloads public files from the Hugging Face dataset repo.

app.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import sys
+
+APP_ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(APP_ROOT / "src"))
+
+import streamlit as st
+
+from h2epr_explorer.constants import (
+    CATALOG_COLUMNS,
+    GOLD_COMPANION_REPO,
+    PUBLIC_DATASET_REPO,
+    RELEASE_BOUNDARY_NOTICE,
+)
+from h2epr_explorer.data_loader import load_catalog, load_event_graph, load_finalcascade_summary, load_stages
+from h2epr_explorer.filters import filter_catalog
+from h2epr_explorer.render_gantt import build_timeline_figure
+
+
+def _as_records(frame):
+    return frame.to_dict(orient="records")
+
+
+def _select_columns(frame, columns):
+    present = [column for column in columns if column in frame.columns]
+    return frame[present] if present else frame
+
+
+st.set_page_config(page_title="H2EPR-Bench Explorer", layout="wide")
+
+st.title("H²EPR-Bench Explorer")
+st.caption("Interactive browser for public event metadata, stage rows, FinalCascade summaries, and Gantt-style views.")
+st.info(RELEASE_BOUNDARY_NOTICE)
+
+catalog = load_catalog()
+stages = load_stages()
+summary = load_finalcascade_summary()
+
+catalog_rows = _as_records(catalog)
+
+with st.sidebar:
+    st.header("Filter events")
+    query = st.text_input("Search", placeholder="event name, ID, category, keyword")
+    domains = st.multiselect("Domain", sorted(catalog["domain"].dropna().unique().tolist()))
+    categories = st.multiselect("Category", sorted(catalog["event_category"].dropna().unique().tolist()))
+    min_source_count = st.slider("Minimum sources", 0, int(catalog["source_count"].max()), 0)
+    min_stage_count = st.slider("Minimum stages", 0, int(catalog["stage_count"].max()), 0)
+
+filtered_rows = filter_catalog(
+    catalog_rows,
+    query=query,
+    domains=domains,
+    categories=categories,
+    min_source_count=min_source_count,
+    min_stage_count=min_stage_count,
+)
+
+if not filtered_rows:
+    st.warning("No event matches the current filters.")
+    st.stop()
+
+selected_event = st.selectbox(
+    "Selected event",
+    [row["event_id"] for row in filtered_rows],
+    format_func=lambda event_id: f"{event_id} · {catalog.loc[catalog['event_id'] == event_id, 'event_name'].iloc[0]}",
+)
+
+event_row = catalog[catalog["event_id"] == selected_event].iloc[0]
+event_stages = stages[stages["event_id"] == selected_event].sort_values("stage_order")
+summary_row = summary[summary["event_id"] == selected_event]
+
+tabs = st.tabs(["Catalog", "Event detail", "Timeline", "Stages", "FinalCascade JSON", "Release boundary"])
+
+with tabs[0]:
+    st.subheader(f"Event catalog: {len(filtered_rows)} of {len(catalog_rows)} events")
+    st.dataframe(_select_columns(catalog[catalog["event_id"].isin([row["event_id"] for row in filtered_rows])], CATALOG_COLUMNS), use_container_width=True, height=520)
+
+with tabs[1]:
+    st.subheader(str(event_row.get("event_name", selected_event)))
+    st.write(str(event_row.get("short_description", "")))
+    c1, c2, c3, c4 = st.columns(4)
+    c1.metric("Domain", str(event_row.get("domain", "")))
+    c2.metric("Category", str(event_row.get("event_category", "")))
+    c3.metric("Sources", int(event_row.get("source_count", 0)))
+    c4.metric("Stages", int(event_row.get("stage_count", 0)))
+    if not summary_row.empty:
+        st.markdown("#### Public FinalCascade summary")
+        st.dataframe(summary_row, use_container_width=True)
+
+with tabs[2]:
+    figure = build_timeline_figure(_as_records(event_stages), selected_event)
+    if figure is None:
+        st.warning("No public stage rows are available for this event.")
+    else:
+        st.plotly_chart(figure, use_container_width=True)
+    if "gantt_html_path" in event_row and event_row.get("gantt_html_path"):
+        st.markdown(f"Gantt HTML artifact path: `{event_row.get('gantt_html_path')}`")
+
+with tabs[3]:
+    st.dataframe(event_stages, use_container_width=True, height=520)
+
+with tabs[4]:
+    graph = load_event_graph(selected_event)
+    st.download_button(
+        "Download selected public FinalCascade JSON",
+        data=json.dumps(graph, ensure_ascii=False, indent=2),
+        file_name=f"{selected_event}_finalcascade_public.json",
+        mime="application/json",
+    )
+    st.json(graph, expanded=False)
+
+with tabs[5]:
+    st.markdown(
+        f"""
+### Release boundary
+
+- Public dataset repo: [`{PUBLIC_DATASET_REPO}`](https://huggingface.co/datasets/{PUBLIC_DATASET_REPO})
+- Manual-gated Gold companion: [`{GOLD_COMPANION_REPO}`](https://huggingface.co/datasets/{GOLD_COMPANION_REPO})
+- This Explorer loads public event metadata, public stages, public sanitized FinalCascade records, and public visualization paths.
+- It does not load gated Gold references.
+- Public FinalCascade and Gantt views are supplementary inspection assets, not official scoring references.
+"""
+    )

requirements.txt

@@ -0,0 +1,5 @@
+streamlit>=1.36
+pandas>=2.0
+pyarrow>=14.0
+plotly>=5.20
+huggingface_hub>=0.23

src/h2epr_explorer/__init__.py

@@ -0,0 +1,2 @@
+"""Support modules for the H2EPR-Bench Explorer Space."""
+

src/h2epr_explorer/constants.py

@@ -0,0 +1,29 @@
+PUBLIC_DATASET_REPO = "AgenticFinLab/H2EPR-Bench"
+GOLD_COMPANION_REPO = "AgenticFinLab/H2EPR-Bench-Gold"
+LOCAL_DATASET_ENV = "H2EPR_EXPLORER_LOCAL_DATASET_DIR"
+
+CATALOG_PARQUET = "data/viewer_mirrors/event_catalog.parquet"
+CATALOG_JSONL = "data/event_catalog.jsonl"
+STAGES_PARQUET = "data/viewer_mirrors/event_stages.parquet"
+STAGES_JSONL = "data/event_stages.jsonl"
+FINALCASCADE_JSONL = "data/finmycelium_finalcascade_public.jsonl"
+FINALCASCADE_SUMMARY_PARQUET = "data/viewer_mirrors/finalcascade_summary.parquet"
+
+RELEASE_BOUNDARY_NOTICE = (
+    "Official scoring uses the manual-gated Gold companion repository. "
+    "Public FinalCascade and Gantt views are supplementary inspection assets, "
+    "not official scoring references."
+)
+
+CATALOG_COLUMNS = [
+    "event_id",
+    "event_name",
+    "domain",
+    "event_category",
+    "short_description",
+    "keywords",
+    "source_count",
+    "stage_count",
+    "gantt_html_path",
+]
+

src/h2epr_explorer/data_loader.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from .constants import (
+    CATALOG_JSONL,
+    CATALOG_PARQUET,
+    FINALCASCADE_JSONL,
+    FINALCASCADE_SUMMARY_PARQUET,
+    LOCAL_DATASET_ENV,
+    PUBLIC_DATASET_REPO,
+    STAGES_JSONL,
+    STAGES_PARQUET,
+)
+
+
+class SimpleTable:
+    """Small fallback table used when pandas is unavailable in local checks."""
+
+    def __init__(self, rows: list[dict[str, Any]]):
+        self._rows = rows
+
+    def __len__(self) -> int:
+        return len(self._rows)
+
+    def to_dict(self, orient: str = "records") -> list[dict[str, Any]]:
+        if orient != "records":
+            raise ValueError("SimpleTable only supports orient='records'")
+        return list(self._rows)
+
+
+def _as_local_root(local_dataset_dir: Path | str | None = None) -> Path | None:
+    value = local_dataset_dir or os.environ.get(LOCAL_DATASET_ENV)
+    if not value:
+        return None
+    return Path(value).expanduser().resolve()
+
+
+def resolve_dataset_file(filename: str, local_dataset_dir: Path | str | None = None) -> Path:
+    local_root = _as_local_root(local_dataset_dir)
+    if local_root is not None:
+        path = (local_root / filename).resolve()
+        if not path.is_relative_to(local_root):
+            raise ValueError(f"Refusing to read outside local dataset root: {filename}")
+        if not path.exists():
+            raise FileNotFoundError(path)
+        return path
+
+    from huggingface_hub import hf_hub_download
+
+    return Path(
+        hf_hub_download(
+            repo_id=PUBLIC_DATASET_REPO,
+            repo_type="dataset",
+            filename=filename,
+        )
+    )
+
+
+def load_jsonl_rows(filename: str, local_dataset_dir: Path | str | None = None) -> list[dict[str, Any]]:
+    path = resolve_dataset_file(filename, local_dataset_dir=local_dataset_dir)
+    rows: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if line:
+                rows.append(json.loads(line))
+    return rows
+
+
+def read_event_graph_from_jsonl(
+    event_id: str, local_dataset_dir: Path | str | None = None
+) -> dict[str, Any]:
+    path = resolve_dataset_file(FINALCASCADE_JSONL, local_dataset_dir=local_dataset_dir)
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            if not line.strip():
+                continue
+            row = json.loads(line)
+            if row.get("event_id") == event_id:
+                return row
+    raise KeyError(f"Event graph not found: {event_id}")
+
+
+def _read_table(filename: str, fallback_jsonl: str, local_dataset_dir: Path | str | None = None):
+    pd = None
+    try:
+        import pandas as pandas_module
+
+        pd = pandas_module
+    except ImportError:
+        pass
+    try:
+        path = resolve_dataset_file(filename, local_dataset_dir=local_dataset_dir)
+        if pd is None:
+            raise ImportError("pandas is unavailable")
+        return pd.read_parquet(path)
+    except (FileNotFoundError, ImportError, ValueError):
+        rows = load_jsonl_rows(fallback_jsonl, local_dataset_dir=local_dataset_dir)
+        if pd is None:
+            return SimpleTable(rows)
+        return pd.DataFrame(rows)
+
+
+@lru_cache(maxsize=1)
+def load_catalog():
+    return _read_table(CATALOG_PARQUET, CATALOG_JSONL)
+
+
+@lru_cache(maxsize=1)
+def load_stages():
+    return _read_table(STAGES_PARQUET, STAGES_JSONL)
+
+
+@lru_cache(maxsize=1)
+def load_finalcascade_summary():
+    return _read_table(FINALCASCADE_SUMMARY_PARQUET, CATALOG_JSONL)
+
+
+@lru_cache(maxsize=128)
+def load_event_graph(event_id: str) -> dict[str, Any]:
+    return read_event_graph_from_jsonl(event_id)

src/h2epr_explorer/filters.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+SEARCH_FIELDS = ("event_id", "event_name", "short_description", "domain", "event_category", "keywords")
+
+
+def _contains_query(row: dict[str, Any], query: str) -> bool:
+    if not query:
+        return True
+    needle = query.casefold()
+    return any(needle in str(row.get(field, "")).casefold() for field in SEARCH_FIELDS)
+
+
+def filter_catalog(
+    rows: Iterable[dict[str, Any]],
+    *,
+    query: str = "",
+    domains: list[str] | None = None,
+    categories: list[str] | None = None,
+    min_source_count: int = 0,
+    min_stage_count: int = 0,
+) -> list[dict[str, Any]]:
+    domain_set = set(domains or [])
+    category_set = set(categories or [])
+    filtered: list[dict[str, Any]] = []
+    for row in rows:
+        if domain_set and row.get("domain") not in domain_set:
+            continue
+        if category_set and row.get("event_category") not in category_set:
+            continue
+        if int(row.get("source_count") or 0) < min_source_count:
+            continue
+        if int(row.get("stage_count") or 0) < min_stage_count:
+            continue
+        if not _contains_query(row, query):
+            continue
+        filtered.append(row)
+    return filtered
+

src/h2epr_explorer/render_gantt.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _is_known_time(value: Any) -> bool:
+    return bool(value) and str(value).strip().lower() not in {"unknown", "none", "nan", "nat"}
+
+
+def prepare_gantt_rows(stage_rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    ordered = sorted(stage_rows, key=lambda row: (int(row.get("stage_order") or 0), str(row.get("stage_id", ""))))
+    prepared: list[dict[str, Any]] = []
+    for fallback_index, row in enumerate(ordered, start=1):
+        start = row.get("stage_start_time")
+        end = row.get("stage_end_time")
+        if _is_known_time(start) and _is_known_time(end):
+            display_start = start
+            display_end = end
+            axis_mode = "calendar"
+        else:
+            display_start = int(row.get("stage_order") or fallback_index)
+            display_end = display_start + 0.85
+            axis_mode = "relative_order"
+
+        time_note = row.get("temporal_anchor_summary") or ""
+        if not time_note and int(row.get("known_action_time_anchor_count") or 0) > 0:
+            time_note = "Action-level time anchors available"
+
+        prepared.append(
+            {
+                **row,
+                "display_start": display_start,
+                "display_end": display_end,
+                "axis_mode": axis_mode,
+                "time_note": time_note,
+            }
+        )
+    return prepared
+
+
+def build_timeline_figure(stage_rows: list[dict[str, Any]], event_id: str):
+    import pandas as pd
+    import plotly.express as px
+
+    prepared = prepare_gantt_rows(stage_rows)
+    if not prepared:
+        return None
+
+    frame = pd.DataFrame(prepared)
+    if set(frame["axis_mode"]) == {"calendar"}:
+        fig = px.timeline(
+            frame,
+            x_start="display_start",
+            x_end="display_end",
+            y="stage_label_public",
+            color="stage_label_public",
+            hover_data=["stage_id", "stage_order", "time_note"],
+            title=f"{event_id}: public stage timeline",
+        )
+        fig.update_yaxes(autorange="reversed")
+        return fig
+
+    fig = px.bar(
+        frame,
+        x=[row["display_end"] - row["display_start"] for row in prepared],
+        y="stage_label_public",
+        base="display_start",
+        orientation="h",
+        color="stage_label_public",
+        hover_data=["stage_id", "stage_order", "time_note"],
+        title=f"{event_id}: relative stage order",
+    )
+    fig.update_yaxes(autorange="reversed")
+    fig.update_layout(xaxis_title="Relative stage order")
+    return fig
+