Metadata-Version: 2.4
Name: clusteraudiencekit
Version: 7.3.1
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: News/Diary
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Dist: pandas>=2.0,<3
Requires-Dist: numpy>=1.24,<2.1
Requires-Dist: pyarrow>=10.0
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0 ; extra == 'dev'
Requires-Dist: black>=22.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: sphinx>=5.0 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.0 ; extra == 'docs'
Provides-Extra: dev
Provides-Extra: docs
License-File: LICENSE
Summary: Rust-powered customer segmentation: RFM analysis, KMeans/K-Prototypes clustering, churn prediction, customer lifetime value, real-time streaming segmentation, drift detection, lookalike audiences, cohort analytics, lifecycle tracking, and differential privacy / k-anonymity.
Keywords: clustering,customer-segmentation,rfm-analysis,martech,audience-segmentation,customer-analytics,machine-learning,k-means,k-prototypes,differential-privacy,k-anonymity,segmentation-engine,crm,customer-lifetime-value,churn-prediction,cohort-analysis,audience-targeting,marketing-automation,email-marketing,retargeting,customer-scoring,behavioral-analytics,data-science,python-library,real-time-processing,streaming-data,marketing-tech,audience-modeling,rust-performance,predictive-analytics
Author-email: Georgi Mammen Mullassery <mullassery@gmail.com>
Maintainer-email: Georgi Mammen Mullassery <mullassery@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/Mullassery/ClusterAudienceKit/issues
Project-URL: Changelog, https://github.com/Mullassery/ClusterAudienceKit/releases
Project-URL: Discussions, https://github.com/Mullassery/ClusterAudienceKit/discussions
Project-URL: Documentation, https://github.com/Mullassery/ClusterAudienceKit#readme
Project-URL: Homepage, https://github.com/Mullassery/ClusterAudienceKit
Project-URL: Repository, https://github.com/Mullassery/ClusterAudienceKit
Project-URL: Source Code, https://github.com/Mullassery/ClusterAudienceKit/tree/main

# 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](#known-issues)); Linux/Windows deployment via `pip
  install` (macOS ARM64 wheel only — see [Installation](#installation)).

[![Tests](https://img.shields.io/github/actions/workflow/status/Mullassery/ClusterAudienceKit/tests.yml?label=tests)](https://github.com/Mullassery/ClusterAudienceKit/actions)
[![PyPI](https://img.shields.io/pypi/v/clusteraudiencekit)](https://pypi.org/project/clusteraudiencekit/)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org)

---

## 30-Second Start

```python
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`](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`](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`](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

```bash
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](#known-issues). To use this on Linux/Windows/other Python
versions in the meantime, clone the repo and build locally with
[`maturin`](https://github.com/PyO3/maturin) (`pip install maturin && maturin
develop --release`), which does require a Rust toolchain.

## Documentation

- [Honest roadmap](docs/ROADMAP_HONEST.md) — what's real, what's deferred,
  and why.
- [Architecture](docs/architecture/README.md) — real module layout and data
  flow, checked against `src/` (replaces two previous architecture docs that
  described integrations and directory layouts that never existed — see
  [`docs/archive/README.md`](docs/archive/README.md)).
- [Security audit](docs/SECURITY_AUDIT.md)
- [SQL export reference](docs/SQL_EXPORT.md)
- [Examples](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.1, 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`](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.1`, 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`](LICENSE) for the full terms.

