All works till now.

README.md

@@ -1,2 +1,362 @@
 # birthdaymessaging
 
+
+Overview
+
+The Birthday Messaging Intelligence Platform is a data-driven engagement system designed to transform static birthday campaigns into an intelligent engagement engine.
+
+The system integrates CRM data, behavioral interaction logs, and predictive analytics to automatically identify high-value engagement opportunities, detect churn risk, and orchestrate personalized birthday messaging campaigns.
+
+The platform evolves through three stages:
+
+Stage	Description
+Week 2	Data pipeline and engagement preparation
+Week 3	Predictive intelligence and behavioral segmentation
+Future	Multi-channel automation and campaign optimization
+
+The end result is a system that predicts disengagement before it happens and activates personalized engagement campaigns.
+
+System Architecture
+
+The project is organized into modular components following a data pipeline → intelligence → automation architecture.
+
+CRM Data + Clickstream Logs
+            │
+            ▼
+     Unified Data Pipeline
+            │
+            ▼
+    Data Cleaning & Compliance
+            │
+            ▼
+     Engagement Intelligence
+            │
+            ▼
+      Churn Prediction
+            │
+            ▼
+     Predictive Segmentation
+            │
+            ▼
+     Automation Triggers
+Project Structure
+birthdaymessaging/
+│
+├── config.yaml
+├── main.py
+├── README.md
+│
+├── data/
+│   ├── raw/
+│   └── processed/
+│
+├── docs/
+│   ├── ethics.md
+│   └── model-audits/
+│
+├── src/
+│   ├── pipeline/            # Week 2 Data Engineering
+│   │   ├── unified_stream.py
+│   │   ├── relative_date_trigger.py
+│   │   ├── rf_scoring.py
+│   │   ├── list_hygiene.py
+│   │   ├── ethics_flags.py
+│   │   ├── deliverability_check.py
+│   │   └── config_loader.py
+│   │
+│   ├── models/              # Week 3 Intelligence Layer
+│   │   ├── engagement_scoring.py
+│   │   ├── churn_classifier.py
+│   │   └── send_time_optimizer.py
+│   │
+│   ├── segmentation/
+│   │   └── predictive_segments.py
+│   │
+│   └── automation/
+│       ├── trigger_engine.py
+│       └── reactivation_triggers.yaml
+Week 2: Data Engineering Pipeline
+
+Week 2 focuses on building a clean, compliant data foundation.
+
+Unified Data Stream
+
+File:
+
+src/pipeline/unified_stream.py
+
+Functions:
+
+Load CRM dataset
+
+Load clickstream activity logs
+
+Pseudonymize user identifiers
+
+Merge datasets
+
+Normalize timestamps (UTC)
+
+Output:
+
+unified_dataset.csv
+Birthday Recursion Trigger
+
+File:
+
+relative_date_trigger.py
+
+Implements recurring campaign triggers such as:
+
+Birthday approaching
+
+Pre-birthday reminder
+
+Post-birthday follow-up
+
+Ensures contacts re-enter the workflow annually.
+
+Recency-Frequency Scoring
+
+File:
+
+rf_scoring.py
+
+Calculates engagement indicators:
+
+Recency index
+
+Frequency of sessions
+
+Session change delta
+
+Used as an early engagement signal.
+
+List Hygiene Automation
+
+File:
+
+list_hygiene.py
+
+Improves deliverability by removing:
+
+Invalid email domains
+
+Disposable email services
+
+Role-based addresses
+
+Ethics and Compliance Layer
+
+File:
+
+ethics_flags.py
+
+Detects sensitive data usage:
+
+medical_condition
+
+political_opinion
+
+dietary_restrictions
+
+Ensures compliance with GDPR principles.
+
+Deliverability Simulation
+
+File:
+
+deliverability_check.py
+
+Simulates email infrastructure readiness:
+
+SPF validation
+
+DKIM compatibility
+
+DMARC enforcement
+
+inactive contact suppression
+
+Week 3: Engagement Intelligence Engine
+
+Week 3 converts the pipeline into a predictive analytics platform.
+
+Engagement Scoring Engine
+
+File:
+
+src/models/engagement_scoring.py
+
+Calculates a normalized engagement score (0–100) based on:
+
+Recency of interaction
+
+Session frequency
+
+Session duration
+
+Click engagement depth
+
+Formula:
+
+Engagement Score =
+(Recency Weight × Normalized Recency)
++ (Frequency Weight × Session Count)
++ (Engagement Depth Weight × Interaction Index)
+
+Output classification:
+
+Score	Tier
+75–100	Highly Engaged
+50–74	Stable
+25–49	Declining
+0–24	At Risk
+Churn Risk Classification
+
+File:
+
+src/models/churn_classifier.py
+
+Defines churn risk using behavioral signals.
+
+Conditions:
+
+No login ≥ X days
+AND
+Engagement score drop ≥ Y%
+
+Risk categories:
+
+Risk Level	Description
+Low	Healthy engagement
+Medium	Engagement declining
+High	High probability of churn
+
+Output fields:
+
+churn_risk_flag
+churn_probability_score
+risk_class
+Predictive Segmentation
+
+File:
+
+src/segmentation/predictive_segments.py
+
+Creates behavioral marketing segments using:
+
+Lifecycle Stage
+Engagement Tier
+Birthday Proximity
+Churn Risk Overlay
+
+Example segment:
+
+At-Risk + Birthday Approaching
+Send-Time Optimization
+
+File:
+
+src/models/send_time_optimizer.py
+
+Analyzes historical open patterns and determines optimal send windows.
+
+Outputs:
+
+optimal_send_hour
+optimal_send_day
+Automation Triggers
+
+File:
+
+src/automation/reactivation_triggers.yaml
+
+Defines campaign orchestration rules.
+
+Example:
+
+IF churn_risk_flag = True
+AND birthday_within_30_days = True
+
+THEN send reminder email
+WAIT 24h
+IF unopened → send SMS
+Model Governance & Ethics
+
+Documentation:
+
+docs/model-audits/week3-bias-review.md
+docs/ethics.md
+
+Audits include:
+
+Geographic bias
+
+Age-based performance variance
+
+False-positive churn classification
+
+Transparency measures include clear documentation of automated decision logic.
+
+Running the Pipeline
+
+Run the full pipeline:
+
+python main.py
+
+Pipeline order:
+
+Week 2:
+Data Merge
+Birthday Triggers
+RF Scoring
+List Hygiene
+Ethics Checks
+Deliverability Simulation
+
+Week 3:
+Engagement Scoring
+Churn Classification
+Predictive Segmentation
+Send-Time Optimization
+
+Final dataset:
+
+data/processed/final_intelligence_output.csv
+Success Criteria
+
+The system is considered operational when:
+
+Engagement scores generated for all active users
+
+Churn risk classification validated
+
+Predictive segments documented
+
+Reactivation triggers tested
+
+Send-time optimization operational
+
+Ethics documentation updated
+
+Bias audit completed
+
+Outcome
+
+At completion, the platform functions as an Engagement Intelligence Engine.
+
+Capabilities include:
+
+Predicting disengagement
+
+Prioritizing high-value users
+
+Automating reactivation campaigns
+
+Personalizing birthday marketing
+
+Ensuring ethical data usage
+
+The platform transforms traditional birthday messaging into a behaviorally intelligent engagement strategy.
+