ClusterAudienceKit

Problem

RFM segmentation, clustering, churn scoring, and CLV estimation for a customer base usually means stitching together several separate tools (scikit-learn for clustering, a hand-rolled RFM script, a separate churn model), each with its own performance ceiling on a large transaction table.

Solution

A Rust-powered customer segmentation engine with Python bindings.

RFM analysis, KMeans/K-Prototypes clustering, churn prediction, customer lifetime value, SQL export to 8 warehouse dialects, differential privacy / k-anonymity, real-time streaming segmentation, drift detection, lookalike audiences, cohort analytics, lifecycle tracking, rule-based behavioral segmentation, and segment profiling — all real, tested, and callable from Python today.

Use cases

• Building a marketing segmentation pipeline on a large transaction table where scikit-learn's Python-level clustering is the bottleneck — the Rust core is rayon-parallelized and deterministic for a given seed.
• Exporting customer segments directly into a warehouse — export_segment_sql generates injection-safe SQL for 8 dialects rather than hand-writing per- warehouse export scripts.
• Privacy-constrained segmentation — differential privacy (Laplace/ Gaussian noise) and k-anonymity suppression/generalization are real, tested primitives, not a compliance checkbox.
• Not yet a good fit for: anything needing K-Prototypes' categorical support through the main AudienceSegmenter class (numeric-only today — see Known Issues); Linux/Windows deployment via pip install (macOS ARM64 wheel only — see Installation).

---

30-Second Start

from clusteraudiencekit import AudienceSegmenter, RFMConfig, calculate_rfm

# transactions: list of (customer_id, iso8601_date, amount).
# n_clusters must be <= the number of distinct customers — use your real,
# larger transaction history here; this toy example has 3 customers.
transactions = [
    ("cust_1", "2026-06-01T00:00:00+00:00", 120.0),
    ("cust_1", "2026-07-15T00:00:00+00:00", 80.0),
    ("cust_2", "2026-01-10T00:00:00+00:00", 15.0),
    ("cust_3", "2026-08-01T00:00:00+00:00", 500.0),
]

# Real RFM scoring (recency/frequency/monetary, quintile-scored, 13-segment
# classification), not a mock.
scores = calculate_rfm(transactions, RFMConfig())

# Cluster customers by their RFM features with real KMeans (k-means++ init,
# rayon-parallelized assignment step, deterministic for a given seed).
features = [[s.recency, s.frequency, s.monetary] for s in scores]
segmenter = AudienceSegmenter(2)
segmenter.fit(features)
segments = segmenter.predict(features)

---

Why ClusterAudienceKit?

Marketing/data teams need RFM segmentation, clustering, churn scoring, and CLV estimation, usually stitched together from several tools. This package does the core numeric work in Rust (fast, deterministic, real unit-tested algorithms — not scikit-learn wrappers) with a Python API, so you get one dependency instead of five, and you can inspect exactly what's real (see docs/ROADMAP_HONEST.md — this project tracks its own honesty about what's implemented vs. planned, on purpose).

---

What's real today

Everything below is backed by real Rust logic with cargo test coverage and exposed through the compiled Python extension (import clusteraudiencekit) with its own Python-level tests — not a stub, not a mock, not aspirational documentation.

Capability	Python entry points
RFM analysis	calculate_rfm, RFMConfig, RFMScore
KMeans / K-Prototypes clustering	kmeans, AudienceSegmenter
Cluster quality metrics	silhouette_score, davies_bouldin_score, calinski_harabasz_score, assess_cluster_quality
Automatic K selection	estimate_k_elbow, estimate_k_gap_statistic, estimate_k_silhouette, estimate_k_combined
Churn prediction (incl. real AUC-ROC)	ChurnPrediction, ChurnRiskLevel
Customer lifetime value	CustomerLTV, calculate_simple_ltv
SQL export (8 dialects, injection-safe)	export_segment_sql, export_all_segments_sql, get_supported_sql_dialects
Differential privacy & k-anonymity	PyPrivacyBudget, add_laplace_noise, add_gaussian_noise, check_k_anonymity, suppress_to_k_anonymous, generalize_numeric
Real-time streaming segmentation	PyStreamingSegmentationEngine, PyStreamingEvent, PyStreamingConfig
Drift detection	kolmogorov_smirnov, hellinger_distance, chi_square_drift, detect_feature_drift, detect_segment_composition_change
Lookalike audiences	generate_lookalike, find_similar_customers, cosine_similarity
Cohort analytics	create_cohort, cohort_id_for, compare_cohorts, aggregate_cohorts_by_period, cohort_retention_table
Lifecycle tracking	classify_lifecycle_stage, lifecycle_retention_actions, lifecycle_stage_distribution
Rule-based behavioral segmentation	PyBehavioralSegmenter, PyBehavioralSegment, PyBehavioralRule, PyCondition
Segment profiling	profile_segment

Segmentation output: 13 named RFM segments (Champions, Loyal Customers, Potential Loyalists, At Risk, Cannot Lose Them, About to Sleep, New Customers, Promising, Need Attention, Lost, At Risk - Sleeping, Hibernating, VIP).

What's real but not yet exposed to Python

segment_intelligence, pattern_discovery, temporal_analytics, price_intelligence, revenue_intelligence, and neural_networks are real, tested Rust modules (not stubs) that are large enough we deferred wiring them to a follow-up release rather than rush it. See docs/ROADMAP_HONEST.md for specifics on each.

What's explicitly out of scope

External platform activation (pushing segments to ad/CRM platforms), B2B governance/workflow tooling, a dashboard UI, and a plugin framework are deliberately not part of this library — see docs/ROADMAP_HONEST.md for why.

---

Requirements

• Python 3.8+
• NumPy, Pandas, PyArrow (see pyproject.toml for exact ranges)
• Precompiled Rust core (ships as a platform wheel; no local Rust toolchain needed to install) — but see the platform caveat below

Installation

pip install clusteraudiencekit

The only wheel currently published to PyPI is macOS ARM64 (cp39). There is no source distribution and no CI pipeline building Linux/Windows wheels yet, so pip install will fail on other platforms today — see Known Issues. To use this on Linux/Windows/other Python versions in the meantime, clone the repo and build locally with maturin (pip install maturin && maturin develop --release), which does require a Rust toolchain.

Documentation

• Honest roadmap — what's real, what's deferred, and why.
• Security audit
• SQL export reference
• Examples

Known Issues

Verified as of this audit (August 2026):

• Published wheels are still single-platform, though the latest release improved on this. The latest PyPI release (7.3.0, matching this repo's version exactly — no drift) ships a macOS ARM64 / cp311 wheel and, unlike 7.1.1/7.2.0 before it, a source distribution — so pip install can now at least attempt a source build via maturin on Linux/Windows instead of failing outright with no fallback. There is still no CI job that builds Linux or Windows wheels (.github/workflows/ only runs tests on ubuntu-latest, not a release build matrix), despite pyproject.toml classifying the package as OS Independent and supporting Python 3.8–3.12, so every release's wheel is still built and uploaded by hand rather than by CI.
• v7.0.0 remains installable from PyPI despite a confirmed import-crashing bug. It was never yanked. If you have it pinned, upgrade to >=7.2.0.
• K-Prototypes categorical support is partial. AudienceSegmenter.fit() only accepts a numeric feature matrix today, so selecting K-Prototypes through that class currently runs in numeric-only mode (effectively KMeans). The underlying engine::clustering::kprototypes Rust implementation does support mixed numeric/categorical data; it just isn't reachable from that Python entry point yet. Details in docs/ROADMAP_HONEST.md.
• Two Rust utility functions are unimplemented stubs. pandas_to_arrow/arrow_to_pandas in src/utils/conversions.rs return Err("Not implemented"). They are not called from anywhere else in the crate and are not exposed to Python, so they don't affect any documented functionality — noted here for completeness.
• Registry check: local version (7.3.0, in Cargo.toml and pyproject.toml) matches the latest version actually published on PyPI. No drift.
• No open GitHub issues at the time of this audit.
• Six real, tested Rust modules are implemented but not yet wired to the Python API (segment_intelligence, pattern_discovery, temporal_analytics, price_intelligence, revenue_intelligence, neural_networks) — see "What's real but not yet exposed to Python" above.

License

Apache License 2.0. See LICENSE for the full terms.