# RFM Custom Thresholds Implementation Summary

**Date:** 2026-02-11
**Feature:** Custom RFM Scoring Thresholds for Pro/Enterprise
**Status:** ✅ Complete and Tested

## Overview

Added flexible RFM threshold configuration that allows Pro/Enterprise users to customize Recency, Frequency, and Monetary scoring thresholds to match their specific industry, business model, or customer behavior patterns.

## Problem Solved

**Before:**
- Only 3 preset scorers available (b2b_service, saas, manufacturing)
- Thresholds were hardcoded in preset classes
- Users couldn't adjust thresholds to match their specific buying cycles or revenue ranges
- No way to use fixed dollar thresholds for monetary scoring

**After:**
- Pro/Enterprise users can define custom thresholds via JSON configuration
- Full control over recency days, frequency counts, and monetary scoring
- Support for both percentile-based and fixed monetary scoring methods
- Custom thresholds override presets when configured

## Implementation Details

### New Files Created

1. **`src/artefact_mcp/core/rfm_thresholds.py`**
   - `RFMThresholds` dataclass with all configurable thresholds
   - `to_scorer_config()` method to convert to RFMScorer format
   - Preset threshold definitions (DEFAULT, B2B_SERVICE, B2B_SAAS, B2B_MANUFACTURING)
   - `PRESET_THRESHOLDS` dictionary for preset access

2. **`rfm_thresholds.example.json`**
   - Example configuration with percentile-based monetary scoring
   - Demonstrates B2B service thresholds (longer cycles)

3. **`rfm_thresholds.fixed_monetary.example.json`**
   - Example configuration with fixed dollar thresholds
   - For businesses with specific revenue tiers

4. **`test_rfm_thresholds.py`**
   - Verification script with 4 test scenarios
   - Tests default, custom, preset thresholds, and config conversion

### Modified Files

1. **`src/artefact_mcp/tools/rfm.py`**
   - Added `custom_thresholds` parameter to `run_rfm_analysis()`
   - Updated `_get_scorer()` to accept and use custom thresholds
   - Added import for `RFMThresholds`

2. **`src/artefact_mcp/server.py`**
   - Loads RFM thresholds from `ARTEFACT_RFM_THRESHOLDS_PATH` env var
   - Only available for Pro/Enterprise tiers
   - Passes custom thresholds to `run_rfm` tool
   - Added import for `RFMThresholds`

3. **`README.md`**
   - Added "Custom RFM Thresholds (Pro/Enterprise)" section
   - Documented all configuration options
   - Explained when to use percentile vs fixed monetary scoring
   - Added `ARTEFACT_RFM_THRESHOLDS_PATH` to configuration table

## Configuration Options

### Recency Thresholds
- `recency_days`: Array of day thresholds (e.g., `[30, 90, 180, 365]`)
- `recency_scores`: Corresponding scores (e.g., `[5, 4, 3, 2, 1]`)
- **Lower days = higher score** (recent purchases are better)

### Frequency Thresholds
- `frequency_counts`: Array of transaction count thresholds (e.g., `[10, 5, 3, 2]`)
- `frequency_scores`: Corresponding scores (e.g., `[5, 4, 3, 2, 1]`)
- **Higher count = higher score** (frequent buyers are better)

### Monetary Thresholds

**Percentile Method (Default):**
- `monetary_method`: `"percentile"`
- `monetary_percentiles`: Array of percentile thresholds (e.g., `[80, 60, 40, 20]`)
- Scores relative to your current customer base
- Top 20% always scores 5, regardless of absolute revenue

**Fixed Method:**
- `monetary_method`: `"fixed"`
- `monetary_fixed_thresholds`: Array of dollar thresholds (e.g., `[100000, 50000, 25000, 10000]`)
- `monetary_scores`: Corresponding scores (e.g., `[5, 4, 3, 2, 1]`)
- Absolute revenue tiers
- Consistent scoring across time periods

## Usage Example

### 1. Create Configuration File

**Percentile-based (recommended):**
```json
{
  "recency_days": [60, 180, 365, 730],
  "recency_scores": [5, 4, 3, 2, 1],
  "frequency_counts": [5, 3, 2, 1],
  "frequency_scores": [5, 4, 3, 2, 1],
  "monetary_method": "percentile",
  "monetary_percentiles": [80, 60, 40, 20]
}
```

**Fixed-threshold:**
```json
{
  "recency_days": [30, 90, 180, 365],
  "frequency_counts": [10, 5, 3, 2],
  "monetary_method": "fixed",
  "monetary_fixed_thresholds": [250000, 100000, 50000, 25000],
  "monetary_scores": [5, 4, 3, 2, 1]
}
```

### 2. Set Environment Variable

```bash
export ARTEFACT_RFM_THRESHOLDS_PATH=/path/to/rfm_thresholds.json
```

### 3. Use the `run_rfm` Tool

```bash
# Via Claude Code / Claude Desktop
run_rfm(source="hubspot")

# Programmatic
from artefact_mcp.tools.rfm import run_rfm_analysis
from artefact_mcp.core.hubspot_client import HubSpotClient
from artefact_mcp.core.rfm_thresholds import RFMThresholds

thresholds = RFMThresholds(
    recency_days=[60, 180, 365, 730],
    frequency_counts=[5, 3, 2, 1],
    monetary_method="percentile"
)

client = HubSpotClient(api_key="your-key")
result = run_rfm_analysis(
    source="hubspot",
    hubspot_client=client,
    custom_thresholds=thresholds
)
```

## When to Use Custom Thresholds

### Use Percentile Method When:
- You want relative scoring within your current customer base
- Customer base is relatively homogeneous
- You want consistent segment distribution (always ~20% Champions, etc.)
- Revenue ranges vary significantly over time

### Use Fixed Method When:
- You have specific revenue tiers that define customer value
- Wide revenue variance and percentiles don't align with business value
- You want consistent scoring across different time periods
- Enterprise vs SMB segmentation is important

### Adjust Recency Thresholds When:
- **Shorter cycles** (e.g., eCommerce): `[7, 30, 90, 180]`
- **Standard B2B**: `[30, 90, 180, 365]` (default)
- **Longer cycles** (e.g., consulting): `[60, 180, 365, 730]`
- **Very long cycles** (e.g., manufacturing): `[90, 365, 730, 1095]`

### Adjust Frequency Thresholds When:
- **Subscription business** (high frequency): `[12, 6, 3, 1]`
- **Standard B2B**: `[10, 5, 3, 2]` (default)
- **Consulting** (lower frequency): `[5, 3, 2, 1]`
- **Large transactions** (very low frequency): `[3, 2, 1, 0]`

## Testing

All tests pass successfully:

```
✅ Test 1: Default Thresholds — Standard RFM scoring
✅ Test 2: Custom Thresholds — Custom recency/frequency, fixed monetary
✅ Test 3: Preset Thresholds — B2B Service preset verification
✅ Test 4: Config Conversion — Percentile and fixed method conversion
```

Run tests:
```bash
python test_rfm_thresholds.py
```

## Backward Compatibility

✅ **Fully backward compatible**

- Free tier users: No changes, uses default thresholds
- Pro/Enterprise without config: Uses default or preset thresholds (via `industry_preset`)
- Pro/Enterprise with config: Custom thresholds override presets
- Existing preset classes (B2BServiceScorer, etc.) still work

## Priority Order

When scoring RFM:
1. **Custom thresholds** (if `ARTEFACT_RFM_THRESHOLDS_PATH` is set) — **highest priority**
2. **Industry preset** (if `industry_preset` parameter is used)
3. **Default RFMScorer** (fallback)

## Files Summary

### Created
- `src/artefact_mcp/core/rfm_thresholds.py` (96 lines)
- `rfm_thresholds.example.json` (8 lines)
- `rfm_thresholds.fixed_monetary.example.json` (9 lines)
- `test_rfm_thresholds.py` (152 lines)
- `IMPLEMENTATION_RFM_THRESHOLDS.md` (this file)

### Modified
- `src/artefact_mcp/tools/rfm.py` (+14 lines)
- `src/artefact_mcp/server.py` (+16 lines)
- `README.md` (+61 lines)

### Total Changes
- **5 new files**
- **3 modified files**
- **~356 lines of code and documentation added**

## Deployment Checklist

- [x] Implementation complete
- [x] Unit tests pass
- [x] Documentation updated (README)
- [x] Example configurations provided
- [x] Backward compatibility verified
- [x] Import verification passed
- [x] JSON validation passed

## Next Steps for User

1. **Identify your business model** (subscription, consulting, transactional)
2. **Determine typical buying cycle length** (recency thresholds)
3. **Determine typical purchase frequency** (frequency thresholds)
4. **Choose monetary method:**
   - **Percentile** if you want relative scoring
   - **Fixed** if you have specific revenue tiers
5. **Copy example configuration:** `cp rfm_thresholds.example.json my_rfm_thresholds.json`
6. **Edit thresholds** to match your business
7. **Set environment variable:** `export ARTEFACT_RFM_THRESHOLDS_PATH=$(pwd)/my_rfm_thresholds.json`
8. **Test with sample data:** `run_rfm(source="sample")`
9. **Validate segments** align with business expectations
10. **Run with HubSpot data:** `run_rfm(source="hubspot")`

---

**Implementation Status:** ✅ Production Ready
**Tested:** ✅ All tests passing
**Documented:** ✅ README updated with examples
