Metadata-Version: 2.4
Name: PyCustomerJourney
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries
Summary: Open-source customer activation and journey orchestration runtime
Keywords: journey,orchestration,activation,marketing,cdp,workflow
Author-email: Georgi Mammen Mullassery <mullassery@gmail.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/Mullassery/PyCustomerJourney/wiki
Project-URL: Issues, https://github.com/Mullassery/PyCustomerJourney/issues
Project-URL: Repository, https://github.com/Mullassery/PyCustomerJourney

# PyCustomerJourney

**The Open-Source Customer Activation & Journey Orchestration Runtime**

---

## The Problem You're Facing

You're building a modern customer engagement program. You have:

- A CDP (or data warehouse) with customer audiences
- Multiple communication channels (email, SMS, push, ads)
- Attribution requirements
- Journey orchestration needs

But no single system owns the complete lifecycle:

```
Audience → Activation → Journey → Interaction → Outcome → Attribution
```

As a result:

- 🔀 **Journeys become fragmented** — Logic splits across email, SMS, ads, and CRM systems
- 📊 **Attribution becomes unreliable** — No single source of truth for what actually worked
- 🔧 **Operations become overhead** — Reverse ETL tools, manual syncs, disconnected reporting
- ⏱️ **Execution is brittle** — Lost state when browsers close, Python processes die
- 💰 **ROI is unmeasurable** — Can't prove if audiences actually achieve business outcomes

**The core issue:** Modern martech stacks are built for *creating* audiences, not for *activating and measuring* them.

---

## PyCustomerJourney: A Better Way

PyCustomerJourney is a durable journey runtime that unifies the activation layer.

It sits *downstream* of CDPs, data warehouses, and audience systems, providing:

- **Activation** — Connect audiences to channels (email, SMS, ads, CRM)
- **Orchestration** — Multi-step customer journeys with branching and delays
- **Execution** — Durable runtime that survives infrastructure failures
- **Attribution** — Trace every outcome back to its journey
- **Analytics** — Measure audience performance at scale

### Why It's Different

| Aspect | Traditional Martech | PyCustomerJourney |
|--------|-------------------|-------------------|
| **Ownership Model** | Point solutions (email, SMS, ads) | Unified journey runtime |
| **Attribution** | Campaign-based | Journey-based |
| **Execution** | Browser/session-dependent | Durable, infrastructure-independent |
| **Authoring** | Visual UI only | Visual + YAML + Python |
| **Cost** | SaaS licensing per channel | Open-source, self-hosted |
| **Data Ownership** | Vendor-controlled | You control everything |
| **Extensibility** | Limited/proprietary | Developer-first, Python-native |

---

## How It Works

### 1. Audience Source

Audiences come from anywhere:

```
ClusterAudienceKit
       ↓
CDP / Data Warehouse
       ↓
SQL Query / API
       ↓
PyCustomerJourney
```

PyCustomerJourney *consumes* audiences but never *creates* them.

### 2. Journey Definition

Define journeys in your preferred way:

**Visual Builder**
```
Audience Enters
    ↓
Send Email
    ↓
Wait 3 Days
    ↓
Opened?
  ↙   ↘
Yes   No
 ↓     ↓
 A     B
```

**YAML**
```yaml
journey:
  name: churn_prevention
  trigger:
    audience: churn_risk
  steps:
    - send_email:
        template: retention_offer
    - wait: 3 days
    - if_opened:
        then: show_offer_a
        else: send_sms
```

**Python SDK**
```python
journey = (
    Journey("churn_prevention")
    .trigger("churn_risk")
    .send_email("retention_offer")
    .wait(days=3)
    .branch(
        condition="email_opened",
        if_true=show_offer_a,
        if_false=send_sms
    )
)
```

### 3. Activation

The runtime activates journeys across channels:

- **Email**: SES, SendGrid, Mailgun, Postmark, Resend
- **SMS**: Twilio, Vonage, MessageBird
- **WhatsApp**: Meta, Twilio, Gupshup
- **Push**: Firebase, APNS, OneSignal
- **Ads**: Google Ads, Meta, LinkedIn, TikTok, Amazon
- **CRM**: Salesforce, HubSpot, Dynamics
- **Support**: Zendesk, Intercom, Freshdesk

### 4. Feedback Collection

The runtime continuously imports outcomes:

```
Email Delivered → Email Opened → Email Clicked
      ↓                ↓               ↓
  Tracked          Tracked        Tracked
      ↓________________↓_______________↓
           Journey State Updated
                    ↓
            Business Outcome Recorded
```

### 5. Attribution & Analytics

Every outcome is traced back to its journey:

```
Audience: High Churn Risk
  ↓
Activated: 250,000
  ↓
Journey: Churn Prevention
  ↓
Converted: 32,000 (12.8%)
  ↓
Revenue: $2.4M
  ↓
ROI: 7.3x
```

---

## Quick Start (Coming Soon)

```bash
# Install
pip install pycustomerjourney

# Deploy locally
pyaudience start

# Define a journey
pyaudience journey create --yaml journey.yaml

# Activate an audience
pyaudience activate --audience churn_risk --journey churn_prevention
```

---

## The Ecosystem

### ClusterAudienceKit
**Audience Discovery & Intelligence**

- Who should we target?
- Segmentation, clustering, RFM analysis
- Creates audiences

### PyStreamMCP
**Query Optimization & Context Discovery**

- How do we efficiently retrieve customer context?
- Intelligent query planning (60-75% cost reduction)
- Streaming retrieval for real-time personalization
- Use PyStreamMCP instead of building query logic in PyCustomerJourney

### PyCustomerJourney
**Activation & Orchestration**

- What should happen after an audience exists?
- Journeys, activation, attribution
- Consumes audiences
- Integrates with PyStreamMCP for context retrieval

### OpenShell (Future)
**Operations & Deployment**

- One-click deployment
- Monitoring & scaling
- Secrets management

Each product remains independently deployable and independently valuable.

### Important: Integration with PyStreamMCP

**Do NOT rebuild query optimization in PyCustomerJourney.** 

When personalizing journeys with customer context, use PyStreamMCP:

```python
from pystreammcp import Discovery

# For journey step personalization
discovery = Discovery.new(query_id="journey_context")
context = discovery.optimize_for_cost()  # Efficient retrieval

# Use context in journey templates
```

**Why?** PyStreamMCP provides specialized features that PyCustomerJourney shouldn't duplicate:
- Learned relevance models for intelligent data retrieval
- Multi-agent context sharing (20%+ efficiency gains)
- Query decomposition for complex context needs
- Streaming retrieval for real-time personalization

See [ARCHITECTURE.md](ARCHITECTURE.md#with-pystreammcp-query-optimization--context-discovery) for details.

---

## Core Capabilities

### ✅ Multi-Channel Activation
Activate audiences across email, SMS, push, ads, CRM, and support platforms.

### ✅ Durable Journeys
Long-running customer journeys (minutes to months) that survive infrastructure failures.

### ✅ Event-Driven Execution
Trigger branching and progression based on customer actions (opens, clicks, purchases).

### ✅ Experimentation
Built-in A/B testing framework within journeys.

### ✅ Attribution Engine
Trace revenue and business outcomes back to journeys and audiences.

### ✅ Developer-First
Python SDK, custom nodes, custom connectors, extensible architecture.

### ✅ AI-Native
Journey generation, optimization, insights, and channel recommendations.

### ✅ Deployment Agnostic
Run on laptop, Docker, Kubernetes, AWS, Azure, GCP, or on-premise.

---

## Architecture

### Rust Core
- Workflow execution
- Scheduling & state management
- Event processing
- Attribution engine
- Telemetry & observability

### Python Layer
- SDK
- Custom nodes & connectors
- AI integrations
- Automation

### Persistent Layer
- Journey definitions & versions
- Execution state
- Customer progress
- Attribution records
- Analytics data

The database is the operational source of truth. The runtime executes from persisted state, not from browser sessions.

---

## Status: v0.1.0 (Planning Phase)

This project is in the planning phase. The repository contains:

- Product vision & architecture
- Core design decisions
- Integration patterns
- Roadmap

Implementation begins in the coming months.

---

## Vision

Transform how organizations think about customer engagement.

Just as:
- **Airflow** became the standard for workflow orchestration in data
- **dbt** became the standard for data transformation
- **Temporal** became the standard for durable workflows
- **DuckDB** became the standard for embedded analytics

**PyCustomerJourney** will become the standard runtime for customer activation and journey orchestration.

---

## License

MIT — See [LICENSE](LICENSE) for details.

---

## Contact

- **GitHub**: https://github.com/Mullassery/PyCustomerJourney
- **Email**: mullassery@gmail.com


