Metadata-Version: 2.4
Name: clusteraudiencekit
Version: 7.0.0
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: Production audience intelligence platform. RFM analysis, advanced clustering, real-time streaming, customer lifetime value prediction, lifecycle management, churn prediction, B2B governance.
Keywords: clustering,customer-segmentation,rfm-analysis,martech,audience-segmentation,customer-analytics,machine-learning,deep-learning,neural-networks,xgboost,gradient-boosting,automl,k-means,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>
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

**Segment millions of customers in <1 second. Know who matters.**

RFM analysis, customer lifetime value prediction, churn detection, and lookalike modeling—all in one production-ready package. Process 1M+ customers instantly.

[![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.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org)

---

## 30-Second Start

```python
from clusteraudiencekit import Segmentation, CLV

# Segment your customers
segments = Segmentation(df).fit()
print(segments.summary)  # Automatic RFM + clustering

# Find high-value customers
clv = CLV(df)
vips = clv.top_customers(n=100)
print(f"Top 100 worth: ${clv.total_value(vips):,.0f}")
```

---

## Why ClusterAudienceKit?

**The Problem:**
- Marketing teams manually segment (outdated, slow)
- No clear view of customer value
- Churn prediction requires multiple tools
- Building lookalike audiences is complex

**The Solution:**
- Automatic RFM segmentation (no configuration)
- Customer lifetime value prediction
- Churn scoring and early warning
- Lookalike audience generation
- Sub-second processing (1M+ customers)
---

## Quick Start

```python
from clusteraudiencekit import Segmentation, CLV

# Load customer data
df = load_customers()

# Automatic segmentation
segments = Segmentation(df).fit()
print(segments.summary)

# Calculate lifetime value
clv = CLV(df)
high_value = clv.top_customers(n=100)
```

## Process 1M+ Customers in <1s

Optimized clustering on millions of records:
- K-means, DBSCAN, Hierarchical clustering
- 6 algorithm options
- Parallel processing
- GPU acceleration support

## Key Features

- RFM analysis built-in
- 6 clustering algorithms
- Customer Lifetime Value (CLV)
- Churn prediction
- Lookalike modeling
- Neural network clustering
- Sub-second processing

## Key Features

**Audience Analysis**
- RFM segmentation (Recency, Frequency, Monetary)
- 6 clustering algorithms (K-means, DBSCAN, Spectral, Hierarchical, GMM, Isolation Forest)
- Customer Lifetime Value (CLV) prediction
- Churn detection and scoring
- Lookalike audience modeling

**Scalability**
- Process 1M+ customers in <1 second
- Rust-powered core for speed
- Streaming data support
- Batch and real-time APIs

**Integration**
- Pandas/Polars DataFrames
- Cloud storage (S3, GCS)
- SQL databases
- BI tools (Tableau, Looker)

---

## Requirements

- Python 3.10+
- NumPy ≥1.20.0
- Scikit-learn ≥1.0.0
- Pandas ≥1.3.0
- Rust core (precompiled wheels)
- Optional: Polars ≥0.18.0

---

## Installation

```bash
pip install clusteraudiencekit
# or with uv
uv pip install clusteraudiencekit

# Verify installation
clusteraudiencekit --version
```

## Use Cases

- Customer segmentation
- Churn prediction
- Retention campaigns
- CLV analysis
- Lookalike targeting
- Campaign personalization

## Examples

```python
from clusteraudiencekit import Segmentation, Churn, Lookalikes

# Segment customers
seg = Segmentation(df)
high_value = seg.segments['high_value']

# Predict churn
churn = Churn(df)
at_risk = churn.predict_churn(threshold=0.7)

# Find lookalikes
similar = Lookalikes(df).find_similar(seed_customers)
```

## Benchmarks

| Customers | Time | Throughput |
|-----------|------|-----------|
| 100K | 50ms | 2M/s |
| 1M | 400ms | 2.5M/s |
| 10M | 3.5s | 2.8M/s |

## Documentation

- [API Reference](docs/api.md)
- [Examples](examples/)
- [Benchmarks](docs/performance.md)

## License

MIT License - See LICENSE

