seq-explorer 0.1.0__tar.gz

seq_explorer-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seq_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: seq-explorer
+Version: 0.1.0
+Summary: Visualize hidden state evolution in sequence models
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>=2.4.2
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: plotly>=6.5.2
+Requires-Dist: polars>=1.38.1
+Requires-Dist: streamlit>=1.54.0
+Requires-Dist: torch>=2.10.0
+Provides-Extra: dev
+Requires-Dist: isort>=7.0.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.7.1; extra == "dev"
+Requires-Dist: mkdocs-table-reader-plugin>=3.1.0; extra == "dev"
+Requires-Dist: mkdocstrings-python>=2.0.2; extra == "dev"
+Requires-Dist: pre-commit>=4.5.1; extra == "dev"
+Requires-Dist: pymdown-extensions>=10.20.1; extra == "dev"
+Requires-Dist: ruff>=0.15.1; extra == "dev"
+Dynamic: license-file
+
+# Sequence Explorer
+
+Interactive Streamlit dashboard for visualizing how a sequence model's hidden state evolves over transaction sequences. Works with **any PyTorch RNN** (GRU, LSTM, RNN) with **any number of layers**.
+
+## Two Ways to Use
+
+### As a Package (pip install)
+
+```bash
+pip install seq-explorer
+```
+
+**In Python/Notebooks:**
+```python
+from seq_explorer import SequenceTrace
+
+trace = SequenceTrace.from_arrays(...)
+```
+
+**Run dashboard:**
+```bash
+streamlit run src/seq_explorer/app.py
+```
+
+### As a Project (clone & run)
+
+```bash
+git clone https://github.com/chris-santiago/seq-explorer
+cd seq-explorer
+uv sync
+uv run python src/seq_explorer/build_cache.py dataframe your_data.csv -o cache.parquet
+uv run streamlit run src/seq_explorer/app.py
+```
+
+## What it shows
+
+- **Model score timeline** — running P(fraud) at every timestep, color-coded green → red
+- **Hidden state heatmap** — per-neuron activations across the sequence (any number of layers)
+- **Hidden state norms** — L2 norm over time for all layers, plus rate-of-change bars
+- **Top-k neuron drill-down** — neurons most correlated with the fraud score, traced over time
+- **Layer similarity** — cosine similarity between consecutive hidden state layers
+- **Raw features table** — the actual transaction data, highlighted at the selected timestep
+- **Metadata overlays** — visualize categorical/numeric metadata on timelines (e.g., risk tiers, channels)
+- **Timestep scrubber** — linked across all panels for synchronized inspection
+
+## Quick Start
+
+```bash
+# Install dependencies
+uv sync
+
+# Build cache from CSV/Parquet (auto-detects schema)
+uv run python src/seq_explorer/build_cache.py dataframe your_data.csv -o cache.parquet
+
+# Launch dashboard
+uv run streamlit run src/seq_explorer/app.py
+```
+
+The dashboard auto-detects hidden state columns - just use any prefix pattern like `h0_*, h1_*` or `encoder_*, decoder_*`.
+
+## Usage Options
+
+### Option 1: Construct + Plot Directly in Jupyter (Simplest!)
+
+No need to save files or run Streamlit. Just use the plotting functions:
+
+```python
+from seq_explorer import (
+    SequenceTrace,
+    fraud_score_timeline,
+    hidden_state_heatmap,
+    hidden_norm_plot,
+    top_neuron_traces,
+    layer_similarity_plot,
+    raw_feature_heatmap,
+    feature_fraud_correlation,
+    metadata_timeline_overlay,
+)
+
+trace = SequenceTrace.from_arrays(
+    sequence_id=0,
+    label=1,
+    raw_features=my_features,        # (seq_len, n_features)
+    feature_names=['amount', ...],
+    hidden_states=[h0, h1],         # list of (seq_len, hidden_dim)
+    running_fraud_scores=scores,    # (seq_len,)
+)
+
+# All plotting functions return Plotly figures - show them inline!
+fraud_score_timeline(trace.running_fraud_scores).show()
+hidden_state_heatmap(trace.hidden_states[0]).show()
+hidden_norm_plot(trace.hidden_norms).show()
+top_neuron_traces(
+    trace.hidden_states[0],
+    trace.top_neuron_indices[0],
+    trace.top_neuron_correlations[0]
+).show()
+```
+
+### Option 2: Construct + Save + Dashboard
+
+```python
+# Save to Parquet
+df = SequenceTrace.to_dataframe({0: trace})
+df.write_parquet('cache.parquet')
+
+# Launch dashboard
+streamlit run src/seq_explorer/app.py
+```
+
+### Option 3: From DataFrame
+
+```bash
+python src/seq_explorer/build_cache.py dataframe data.csv -o cache.parquet
+```
+
+### Option 4: From Model
+
+```bash
+python src/seq_explorer/build_cache.py model \
+    --checkpoint model.ckpt \
+    --data transactions.pt \
+    --auto-select \
+    -o cache.parquet
+```
+
+## Model Support
+
+Works with any PyTorch sequence model:
+
+- **GRU** - any number of layers
+- **LSTM** - any number of layers
+- **RNN** - any number of layers
+- Custom architectures with different attribute names (e.g., `encoder`, `rnn_module`)
+
+## Project structure
+
+```
+seq-explorer/
+├── seq_explorer/           # Package + CLI
+│   ├── __init__.py
+│   ├── app.py            # Streamlit dashboard
+│   ├── plots.py          # Plotly figure builders
+│   ├── extractor.py      # Model trace extraction
+│   ├── trace.py          # Data models
+│   └── build_cache.py   # Cache builder CLI
+├── docs/                  # Documentation
+├── demo/                  # Demo notebooks
+└── README.md
+```
+
+## Documentation
+
+See the `docs/` folder for full documentation:
+
+- [Quick Start](docs/quickstart.md)
+- [Dashboard Guide](docs/dashboard.md)
+- [Cache Format](docs/cache-format.md)
+- [Architecture](docs/architecture.md)

seq_explorer-0.1.0/README.md

@@ -0,0 +1,159 @@
+# Sequence Explorer
+
+Interactive Streamlit dashboard for visualizing how a sequence model's hidden state evolves over transaction sequences. Works with **any PyTorch RNN** (GRU, LSTM, RNN) with **any number of layers**.
+
+## Two Ways to Use
+
+### As a Package (pip install)
+
+```bash
+pip install seq-explorer
+```
+
+**In Python/Notebooks:**
+```python
+from seq_explorer import SequenceTrace
+
+trace = SequenceTrace.from_arrays(...)
+```
+
+**Run dashboard:**
+```bash
+streamlit run src/seq_explorer/app.py
+```
+
+### As a Project (clone & run)
+
+```bash
+git clone https://github.com/chris-santiago/seq-explorer
+cd seq-explorer
+uv sync
+uv run python src/seq_explorer/build_cache.py dataframe your_data.csv -o cache.parquet
+uv run streamlit run src/seq_explorer/app.py
+```
+
+## What it shows
+
+- **Model score timeline** — running P(fraud) at every timestep, color-coded green → red
+- **Hidden state heatmap** — per-neuron activations across the sequence (any number of layers)
+- **Hidden state norms** — L2 norm over time for all layers, plus rate-of-change bars
+- **Top-k neuron drill-down** — neurons most correlated with the fraud score, traced over time
+- **Layer similarity** — cosine similarity between consecutive hidden state layers
+- **Raw features table** — the actual transaction data, highlighted at the selected timestep
+- **Metadata overlays** — visualize categorical/numeric metadata on timelines (e.g., risk tiers, channels)
+- **Timestep scrubber** — linked across all panels for synchronized inspection
+
+## Quick Start
+
+```bash
+# Install dependencies
+uv sync
+
+# Build cache from CSV/Parquet (auto-detects schema)
+uv run python src/seq_explorer/build_cache.py dataframe your_data.csv -o cache.parquet
+
+# Launch dashboard
+uv run streamlit run src/seq_explorer/app.py
+```
+
+The dashboard auto-detects hidden state columns - just use any prefix pattern like `h0_*, h1_*` or `encoder_*, decoder_*`.
+
+## Usage Options
+
+### Option 1: Construct + Plot Directly in Jupyter (Simplest!)
+
+No need to save files or run Streamlit. Just use the plotting functions:
+
+```python
+from seq_explorer import (
+    SequenceTrace,
+    fraud_score_timeline,
+    hidden_state_heatmap,
+    hidden_norm_plot,
+    top_neuron_traces,
+    layer_similarity_plot,
+    raw_feature_heatmap,
+    feature_fraud_correlation,
+    metadata_timeline_overlay,
+)
+
+trace = SequenceTrace.from_arrays(
+    sequence_id=0,
+    label=1,
+    raw_features=my_features,        # (seq_len, n_features)
+    feature_names=['amount', ...],
+    hidden_states=[h0, h1],         # list of (seq_len, hidden_dim)
+    running_fraud_scores=scores,    # (seq_len,)
+)
+
+# All plotting functions return Plotly figures - show them inline!
+fraud_score_timeline(trace.running_fraud_scores).show()
+hidden_state_heatmap(trace.hidden_states[0]).show()
+hidden_norm_plot(trace.hidden_norms).show()
+top_neuron_traces(
+    trace.hidden_states[0],
+    trace.top_neuron_indices[0],
+    trace.top_neuron_correlations[0]
+).show()
+```
+
+### Option 2: Construct + Save + Dashboard
+
+```python
+# Save to Parquet
+df = SequenceTrace.to_dataframe({0: trace})
+df.write_parquet('cache.parquet')
+
+# Launch dashboard
+streamlit run src/seq_explorer/app.py
+```
+
+### Option 3: From DataFrame
+
+```bash
+python src/seq_explorer/build_cache.py dataframe data.csv -o cache.parquet
+```
+
+### Option 4: From Model
+
+```bash
+python src/seq_explorer/build_cache.py model \
+    --checkpoint model.ckpt \
+    --data transactions.pt \
+    --auto-select \
+    -o cache.parquet
+```
+
+## Model Support
+
+Works with any PyTorch sequence model:
+
+- **GRU** - any number of layers
+- **LSTM** - any number of layers
+- **RNN** - any number of layers
+- Custom architectures with different attribute names (e.g., `encoder`, `rnn_module`)
+
+## Project structure
+
+```
+seq-explorer/
+├── seq_explorer/           # Package + CLI
+│   ├── __init__.py
+│   ├── app.py            # Streamlit dashboard
+│   ├── plots.py          # Plotly figure builders
+│   ├── extractor.py      # Model trace extraction
+│   ├── trace.py          # Data models
+│   └── build_cache.py   # Cache builder CLI
+├── docs/                  # Documentation
+├── demo/                  # Demo notebooks
+└── README.md
+```
+
+## Documentation
+
+See the `docs/` folder for full documentation:
+
+- [Quick Start](docs/quickstart.md)
+- [Dashboard Guide](docs/dashboard.md)
+- [Cache Format](docs/cache-format.md)
+- [Architecture](docs/architecture.md)

seq_explorer-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "seq-explorer"
+version = "0.1.0"
+description = "Visualize hidden state evolution in sequence models"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=2.4.2",
+    "pandas>=2.3.3",
+    "plotly>=6.5.2",
+    "polars>=1.38.1",
+    "streamlit>=1.54.0",
+    "torch>=2.10.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "isort>=7.0.0",
+    "mkdocs-material>=9.7.1",
+    "mkdocs-table-reader-plugin>=3.1.0",
+    "mkdocstrings-python>=2.0.2",
+    "pre-commit>=4.5.1",
+    "pymdown-extensions>=10.20.1",
+    "ruff>=0.15.1",
+]
+
+[project.scripts]
+seq-explorer-build = "seq_explorer.build_cache:main"
+
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"

seq_explorer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

seq_explorer-0.1.0/src/seq_explorer/__init__.py

@@ -0,0 +1,41 @@
+"""
+Sequence Explorer - Visualize hidden state evolution in sequence models.
+
+Usage:
+    from seq_explorer import SequenceTrace
+    from seq_explorer import fraud_score_timeline, hidden_state_heatmap, ...
+
+    trace = SequenceTrace.from_arrays(...)
+
+To run the dashboard:
+    streamlit run seq_explorer/app.py
+"""
+
+from seq_explorer.plots import (
+    feature_fraud_correlation,
+    feature_snapshot_bar,
+    fraud_score_timeline,
+    hidden_norm_plot,
+    hidden_state_heatmap,
+    layer_similarity_plot,
+    metadata_timeline_overlay,
+    norm_delta_plot,
+    raw_feature_heatmap,
+    top_neuron_traces,
+)
+from seq_explorer.trace import SequenceTrace
+
+__version__ = "0.1.0"
+__all__ = [
+    "SequenceTrace",
+    "fraud_score_timeline",
+    "hidden_state_heatmap",
+    "hidden_norm_plot",
+    "norm_delta_plot",
+    "top_neuron_traces",
+    "layer_similarity_plot",
+    "raw_feature_heatmap",
+    "feature_fraud_correlation",
+    "feature_snapshot_bar",
+    "metadata_timeline_overlay",
+]