About this project

Retentioneering is a Python‑based, open‑source toolkit designed for reproducible, auditable analytics on clickstream and event‑log data. It replaces ad‑hoc scripts with tested analytical primitives and reusable workflows, helping analysts, data scientists, and AI agents explore user journeys, discover behavioral segments, evaluate experiments, and cross‑check results. Key components: - **Eventstream**: a DuckDB‑backed object that ingests raw event data from pandas DataFrames, CSV/TSV/Parquet files, or database exports. It supports filtering, sessionisation, event collapsing, synthetic event creation, and other chainable processors, always returning a new immutable stream. - **Interactive widgets**: built with anywidget, they render directly in Jupyter, Colab, VS Code, etc. Widgets include Transition Graph, Step Matrix, Step Sankey, Funnel, Segment Overview, and Cluster Analysis, all with a diff mode to compare cohorts. - **Data processors**: methods for filtering events, splitting sessions, adding churn markers, parsing URLs, lifecycle state extraction, sampling, and more, enabling multi‑resolution analysis from seconds‑long interactions to months‑long journeys. - **MCP server**: exposes the Eventstream to Claude or any MCP‑compatible LLM client. Agents can run analyses, generate report tabs, and export validated interactive HTML reports where every metric links back to its source data. - **Headless APIs**: each widget has a data‑only counterpart (e.g., `transition_graph_data`, `funnel_data`) for programmatic consumption. Installation is straightforward with Python 3.10+: ```bash pip install retentioneering ``` A quick start loads a CSV with three columns (user_id, event, timestamp), creates an `Eventstream`, and calls `stream.transition_graph()` to display an interactive graph. The toolkit ships with a synthetic e‑commerce dataset for experimentation, and all visualisations can be exported as shareable HTML reports. Raw data never leaves the local environment; optional telemetry can be disabled. Retentioneering 5.0 is a ground‑up rewrite that replaces the previous pandas engine with a faster DuckDB backend and modern anywidget widgets. Documentation, examples, and a community Discord/Telegram are available at https://retentioneering.com/docs. The project is licensed under Apache‑2.0, encouraging free use, modification, and commercial distribution of the core library. Contributions are welcomed via GitHub issues and pull requests.