retentioneering 5.0.0rc3

What is Retentioneering?

Retentioneering is a Python library for behavioral analytics on event data: clickstreams, product event logs, user paths. Where funnels tell you what happened, retentioneering shows how users actually behave — real paths to conversion, loops and dead ends, behavioral segments, and the differences in behavior between any two groups of users.

Retentioneering is code-first and quickest way from raw data into detailed views and product insights. With average python knowledge you can quickly identify what can be improved in the website, application or chats interactions by finding and isolating specific patterns of different users at multiple scales - session to session and within each session or its pieces.

It runs on your raw data (a pandas DataFrame or CSV is enough), and renders interactive widgets right in Jupyter, Cursor or whatever IDE you prefer — no SaaS, no data leaving your machine.

Retentioneering-tools Version 5.0 is a ground-up rewrite. The pandas engine and CDN-loaded widgets of 3.x were replaced with a much faster DuckDB-backed Eventstream, a new generation of open-source anywidget-based widgets, and an MCP server that lets LLM agents run analyses on your eventstream. See CHANGELOG.md for the full 3.3.0 → 5.0 delta; the legacy 3.x engine lives on the 3.x branch.

With this update we also include the opensource code for widgets front, and we highly encourage for the collaboration in its further development.

Regarding migrations of any features from 3.x to next release of 5.x please feel free to open new issues or pull requests in this repo, we will focus on faster development of useful features and ideas based on your engagement.

Documentation

Complete documentation is available at https://retentioneering.com/docs.

Installation

Python 3.11+ is required.

pip install retentioneering

Or directly from a Jupyter (Lab, Notebook, Desktop) / Google Colab / VS Code:

!pip install retentioneering

Quick start

All you need is a DataFrame with three columns: a path identifier, an event name, and a timestamp. (Different column names? Pass a schema.)

import pandas as pd
import retentioneering as rete

df = pd.read_csv("events.csv")   # columns: user_id, event, timestamp
stream = rete.Eventstream(df)

stream.transition_graph()        # interactive behavior graph, right in the notebook

No data at hand? Use the bundled synthetic e-commerce dataset:

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"])

Clean and shape the data by chaining data processors — every step returns a new Eventstream, the original is never modified:

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

Need raw numbers instead of a widget? Every widget has a headless twin:

tm = stream.transition_graph_data(edge_weight="proba_out")   # DataFrame
funnel = stream.funnel_data(steps=["catalog", "add_to_cart", "purchase"])  # dict

What's inside

• Interactive widgets for in-depth analysis of user behavior:
  • Transition Graph,
  • Step Matrix,
  • Step Sankey,
  • Funnel,
  • Segment Overview,
  • Cluster Analysis.
• Diff mode in every widget — overlay two segments to see how behavior differs, not just that a metric moved.
• Data processors — chainable methods for filtering events and paths, sessionization, collapsing events, adding synthetic events (including churn markers), segments, URL parsing, daily lifecycle states, sampling, etc.
• Path metrics — one registry of per-path metrics that feeds behavioral clustering, segment comparison, path filtering, and your own ML feature pipelines.
• MCP server — exposes the eventstream to Claude or any MCP client: agents explore the data, build report tabs, and export a validated interactive HTML report where every number links to its source.

Contributing

This is a community-driven open source project in active development. Any contributions — bug reports, documentation improvements, examples, visualizations, analytical recipes, integrations, performance improvements, API proposals, widgets improvements, new agent skills and prompt libraries, new analytical capabilities — are very welcome. See CONTRIBUTING.md for the local development setup. Please feel free to contact us at retentioneering@gmail.com if you have any questions regarding this repo.

Apps are better with math, join us! :)

License and commercial model

Retentioneering-tools is open-source software licensed under the Apache License, Version 2.0.

Retentioneering is a community research laboratory dedicated to developing new analytics methodology and opensource tools.

Copyright retentioneering-tools v.5.0 Maxim Godzi, Vladimir Kukushkin and Anatoly Zaytsev. Updates may include software developed by the Retentioneering community.

You are free to use, modify, distribute, and build commercial products with Retentioneering-tools, subject to the terms of the Apache-2.0 license.

Other Retentioneering libraries, packages and managed execution services, enterprise integrations, premium diagnostic workflows, hosted collaboration features are separate proprietary products and are governed by their respective commercial terms. Additional details provided in COMMERCIAL.md.

The Apache-2.0 license applies only to the source code and assets distributed in this repository. It does not grant rights to use the Retentioneering name, logo, trademarks, hosted services, proprietary cloud infrastructure, or commercial content that is not distributed in this repository.

We welcome contributions from individuals and organizations. Contributions to Retentioneering-tools are accepted under the contribution terms described in CONTRIBUTING.md.

Our goal is to keep the core analytical language and ecosystem open, extensible, and useful for independent analysts, researchers, startups, and enterprise teams, while funding long-term maintenance through optional commercial products and services.