ClusterAudienceKit

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.

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, 8-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.

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)

Installation

pip install clusteraudiencekit

Documentation

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

License

Proprietary — free to use with explicit attribution. See LICENSE for the full terms.