retentioneering-tools: Instructions file for Codex

AGENTS.md

Guidance for coding agents (Claude Code, Codex, Cursor, and others) working in this repository. Claude Code loads this file through the @AGENTS.md import in CLAUDE.md; Claude-specific instructions, if any, go in CLAUDE.md below the import.

Deep context lives in the Architecture Decision Records — see docs/adr/README.md for the index. Load the ADRs relevant to your task; ADR-0002 (DuckDB replacement scan, now superseded by engine.py — see below) documents why some historical code still carries # noqa: F841 comments on variables that look unused.

Project background

retentioneering 5.x is a ground-up rewrite of the 3.3.0 engine: the pandas-based Eventstream and the iframe/CDN-loaded widgets were replaced with a DuckDB-backed Eventstream and anywidget-based Jupyter widgets. The 3.x branch preserves the legacy engine for reference and patches. CHANGELOG.md's [5.0.0] entry documents the full delta vs. 3.3.0, including removed/added/renamed Eventstream methods and the 5.0 naming conventions. docs/ (guide pages, generated reference, ADRs) describes the current API.

Known gaps vs. 3.3.0 (deliberately not carried over, may return later — ADR-0012): the interactive Preprocessing Graph (visual no-code pipeline builder), and the Cohorts, StatTests, Sequences tools.

Commands

uv sync                    # install Python deps (+ dev group: pytest, ruff, pre-commit)
cd js && npm install       # install JS deps (npm workspaces: viz-core, widget)
# or: make install         # does both

make build                 # build JS and drop widget.js/widget-static.js into src/retentioneering/static/
make watch                 # vite --watch for js/widget, for iterating on widget UI

uv run pytest tests/ -v                          # full test suite
uv run pytest tests/data_processors/add_events_test.py -v          # single file
uv run pytest tests/data_processors/add_events_test.py::test_name -v   # single test
# or: make test            # full suite only
npm test --prefix js/widget                      # JS unit tests (node:test via esbuild)

uv run pre-commit run --all-files    # ruff (lint+format) + gitleaks + hygiene hooks
uv run pre-commit install            # one-time, makes hooks run automatically on `git commit`
# or: make install-dev      # = make install + the pre-commit install line above

uv run python docs/scripts/render_pages.py           # regenerate reference docs from docstrings
uv run python docs/scripts/generate_widget_demos.py  # regenerate static widget demos

uv build                   # sdist + wheel; requires `make build` to have run first so the
                            # JS bundle exists on disk (hatchling force-includes it via
                            # [tool.hatch.build] artifacts in pyproject.toml even though
                            # it's gitignored)