clusteraudiencekit 5.9.2__tar.gz

clusteraudiencekit-5.9.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug Report
+about: Report a bug to help us improve
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Description
+Briefly describe the bug.
+
+## Steps to Reproduce
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+What should happen?
+
+## Actual Behavior
+What actually happened?
+
+## Environment
+- OS: [e.g. macOS, Linux, Windows]
+- Python version: [e.g. 3.10]
+- Library version: [e.g. 2.0.0]
+
+## Minimal Example
+```python
+# Minimal code to reproduce the bug
+```
+
+## Error Message
+```
+# Paste full error traceback here
+```
+
+## Additional Context
+Any other context about the issue?

clusteraudiencekit-5.9.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature Request
+about: Suggest an idea to improve the project
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem Statement
+Describe the problem this feature would solve.
+
+## Proposed Solution
+How should this feature work?
+
+## Use Case
+What use case does this solve?
+
+## Example
+```python
+# Example of how this would be used
+```
+
+## Alternatives
+Any alternative approaches you've considered?
+
+## Additional Context
+Any other context or screenshots?

clusteraudiencekit-5.9.2/.github/dependabot.yml

@@ -0,0 +1,52 @@
+version: 2
+updates:
+  # Rust dependencies (Cargo.toml)
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    open-pull-requests-limit: 5
+    reviewers:
+      - "Mullassery"
+    labels:
+      - "dependencies"
+      - "rust"
+    commit-message:
+      prefix: "chore(deps):"
+      include: "scope"
+
+  # Python dependencies (pip/pyproject.toml)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    open-pull-requests-limit: 5
+    reviewers:
+      - "Mullassery"
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "chore(deps):"
+      include: "scope"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "Mullassery"
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci):"
+      include: "scope"

clusteraudiencekit-5.9.2/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: Tests & Build
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  rust-build:
+    name: Rust Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: |
+            crates
+            core
+            python
+
+      - name: Build Rust
+        run: cargo build --release --all-features
+
+      - name: Test Rust
+        run: cargo test --release --all-features
+
+  python-tests:
+    name: Python Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest tests/ -v --tb=short

clusteraudiencekit-5.9.2/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Build
+target/
+Cargo.lock
+*.o
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Temporary
+.tmp/
+*.local

clusteraudiencekit-5.9.2/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+
+  - repo: https://github.com/rust-lang/rust-clippy
+    rev: v1.77.0
+    hooks:
+      - id: clippy
+        args: ['--all-targets', '--', '-W', 'clippy::all']
+
+  - repo: https://github.com/rust-lang/rustfmt
+    rev: v1.7.0
+    hooks:
+      - id: rustfmt
+
+  - repo: https://github.com/psf/black
+    rev: 24.1.1
+    hooks:
+      - id: black
+        language_version: python3
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.2.0
+    hooks:
+      - id: ruff
+        args: ['--fix']
+      - id: ruff-format

clusteraudiencekit-5.9.2/ARCHITECTURE.md

@@ -0,0 +1,282 @@
+# ClusterAudienceKit Architecture & Ecosystem Boundaries
+
+## Mission
+
+**Identify Who Matters**
+
+Core Question: Which customers should we target?
+
+## Core Responsibility
+
+ClusterAudienceKit is **exclusively responsible** for:
+
+- **Customer Segmentation** — RFM analysis, behavioral clustering
+- **Audience Definition** — Rules, criteria, membership logic
+- **Audience Calculation** — Computing audience membership
+- **Audience Refresh** — Recalculating audience membership
+- **Segment Hierarchy** — Parent/child segment relationships
+- **Scoring Models** — Customer value, churn risk, engagement scores
+- **Audience Analytics** — Segment performance, overlap analysis
+
+## What We Do NOT Own
+
+These belong to other products:
+
+### ❌ Data Quality & Validation (StatGuardian)
+- Schema validation
+- Data freshness checks
+- Drift detection
+- Constraint enforcement
+
+**Our role:** Assume input data is valid. Optionally require StatGuardian gates.
+
+### ❌ Journey Orchestration (PyCustomerJourney)
+- Journey definition
+- Step execution
+- Communications
+- Attribution
+
+**Our role:** Provide audiences. They activate journeys.
+
+### ❌ Data Activation (PyReverseETL)
+- Syncing to operational systems
+- Destination management
+- Sync orchestration
+
+**Our role:** Define audiences. They sync membership.
+
+### ❌ Query Optimization & Context Discovery (PyStreamMCP)
+- Query planning for audience retrieval
+- Intelligent data fetching
+- Token/cost optimization
+- Streaming retrieval
+
+**Our role:** Use PyStreamMCP for efficient data ingestion and downstream member retrieval.
+
+## Integration with PyStreamMCP
+
+**IMPORTANT:** ClusterAudienceKit should use **PyStreamMCP** for:
+
+### Ingestion (Data In)
+```python
+# ✅ CORRECT: Use PyStreamMCP for intelligent data retrieval
+from pystreammcp import Discovery
+
+# When building audiences from multiple sources:
+discovery = Discovery.new(query_id="audience_ingestion")
+sources = discovery.discover_sources()  # Find optimal data
+optimized = discovery.optimize_for_cost()  # Efficient retrieval
+
+# Use optimized context to build audience
+audience = create_audience(
+    name="churn_risk",
+    criteria=optimized,  # PyStreamMCP's optimized context
+    source_query=optimized
+)
+```
+
+### Member Retrieval (Data Out)
+```python
+# ✅ CORRECT: Use PyStreamMCP for efficient member retrieval
+from pystreammcp import Agent
+
+# When retrieving audience members with context:
+agent = Agent(agent_id="audience_member_context")
+context = agent.query("customer context for audience enrichment")
+
+# Get members with optimized context
+members = audience.get_members()
+enriched_members = enrich_with_context(members, context)  # Context from PyStreamMCP
+```
+
+### Why Use PyStreamMCP?
+- **Intelligent Data Fetching:** Discover optimal data sources for audience building
+- **Cost Optimization:** 60-75% reduction in token/data usage
+- **Streaming Retrieval:** Progressive member retrieval for large audiences
+- **Query Planning:** Handle complex multi-step audience logic
+- **Token Efficiency:** Avoid redundant data fetches
+
+**Do NOT rebuild these in ClusterAudienceKit:**
+- Query planning
+- Data source discovery
+- Token optimization
+- Streaming retrieval
+- Cost estimation
+
+## Architectural Principles
+
+### 1. Segmentation First
+
+ClusterAudienceKit owns segmentation logic. Everything else is delegated.
+
+```
+Customer Data
+     ↓
+PyStreamMCP (Discover & Optimize)
+     ↓
+Efficient Retrieval
+     ↓
+ClusterAudienceKit (Segmentation)
+     ↓
+Audiences
+     ↓
+PyReverseETL (Activate)
+     ↓
+Operational Systems
+```
+
+### 2. No Validation Logic
+
+```rust
+// ❌ NOT OUR JOB
+fn validate_data(data: &Data) -> Result<()> {
+    // Check schema
+    // Check freshness
+    // Check constraints
+}
+
+// ✅ OUR JOB
+fn create_audience(data: &Data) -> Result<Audience> {
+    // Segment data
+    // Calculate membership
+    // Return audience
+}
+```
+
+### 3. Flexible Input
+
+Audiences can be built from:
+- Warehouse tables
+- Query results
+- APIs
+- Stream data
+- Real-time events
+
+But don't rebuild query logic—use PyStreamMCP.
+
+## Module Structure
+
+```
+core/src/
+├── lib.rs                    # Public exports
+├── error.rs                  # Error types
+├── audience.rs              # Audience definition & membership
+├── segment.rs               # Segmentation logic
+├── clustering/              # Clustering algorithms
+│   ├── kmeans.rs
+│   ├── rfm.rs
+│   └── behavioral.rs
+├── scoring/                 # Scoring models
+│   ├── churn_risk.rs
+│   ├── lifetime_value.rs
+│   └── engagement.rs
+└── storage/                 # Persistence
+    ├── schema.rs
+    └── repository.rs
+```
+
+## Integration Points
+
+### With PyStreamMCP (Ingestion)
+
+```rust
+// Use PyStreamMCP to discover optimal data sources
+use pystreammcp::Discovery;
+
+let discovery = Discovery::new(query_id);
+let sources = discovery.discover_sources()?;
+let optimized_query = discovery.optimize_for_cost()?;
+
+// Build audience from optimized query
+let audience = Audience::from_query(optimized_query);
+```
+
+### With PyStreamMCP (Member Retrieval)
+
+```rust
+// Use PyStreamMCP to efficiently retrieve member context
+use pystreammcp::Agent;
+
+let agent = Agent::new(agent_id);
+let context = agent.query("member context")?;
+
+// Enrich members with context
+members.enrich_with(context);
+```
+
+### With StatGuardian
+
+```rust
+// Optionally validate input data
+use statguardian::ValidationGate;
+
+Audience {
+    validation_gate: Option<ValidationGate>,
+    // Only build audience if validation passes
+}
+```
+
+### With PyReverseETL
+
+```rust
+// PyReverseETL syncs audience membership
+sync_to_destination(
+    audience=&audience,
+    destination="salesforce",
+)?;
+```
+
+### With PyCustomerJourney
+
+```rust
+// PyCustomerJourney launches journeys for audience members
+launch_journey(
+    audience_members=&audience.get_members(),
+    journey="churn_prevention",
+)?;
+```
+
+## Testability
+
+Each boundary is enforced through:
+
+1. **Module privacy** — Query/validation/journey modules don't exist
+2. **Type system** — Can't express query logic in our types
+3. **Documentation** — Explicit "use PyStreamMCP" statements
+4. **Integration tests** — Test against PyStreamMCP/StatGuardian APIs
+
+## Philosophy
+
+ClusterAudienceKit is to customer segmentation what dbt is to transformation.
+
+- dbt owns **transformation**, not validation
+- Airflow owns **orchestration**, not transformation
+- ClusterAudienceKit owns **segmentation**, not query optimization
+
+Each product excels at its domain precisely because it doesn't try to own everything else.
+
+PyStreamMCP handles query optimization so ClusterAudienceKit can focus entirely on segmentation.
+
+## Outcome
+
+When properly integrated:
+
+```
+Raw Data (Multiple Sources)
+        ↓
+PyStreamMCP optimizes retrieval
+        ↓
+Efficient Data Access
+        ↓
+ClusterAudienceKit segments
+        ↓
+Audience Membership
+        ↓
+PyReverseETL activates
+        ↓
+Operational Systems (CRM, Marketing, etc.)
+        ↓
+Customer Engagement
+```
+
+Each product does one thing excellently.