Model or dataset
retentioneering/retentioneering-tools avatar
retentioneering/retentioneering-tools

Retentioneering 5.x rebuilt the eventstream on DuckDB, kept the old engine on a branch, and ships telemetry on by default

Python toolkit, MCP server, and agent skills for reproducible, auditable clickstream and event log analytics. Helps AI agents, data scientists and analysts build, validate, and cross-check product analytics, quantitative UX, customer journeys, graph-based user flows, behavioral segmentation, A/B tests, process mining models, Markov chain simulation

947 stars144 forksPythonApache-2.0

At a glance

What is it?
An Apache-2.0 Python toolkit for clickstream and event log analytics, with interactive user-flow widgets, headless data twins, an MCP server and agent skills. The interesting parts are what the 5.0 rewrite dropped, what defaults ships with, and how releases still get cut by hand.
Who is it for?
Retentioneering is worth a look if you already have timestamped event data and want funnel analysis that shows the routes users actually took, especially when reproducibility matters more than a hosted dashboard.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • retentioneering/retentioneering-tools947 ★ · +29
Star history
Repository2026-09-122026-11-15
retentioneering/retentioneering-tools918947

29 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Version 5.0 was a rewrite, and 3.x still lives on its own branch

The jump to 5.0 replaced the engine rather than extending it. The 3.x line ran on pandas and pulled its widgets from a CDN; 5.x swaps in a DuckDB-backed `Eventstream`, a new generation of widgets built on the open-source anywidget library, and an MCP server that lets an LLM agent run analyses against your eventstream. The previous engine is not gone, it sits on a `3.x` branch, and the full 3.3.0 to 5.0 delta is written up in `CHANGELOG.md`. This pass also open-sourced the widget front end and invites outside help on it. What is missing is any deprecation schedule for the old branch, and the project asks you to open issues or pull requests for features you want carried over.

Three columns to start, and a bundled dataset if you have none

Input is deliberately narrow. An `Eventstream` wants a DataFrame with three columns: a path identifier, an event name, and a timestamp. If your column names differ, you pass a schema. Beyond that the toolkit takes what you already have, a DataFrame, CSV, TSV, Parquet, or a custom export from BigQuery, ClickHouse or another event database. Installation is a single pip line, and Python 3.10 or newer is the floor:

bash
pip install retentioneering

For a first look without your own data, a synthetic e-commerce stream is bundled:

python
import retentioneering as rete

ecom = rete.datasets.load_ecom()

# Build a funnel
ecom.funnel(steps=["catalog", "add_to_cart", "purchase"])

# Compare two segments in one picture (diff mode) with transition graph
ecom.transition_graph(diff=["platform", "mobile", "desktop"])

Event data stays local, and usage telemetry is on by default

Two claims sit next to each other and pull in different directions. The project states that analyses run in your own environment and that your raw and analysed event data never leaves your machine, backing that with widgets rendered locally rather than through a hosted platform. In the same description it says anonymous product telemetry, used to understand overall tool usage and improve the toolkit, may be enabled by default and can be disabled at any time. So the locality guarantee covers event data and not usage data, and the second channel is active unless someone turns it off. That is an ordinary trade for a commercially backed open-source tool, but it belongs next to the privacy sentence rather than buried after it, and the quick start does not name a setting for it.

Every widget has a headless twin returning a DataFrame or a dict

Interactive output is not the only output. Each widget has a data twin, so a transition graph hands back a DataFrame and a funnel hands back a plain dict, which is what makes a result reproducible instead of something you read off a rendered cell. The edge weight is selectable, with `edge_weight="proba_out"` as the named option in the example. The same idea runs through the widget set: diff mode exists in every widget so two segments can be overlaid in one picture, and the six named views are Transition Graph, Step Matrix, Step Sankey, Funnel, Segment Overview and Cluster Analysis. Multi-resolution is handled by the same graph and matrix methods, which can operate on raw events or on higher-level units such as sessions, feature-use episodes or lifecycle stages.

Processors chain and never mutate the stream you loaded

Cleaning is a chain of calls, and the original object is left alone. Every processor returns a new `Eventstream`, which is what lets you keep comparing a cleaned view against the raw one:

python
clean = (
    stream
    .filter_events(drop={"event": ["bot_ping"]})
    .collapse_events(loops=True)
    .split_sessions(timeout="30m")
)
clean.step_matrix(path_pattern="add_to_cart->.*->purchase")

Three transformations in four lines: drop a noisy event, fold repeats into one, and cut sessions at a thirty minute gap. The step matrix call then narrows to paths that pass through add_to_cart and finish at purchase, expressed as a pattern over the path rather than a hand-built list.

Building from source needs Node in three subdirectories

Installing the published package is one command. Producing it from a clean checkout is not, because the widgets are built from a JavaScript tree that sits in the repository. `make install` runs `uv sync` and then `cd js && npm install`, and the build splits by package: `cd js/viz-core && npm run build` for the visualization core, `cd js/widget && npm run build` for the widget itself. The widget target first regenerates a TypeScript file of metric names with `uv run python scripts/export_metric_schema.py`, so the generated list cannot go stale between a change to the metric schema and the next build. Tests run through `uv run python -m pytest tests/ -v`, and `make install-dev` adds `uv run pre-commit install` for contributors only. One detail in `clean` is deliberate: it deletes the built widget bundles and node_modules but leaves `widget.css`, because that stylesheet is checked in as source and the JavaScript build never regenerates it.

Merging to master does not cut a release, only a v tag does

Releases are a manual step with a documented order. The Makefile states that `master` is protected and takes pull requests only, and that merging into it does not trigger a release; only pushing a `v*` tag does, through `release.yml`. The procedure is to bump the version in `pyproject.toml`, turn the `[Unreleased]` heading of `CHANGELOG.md` into a version and date, land that as a normal pull request, and only then run `make release VERSION=5.1.0`. That worked example sits well behind what the project now publishes: the current version in `pyproject.toml` is 5.2.3, and tags 5.2.1, 5.2.2 and 5.2.3 all landed within about ten days of each other. Three tags in that window is a release cadence that only holds if the changelog step is never skipped.

Apache-2.0 code sits next to COMMERCIAL.md and a gmail contact

The root of the tree is unusually loud about what this project is. A `LICENSE` file, a `NOTICE` file and a `COMMERCIAL.md` sit at the top level, next to `AGENTS.md`, `CLAUDE.md`, a `.claude/` directory and a `.agents/` directory, so instructions aimed at agents and at commercial questions are versioned in the same place as the code. The `pyproject.toml` names one author, the Retentioneering User Trajectory Analysis Lab, with a gmail address as its contact, declares the package `Development Status :: 5 - Production/Stable`, and requires Python 3.10 or newer. Repository hygiene is checked in as well, with `.gitleaks.toml`, a pre-commit configuration and a `.git-blame-ignore-revs` file for the reformatting commits that would otherwise pollute history.

Editorial conclusion

Retentioneering is worth a look if you already have timestamped event data and want funnel analysis that shows the routes users actually took, especially when reproducibility matters more than a hosted dashboard. Check three things first: whether the anonymous usage telemetry being on by default fits your environment, whether the features you relied on in 3.x made it across the rewrite or only exist as an open issue, and whether your column names fit the path, event and timestamp shape or need a schema. Building from source also means Node in three subdirectories, and cutting a release is a manual tag rather than a side effect of merging.

Frequently asked questions

What does Retentioneering need to build an Eventstream?

A DataFrame with three columns: a path identifier, an event name and a timestamp. Different column names need a schema passed in. CSV, TSV, Parquet files and custom exports from BigQuery or ClickHouse are also accepted as input.

Is Retentioneering a hosted service?

No. It runs in your own environment and renders its widgets in Jupyter, Google Colab, Cursor, VS Code, Codex, Claude Code or another Python-compatible environment. Analyses, visualizations and simulated interventions export into shareable HTML reports.

Does Retentioneering send my event data to a server?

The project states the analysis runs locally and that raw and analysed event data never leaves your machine. Separate from that, anonymous product telemetry about overall tool usage may be enabled by default and can be disabled at any time.

What changed in Retentioneering 5.0?

The pandas engine and CDN-loaded widgets of 3.x were replaced by a DuckDB-backed `Eventstream`, anywidget-based widgets and an MCP server for agents. The 3.x engine still lives on the `3.x` branch, and the 3.3.0 to 5.0 delta is written up in CHANGELOG.md.

How do I build and test Retentioneering from source?

`make install` runs `uv sync` plus `npm install` inside `js`, and the widget build regenerates metric names first through `uv run python scripts/export_metric_schema.py`. `make test` runs `uv run python -m pytest tests/ -v`.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. retentioneering/retentioneering-tools on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/retentioneering-retentioneering-tools.svg)](https://hysenlabs.com/projects/retentioneering-retentioneering-tools)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/retentioneering-retentioneering-tools.svg)](https://hysenlabs.com/projects/retentioneering-retentioneering-tools)

Was this useful?