ChurnPilot

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 11 Open GitHub ↗

An intelligent platform that automates churn prediction and customer retention processes with Agentic AI. Thanks to its flexible architecture, it can be easily implemented and scaled across different sectors.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ChurnPilot

AI destekli müşteri kaybı tahmin ve otomatik elde tutma platformu.
*(Agentic AI customer churn prediction and automated retention platform.)*

This repository contains the **Sprint 1 / Milestone 0** foundation: a runnable
full-stack skeleton with the complete database schema, routing shell, and the
provider-agnostic LLM client — ready for Milestone 1 (Dashboard + Customer
List) to build on top of.

## Prerequisites

- Python 3.11+
- Node.js 20+
- A Gemini **or** Azure OpenAI API key (only required starting Sprint 4, when agents call the LLM — see "LLM provider setup" below)

## Backend setup

```bash
cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env             # fill in OPENAI_API_KEY when you reach Milestone 2
uvicorn app.main:app --reload --port 8000
```

Visit `http://localhost:8000/health` — you should see `{"status": "ok", ...}`.

To seed the database with development data:

```bash
python -m app.seed.seed_data
```

> **Note:** the real IBM Telco Customer Churn CSV is not included in this
> repo. Place it at `backend/data/telco_churn.csv` before Milestone 1's
> training script runs. Until then, `seed_data.py` generates a
> schema-matching synthetic dataset so the team isn't blocked.

To train the churn model and score the seeded customers:

```bash
python -m app.ml.train
```

This trains an **XGBoost** classifier (Sprint 3 — see "Sprint 3" below) on a
labeled synthetic dataset (or the real Telco CSV if you've implemented its
column mapping), computes a SHAP explanation for every customer, saves the
model to `app/ml/artifacts/`, and writes a `Prediction` row (probability,
risk tier, SHAP payload) for every customer currently in the database.
Re-run it any time — it's idempotent and safe to run again after re-seeding
or retraining. If the API server is already running, it'll pick up the new
model automatically on the next request (see "Sprint 3 review notes").

Then, to segment customers (Sprint 5 — requires scored customers):

```bash
python -m app.ml.segment
```

## Frontend setup

```bash
cd frontend
npm install
cp .env.example .env
npm run dev
```

Visit `http://localhost:5173` — the Dashboard, Customers, and Customer
Detail pages all show real data once the backend has been seeded and
scored (see above).

## LLM provider setup

Two providers are supported, switched with a single `.env` variable — no
code change needed either way. Every agent depends on the provider-agnostic
`LLMClient` interface (`app/services/llm_client.py`), never on a provider
SDK directly.

### Gemini

1. Get a key from [aistudio.google.com/apikey](https://aistudio.google.com/apikey).
2. In `backend/.env`, set:
   ```
   LLM_PROVIDER=gemini
   GEMINI_API_KEY=your-actual-key
   GEMINI_MODEL=gemini-2.5-flash
   ```

### Azure OpenAI

1. Create a deployment in your Azure OpenAI resource.
2. In `backend/.env`, set:
   ```
   LLM_PROVIDER=azure
   AZURE_ENDPOINT=https://your-resource-name.cognitiveservices.azure.com/
   AZURE_API_KEY=your-azure-api-key
   AZURE_MODEL_NAME=your-deployment-name
   ```
3. Note: newer reasoning-style Azure models (e.g. `gpt-5.2-chat`) reject a
   non-default `temperature` value — `AzureOpenAIClient.complete()`
   deliberately omits the parameter rather than hardcoding one, so it works
   across older and newer deployments alike.

No key configured, or the provider SDK not installed? The whole pipeline
still runs — every LLM-backed agent falls back to a deterministic Turkish
template (see "Sprint 4" below). You'll see `"source": "template"` in the
API responses instead of `"source": "gemini"`.

## Testing the Sprint 4 agents individually

Each agent takes plain Python objects (no DB, no live Gemini call needed) —
run the whole suite:

```bash
cd backend
python -m unittest tests.test_agents -v
# or, if you have pytest: python -m pytest tests/test_agents.py -v
```

Or test any single agent by hand in a Python shell:

```python
from types import SimpleNamespace
from app.agents.risk_agent import RiskAgent
from app.models.prediction import RiskTier

customer = SimpleNamespace(name="Test", monthly_charges=120.0)
prediction = SimpleNamespace(churn_probability=0.8, risk_tier=RiskTier.CRITICAL, confidence_score=0.6)
print(RiskAgent().assess(customer, prediction))
```

`ExplainabilityAgent`, `RetentionStrategyAgent`, and `CommunicationAgent` all
accept `llm_client=None` to force their deterministic fallback — pass a real
`get_llm_client()` instance to exercise the Gemini path instead. The full
pipeline end-to-end, against a real seeded+scored customer:

```bash
python -m app.seed.seed_data && python -m app.ml.train  # if not already done
uvicorn app.main:app --reload --port 8000
# in another terminal:
curl -X POST http://localhost:8000/api/customers/<customer-id>/run-pipeline \
  -H "Content-Type: application/json" -d '{"approval_mode": "semi_autonomous"}'
curl http://localhost:8000/api/customers/<customer-id>/timeline
```

Or from the Customers page, click into any customer and use the "AI Elde
Tutma Pipeline'ı" panel on their Customer Detail page.

## What's in Sprint 1

- Full folder structure per the approved architecture (Phase 2 doc)
- All 8 SQLAlchemy models, wired to `Base.metadata.create_all`
- `/health` endpoint, CORS configured for the Vite dev server
- Provider-agnostic `LLMClient` abstraction (Sprint 1 shipped it with an
  OpenAI implementation; Sprint 4 switched the active provider to Gemini,
  and a later dependency cleanup removed the unused OpenAI implementation
  and package entirely — see "Sprint 4 review notes")
- Feature-engineering column contract (`ml/features.py`) shared by future
  training and inference code
- Seed script + golden demo customer ("Ayşe Yılmaz") for the live-demo narrative
- Frontend routing shell, glass-card design system, persistent Copilot
  drawer (UI shell only), all navigation and placeholder pages in Turkish

## What's in Sprint 2

- Sprint 1 review fixes: see "Sprint 1 review notes" below
- `app/ml/train.py` — trains a churn model and scores every seeded customer
  into the `predictions` table
- `app/services/ml_service.py` — single-customer inference, ready for the
  What-If Simulator (Milestone 5)
- `GET /api/customers` — search, filter (risk tier / contract / internet
  service), sort, and paginate
- `GET /api/dashboard/summary` — KPI totals, risk-tier breakdown, top
  at-risk customers
- Dashboard page: real KPI cards + risk-tier chart + top-at-risk list
- Customers page: real search/filter/sort/paginated table with risk badges

## What's in Sprint 3

- Sprint 2 review fixes: see "Sprint 2 review notes" below
- **XGBoost replaces RandomForest** as the production model
  (`app/ml/train.py`, `MODEL_VERSION = "xgb-v1"`) — exact, fast SHAP
  TreeExplainer support and the model used in the hackathon demo
- SHAP explainability: every customer's `Prediction.shap_values` now holds
  a real SHAP payload (base value + per-field contributions)
- `GET /api/customers/{id}` — full customer detail + prediction + explanation
- Customer Detail page: probability, risk badge, confidence, SHAP feature
  importance chart, and an AI-friendly Turkish explanation

## What's in Sprint 4 — the agentic system

This is the core differentiator: a five-agent retention pipeline,
coordinated by an Orchestrator, backed by Gemini with deterministic
fallbacks everywhere an LLM is involved.

- **Gemini integration** (`app/services/llm_client.py`): `GeminiClient`,
  using Google's current unified `google-genai` SDK (`from google import
  genai`) — not the deprecated `google-generativeai` package. Reads
  `GEMINI_API_KEY` through `Settings`. Agents never import `google.genai`
  themselves; only this module does, and only `get_llm_client()` decides
  which provider is active. Originally shipped alongside a second
  `OpenAIClient` implementation as proof the `LLMClient` interface was a
  real provider boundary; removed in a later dependency cleanup since this
  project only uses Gemini — see "Dependency cleanup" below.
- **Risk Agent** (`app/agents/risk_agent.py`) — fully deterministic:
  priority, urgency, and workflow-entry decision from the XGBoost
  probability and customer revenue. No LLM call.
- **Explainability Agent** (`app/agents/explainability_agent.py`) — upgraded
  from Sprint 3's template to Gemini-generated `why_at_risk` /
  `business_interpretation` text, with the template kept as an automatic
  fallback. See the module docstring for exactly when each path runs.
- **Retention Strategy Agent** (`app/agents/retention_strategy_agent.py` +
  `strategy_rules.py`) — deterministic cost/ROI math, Gemini-generated
  narrative on top. Strategies are always ranked by ROI, never by anything
  Gemini decides.
- **Communication Agent** (`app/agents/communication_agent.py`) —
  Gemini-generated Turkish email + SMS drafts, with a deterministic SMS
  length guard and a template fallback.
- **Approval & Automation Agent** (`app/agents/approval_agent.py`) — fully
  deterministic state machine: Semi Autonomous always awaits human approval;
  Full Autonomous auto-approves only when a strategy's confidence score
  clears `FULL_AUTONOMOUS_CONFIDENCE_THRESHOLD` (default 0.85).
- **Orchestrator Agent** (`app/agents/orchestrator.py`) — runs the five
  agents in sequence, persists every step to `AgentRun` (durable audit
  trail — see "Sprint 3 review notes" pattern continued here) and
  `TimelineEvent`, creates `Campaign` rows, and generates the AI Executive
  Summary.
- `POST /api/customers/{id}/run-pipeline`, `GET /api/customers/{id}/timeline`,
  `POST /api/campaigns/{id}/approve`, `POST /api/campaigns/{id}/reject`.
- Customer Detail page: "AI Elde Tutma Pipeline'ı" panel — run the pipeline,
  see the executive summary and ranked strategies, approve/reject generated
  campaigns, and a visual agent timeline (agent name, status, duration,
  timestamp).
- `backend/tests/test_agents.py` — every agent unit-tested in isolation.

### AI usage rules, as actually implemented

Per the roadmap, these stay 100% deterministic Python — never sent to
Gemini/Azure as something to decide: XGBoost predictions, SHAP calculations, risk
scoring/priority, workflow state transitions, ROI/cost/retention-improvement
calculations. LLM is used only for natural language: explainability
narratives, strategy titles/descriptions, email/SMS copy, and the executive
summary — and every one of those has a deterministic fallback, so an LLM
outage degrades quality, not availability.

## Sisteme Güven ve Başarı Metrikleri (Trust & Verification)

ChurnPilot, "kara kutu" yapay zeka korkusunu ortadan kaldırmak üzere özel bir güven mimarisiyle tasarlanmıştır. Modelin ve ajanların doğruluğu şu şekilde güvence altına alınır:

### 1. Model Başarısı ve Şeffaflık (XGBoost & SHAP)
- **Doğru Metrik (Recall):** Müşteri kaybı tahmininde salt "Accuracy" (Doğruluk) yanıltıcıdır. Sistemin ana KPI'ı **Recall**'dur (Duyarlılık). *Örn: "Gerçekten gidecek olan 100 müşterinin %85'ini önceden tespit ettik."*
- **Matematiksel Şeffaflık (SHAP):** Sistem kimseye sebepsiz yere "Riskli" demez. SHAP TreeExplainer ile her kararın arkasındaki matematiksel neden (Örn: "Son 90 günde sipariş frekansı yarı yarıya düştü") grafiksel olarak sunulur. İşletme sahibi, sistemin "Neden" bu kararı verdiğini net bir şekilde anlar.

### 2. Ajan Güvenilirliği (Azure OpenAI / LLM)
- **Yarı Otonom Simülasyon (Dry-Run):** Ajanlar, güvenilirlikleri kanıtlanana kadar `AWAITING_APPROVAL` (İnsan Onayı Bekliyor) durumunda çalıştırılabilir. Pazarlama ekibi, YZ'nin ürettiği strateji ve mesajları bir süre sadece ekrandan okuyup onaylar (Approve). Mantıklı kararlar alındığı kanıtlandığında "Tam Otonom" (Full Autonomous) moda geçiş yapılır.
- **Güvenlik Ağı (Deterministic Fallback):** LLM API'sinde bir kesinti veya hatalı JSON üretimi yaşanırsa, sistem çökmek veya müşteriye anlamsız mesaj atmak yerine saniyesinde "Sabit Şablon" (Template) moduna geçer. Müşteri iletişimi asla riske atılmaz.
- **Sıkı Çerçeve:** Ajanlar serbest metin yerine sadece belirli bir JSON formatında (`response_format={"type": "json_object"}`) yanıt üretmeye zorlanarak halüsinasyon riski sıfıra yaklaştırılır.

### 3. İşletme İçin Kâr İspatı (A/B Testi)
Sistemin nihai başarısı kodla değil, kasaya giren parayla (ROI) ölçülür. ChurnPilot entegrasyonu sonrasında müşteri tabanının %10'u sisteme bırakılarak, manuel yönetilen %90'lık grupla kârlılık ve "Kurtarılan Gelir (Saved Revenue)" A/B testine tabi tutulur.

### Real email/SMS sending — see "Faz B" below

Sprint 4 originally shipped `simulate_send()` as a deliberately-isolated
stub — no real provider integrated, "sending" just marked a campaign `SENT`.
That stub has since been replaced with real Gmail SMTP + Twilio delivery;
see "Gerçek E-posta / SMS Gönderimi (Faz B)" further down for the current
behavior, including the safe simulation fallback when no credentials are
configured.

## What's NOT in Sprint 4 (by design — see later milestones)

- What-If Simulator, Segments, and Revenue Analytics pages are still
  placeholders at this point in the log — Sprint 5 below builds them
- Copilot chat — still a UI shell, not wired to an agent
- Alembic migrations (still `create_all` — flagged as a known follow-up
  since Sprint 2; now genuinely due, see "Sprint 3 review notes")
- Real email/SMS sending — see "Faz B" further down

## What's in Sprint 5 — polish and business impact

The final implementation sprint before demo prep. No new architectural
surface — everything here builds directly on Sprints 1-4's models,
services, and agent infrastructure.

- **What-If Simulator** (`app/services/simulation_service.py` +
  `app/agents/simulation_recommendation.py`) — re-runs the trained XGBoost
  model (via Sprint 3's `services/ml_service.py`) against a hypothetical
  version of a customer, compares it to their real current prediction, and
  ranks which *changed* inputs actually moved the model's SHAP-derived
  output. Gemini narrates the comparison into a Turkish recommendation
  (template fallback, same pattern as every other LLM step). Honest, stated
  limitation: `payment_method` is exposed as a control per the roadmap, but
  the trained model doesn't use it as a feature, so changing it alone never
  moves the prediction — the simulator says so explicitly rather than
  faking an effect. `POST /api/customers/{id}/simulate`,
  `GET /api/customers/{id}/scenarios` (saved runs, via the `Scenario` model
  Sprint 1 already defined for this).
- **Revenue Impact Dashboard** (`app/api/revenue.py`) — entirely
  deterministic, per the roadmap's explicit requirement. Reuses Sprint 4's
  strategy-economics engine (`app/agents/strategy_rules.py`) applied to
  every at-risk customer's best candidate, not just the one a pipeline run
  targets — so this page and an individual Retention Strategy Agent output
  are guaranteed to agree. `GET /api/revenue/summary`.
- **Customer Segmentation** (`app/ml/segment.py`) — K-Means over tenure,
  monthly spend, and churn probability, with a deterministic, rule-based
  mapping from raw cluster centroids to the five business-meaningful labels
  Sprint 1's `SegmentLabel` enum already anticipated (`loyal`,
  `price_sensitive`, `new`, `premium`, `at_risk`). `GET /api/segments/summary`;
  the Customers list (`GET /api/customers`) now also accepts `?segment=`.
- **Dashboard polish** — a `Skeleton`/`KpiCardSkeleton`/`TableRowsSkeleton`
  component set replacing bare spinners, fade-in/pop-in animation utilities,
  a responsive sidebar (icon-only below `lg`, so the app is usable on a
  narrower laptop or projector window), and consistent hover treatment on
  cards.
- **Demo Mode** (`/demo`, `DemoModePage.tsx`) — a full-screen, presentation-
  paced walkthrough of the real pipeline against the golden demo customer:
  Customer → Prediction → SHAP → Risk Agent → Explainability Agent →
  Strategy Agent → Communication Agent → Approval → Campaign Created →
  Retention Completed, each step revealed with a timestamp and animation.
  This calls the *real* `run-pipeline` endpoint — nothing here is faked or
  mocked; the staggered reveal is a client-side presentation pace applied
  to real data, not a simulation of the system. One deliberate choreography
  decision: if the golden customer's strategy confidence lands below the
  full-autonomous auto-approval threshold, Demo Mode auto-calls the real
  `/approve` endpoint after a beat, so a live demo always reaches
  "Retention Completed" without requiring a manual click — still a genuine
  API call, just automated for a hands-off presentation.

## Running and testing the complete project

```bash
# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then set GEMINI_API_KEY — see "Gemini setup" above
python -m app.seed.seed_data
python -m app.ml.train
python -m app.ml.segment
uvicorn app.main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
cp .env.example .env
npm run dev
```

Then, in the browser (`localhost:5173`):

1. **Panel** — KPIs and risk-tier chart should show real numbers.
2. **Müşteriler** — search, filter by risk tier and segment, sort, paginate.
3. Click into a customer — **Customer Detail** shows probability, SHAP
   chart, AI explanation, and the "AI Elde Tutma Pipeline'ı" panel. Run it,
   approve/reject the generated campaigns.
4. **Senaryo Simülatörü** — pick a customer (or arrive via "Simülatörde Aç"
   on their detail page), adjust a slider or dropdown, run the simulation.
5. **Segmentler** — pie chart + segment cards; click one to jump to a
   filtered Customers view.
6. **Gelir Analitiği** — five deterministic revenue KPIs.
7. **Demo Modu** — click "Demoyu Başlat" and watch the full pipeline play
   out for the golden demo customer.

Backend unit tests: `cd backend && python -m unittest tests.test_agents -v`
(see "Testing the Sprint 4 agents individually" above — unaffected by
Sprint 5, still passes as-is since no agent's public interface changed).

## Final codebase review (Sprint 5)

Requested explicitly this sprint — a full pass over the whole project, not
just the new code:

- **Duplication removed:** the "which risk tiers count as at-risk"
  `("high", "critical")` tuple was about to exist in three places
  (Dashboard, the new Revenue endpoint, and implicitly wherever the next
  feature needed it). Extracted to `app/services/at_risk.py`, which also
  now owns the shared "give me the actual at-risk Customer/Prediction rows"
  query — Dashboard uses the constant, Revenue uses both.
- **No regressions:** every Sprint 1-4 endpoint's response shape is
  additive-only this sprint (`segment_label` added as an optional field to
  `CustomerListItem`/`CustomerDetail`; nothing removed or renamed). The
  Sprint 4 agent test suite requires no changes and still passes.
- **Performance:** the Revenue and Segmentation endpoints both do their
  heavy lifting (candidate-strategy generation, K-Means) in pure Python/
  NumPy with zero Gemini calls — safe to load on every Dashboard-adjacent
  page view without latency or cost concerns. `python -m app.ml.segment`
  is a separate, explicit command rather than folded into `train.py`, so
  retraining the model doesn't force a re-cluster (and vice versa) when
  only one of the two actually needs to change.
- **What I'd genuinely do next, in priority order, post-hackathon**
  (updated — item 2 shipped, see "Gerçek E-posta / SMS Gönderimi (Faz B)"):
  1. Alembic migrations — flagged every sprint since Sprint 2, still the
     top real risk to the schema as it keeps growing.
  2. ~~A real email/SMS provider behind `simulate_send()`~~ — done, see Faz B.
  3. Calibrate the strategy-economics constants in `strategy_rules.py`
     against real campaign outcomes once `CampaignOutcome` data exists —
     they're currently honest, stated assumptions, not fitted numbers (the
     Dinamik Otonom Strateji Ajanı's policy-enforcement clamps are also
     hand-picked, same caveat applies).
  4. The Copilot drawer is still a UI shell with no agent behind it — the
     one piece of the original architecture doc that never got built.

## What's NOT in Sprint 5 (by design — see later milestones)

- Copilot chat — still a UI shell, unchanged from Sprint 1
- Campaign Center as its own dedicated list/management view — built later,
  see "Gerçek E-posta / SMS Gönderimi (Faz B)" further down
- Alembic migrations — still deferred, see "Final codebase review" above
- Real email/SMS sending, e-commerce data schema, and the dynamic strategy
  agent — all built in the post-Sprint-5 phases documented below

## Sprint 1 review notes

Before starting Sprint 2, the Sprint 1 codebase was reviewed and the
following were fixed or hardened:

- **Bug:** every `Enum`-typed column (`ContractType`, `RiskTier`, campaign
  statuses, etc.) relied on SQLAlchemy's default enum handling, which
  persists the Python enum member's `.name` (`"MONTH_TO_MONTH"`) rather than
  its `.value` (`"month_to_month"`). Every call site in the codebase — the
  seed script, the golden demo customer, and now the Sprint 2 API — passes
  and expects the lowercase `.value` form, so this would have failed the
  moment `seed_data.py` tried to insert a row. Fixed via a shared
  `str_enum()` helper in `app/database.py` used by every model.
- Replaced the deprecated `@app.on_event("startup")` hook with a FastAPI
  `lifespan` context manager.
- Added indexes: `Customer.name` (Sprint 2 search) and a composite
  `(customer_id, predicted_at)` index on `predictions` (Sprint 2's
  latest-prediction-per-customer join).
- Seeded the synthetic name generator's RNG (`random.seed`) so a full
  reset-and-reseed is fully reproducible, not just the numeric columns.
- Added `ml/features.py:build_feature_frame()` so training and inference
  code explicitly reindex to `MODEL_FEATURE_COLUMNS` instead of relying on
  Python dict insertion order matching that contract by convention.

## Sprint 2 review notes

Before starting Sprint 3, the Sprint 1 + 2 codebase was reviewed again:

- **Bug:** `services/ml_service.py` cached the loaded model with a bare
  `@lru_cache`, so a long-running API process kept serving predictions from
  a stale model after a retrain in another terminal — exactly the kind of
  thing that bites you retraining right before a hackathon demo. Replaced
  with a small cache that checks the model file's mtime on every call and
  reloads automatically when it changes.
- Risk-tier thresholds and confidence-score math were duplicated
  byte-for-byte between `ml/train.py` and `services/ml_service.py`.
  Extracted to `app/ml/scoring.py`, imported by both.
- `GET /api/customers` and the new `GET /api/customers/{id}` built the same
  Customer/Prediction → response-field mapping independently. Extracted to
  a shared `_customer_fields()` helper in `app/api/customers.py`.

## Sprint 3 review notes

Before starting Sprint 4, the codebase was reviewed once more, with the
agentic system specifically in mind:

- **Schema gap:** `CampaignStatus` had `pending / approved / rejected /
  sent / outcome_logged` but nothing distinguishing "just created" from
  "blocked on a human's approval" — the roadmap's own flow diagram needs
  that distinction. Added `AWAITING_APPROVAL`.
- **Transaction-durability bug caught during implementation:** the
  Orchestrator's step-by-step persistence originally used `flush()`
  (visible within the transaction) instead of `commit()` (durable). Since
  `AgentRun` exists specifically to survive a later step's failure for
  debugging, a mid-pipeline error would have rolled back every earlier
  step's audit record along with it — exactly the failure mode the table
  exists to prevent. Fixed before it shipped, not after.
- Every LLM-backed agent (Explainability, Strategy, Communication) follows
  the same shape: deterministic data in, Gemini asked only to narrate it,
  automatic template fallback on any failure — established once in
  Sprint 3 for Explainability, applied consistently to the three new agents
  rather than each inventing its own error-handling pattern.
- `send-simulation` logic was about to be written twice (once for
  full-autonomous auto-approval, once for the human `/approve` endpoint).
  Extracted to one module-level `simulate_send()` function both paths call.

## Dependency cleanup (post-Sprint 5)

`pip install -r requirements.txt` failed with `ResolutionImpossible` in a
clean Python 3.11 environment: `pydantic==2.9.2` was exact-pinned below the
floor newer `google-genai` releases require (`pydantic>=2.12.5`,
`httpx>=0.28.1`) — pip had no way to satisfy an exact old pin and a newer
package's floor simultaneously.

Fixed by regenerating `requirements.txt` in full rather than bumping one
package at a time (bumping pydantic alone would have just moved the
conflict to pydantic-settings or httpx next):

- **Web/validation/LLM-SDK cluster** (`fastapi`, `pydantic`,
  `pydantic-settings`, `httpx`, `google-genai`) — switched from exact pins
  to version floors (`>=`), so pip's resolver picks mutually compatible
  versions across all five instead of every future release of any one of
  them risking the same conflict again.
- **ML/data + DB stack** (`sqlalchemy`, `pandas`, `numpy`, `scikit-learn`,
  `xgboost`, `shap`, `joblib`) — left exact-pinned. Nothing here depends on
  the cluster above, and exact pins are what make model training
  reproducible, which is worth keeping.
- **Removed `openai` and `lightgbm` entirely.** `openai` per direct
  instruction — Gemini is the only provider this project uses, and
  `OpenAIClient` (kept since Sprint 4 as a second implementation proving
  the provider boundary was real) is gone along with it; see
  `app/services/llm_client.py`'s docstring. `lightgbm` was never actually
  imported anywhere in the codebase — a Sprint 1 speculative dependency for
  a model choice the project ended up not using (XGBoost, since Sprint 3).
  Both were pure dead weight in the resolution graph.

**No application code changes were needed beyond removing `OpenAIClient`**
— `config.py` uses `pydantic_settings.BaseSettings`/`SettingsConfigDict`,
and `GeminiClient` uses `google.genai.Client(...)` /
`types.GenerateContentConfig(...)`, both stable, long-standing v2/current-SDK
API surfaces unaffected by the version bumps. Nothing in this codebase
calls `httpx` directly (it's a transitive dependency of `google-genai`
only), so httpx's own 0.28 changes don't touch any of our code either.

**Verification performed.** I don't have network access in this environment
to run a live `pip install`, so I couldn't do the literal
`pip install -r requirements.txt && uvicorn app.main:app` end-to-end. Instead
I did the strongest verification actually possible without it:

- **Real execution, not just reading.** I built minimal functional stand-ins
  for every unavailable package (`pydantic`, `pydantic-settings`, `fastapi`,
  `sqlalchemy`, `google-genai`, `xgboost`, `shap`, `joblib`, `scikit-learn`)
  — not fakes that just avoid `ImportError`, but ones that actually execute
  class definitions, construct objects, and run methods — and used them to
  genuinely import and run this codebase:
  - **All 52 modules under `app/`** import successfully with zero failures
    (looped over every file, not spot-checked).
  - **`app.main`'s FastAPI app object** constructs successfully with all 7
    routers mounted, and its `lifespan` startup context manager runs without
    error — the Python-level equivalent of what `uvicorn app.main:app`
    needs to succeed before it starts accepting requests.
  - **All 12 tests in `tests/test_agents.py` pass**, for real — actual
    assertions on actual `RiskAgent`/`ApprovalAgent`/`ExplainabilityAgent`/
    `RetentionStrategyAgent`/`CommunicationAgent`/`strategy_rules` behavior,
    exercising real enums from `app/models/**` (only their SQLAlchemy
    *column* definitions were stubbed — the Python `Enum` classes themselves
    are the real, unmodified ones).
  - **`app/ml/train.py`'s actual training code path** — dataset generation,
    `train_test_split`, `model.fit()`, metrics computation — runs end to end
    with zero Python-level errors (the stub XGBoost produces meaningless
    metrics, which is expected and irrelevant; what matters is nothing
    raised `TypeError`/`AttributeError`/`ImportError` anywhere in that path).
  - This surfaced exactly two bugs — both in *my stub scaffolding*
    (missing `joblib.Parallel`/`cpu_count`, needed transitively by a
    locally-installed but version-mismatched real scikit-learn), **zero in
    ChurnPilot's own code.**
- **Researched, not assumed, the actual current API surface.** Checked
  current documentation/changelogs for pydantic 2.12/2.13, pydantic-settings
  2.7+, httpx 0.28, and google-genai directly rather than relying on
  possibly-stale training knowledge:
  - httpx 0.28's breaking changes are entirely about the `proxies=`/`app=`
    client constructor arguments — this codebase never instantiates
    `httpx.Client` directly (it's only a transitive dependency of
    `google-genai`), so none of that applies here.
  - Every pydantic symbol this codebase imports (`BaseModel`, `ConfigDict`,
    `Field`, `ValidationError`) and every pydantic-settings symbol
    (`BaseSettings`, `SettingsConfigDict`) has been stable, unchanged public
    API since pydantic 2.0 — confirmed against the 2.12/2.13 changelogs,
    which contain no entries affecting any of them.
  - FastAPI's own compatibility layer explicitly version-gates for
    "Pydantic 2.12" per its source (suppressing a new warning class
    introduced in that release) — i.e. FastAPI already handles this pydantic
    version by design, not by accident.
  - **No deprecated Gemini SDK APIs are used.** `GeminiClient`'s exact
    pattern — `genai.Client(api_key=...)`,
    `client.models.generate_content(model=, contents=, config=types.GenerateContentConfig(system_instruction=, temperature=, response_mime_type=))`,
    `response.text` — matches Google's own official migration guide
    verbatim, dated within the last few weeks.

**What's still genuinely unverified:** an actual `pip install` resolving
against the real PyPI index with the real current package releases (as
opposed to my hand-built stand-ins), and a real ASGI server accepting real
HTTP requests against a real SQLite database. I'm confident in this — the
combination of real code execution against a faithful stub layer plus
direct research into current breaking-changes documentation is about as
strong as verification gets without literally running `pip install` — but
please run it for real in your Python 3.11 environment and tell me
immediately if anything still surfaces.

## E-Ticaret Dönüşümü (Faz A)

The product pivoted from a telecom-subscriber domain to an **e-commerce
customer** domain — every schema field, synthetic data generator, offer
type, and UI label described in the Sprint sections above referred to telco
concepts (`contract_type`, `internet_service`, `tech_support`) that no
longer exist in the codebase. This section documents the mapping so the
Sprint history above still makes sense read in light of the current schema.

- **Schema** (`app/models/customer.py`, `app/ml/features.py`):
  `ContractType`/`InternetService` → `MembershipTier` (`basic`/`plus`/`premium`)
  and `ProductCategory` (`fashion`/`electronics`/`grocery`); `tech_support`
  → `app_installed`; two new numeric features with no telco equivalent —
  `order_count` and `days_since_last_order` (recency, the dominant churn
  signal in e-commerce). `Customer` also gained `email`/`phone` columns,
  used by Faz B below.
- **Model**: `MODEL_VERSION = "ecom-v1"`. `app/ml/train.py`'s synthetic
  data generator (`_generate_labeled_dataset`) now derives churn risk from
  recency + order frequency + membership tier + app usage, weighted so a
  long-silent, `basic`-tier, app-less customer is the highest-risk profile
  — same "illustrative, not fit to real data" caveat as Sprint 4's original
  rule, just for the new domain. `backend/data/ecommerce_churn.csv` is the
  hook for a real dataset later (same not-yet-implemented-mapping pattern
  Sprint 1 used for the Telco CSV).
- **Offers** (`app/models/campaign.py::StrategyType`): `contract_upgrade` /
  `service_bundle` → `membership_upgrade` / `free_shipping`; `discount`,
  `retention_call`, `loyalty_reward` carried over conceptually with
  e-commerce-flavored copy. Superseded for the primary path by the Dinamik
  Otonom Strateji Ajanı section below — these five types now only drive the
  deterministic fallback.
- **Frontend**: `types/customer.ts`, the Customers table, Customer Detail's
  info panel, and the What-If Simulator's sliders all updated to the new
  fields (kıdem/harcama/sipariş sayısı/son sipariş/üyelik/kategori).

## Gerçek E-posta / SMS Gönderimi (Faz B)

Sprint 4's `simulate_send()` stub is gone. Campaigns are now delivered for
real:

- **`app/services/notifications.py`** — `send_email()` via Gmail SMTP
  (`smtplib` + `ssl`, stdlib only) and `send_sms()` via the Twilio REST API
  (plain `httpx` POST — no `twilio` SDK dependency added). Both return a
  `SendResult(success, provider, message_id, error)` and never raise: no
  credentials configured, or `NOTIFICATIONS_ENABLED=false`, falls back to a
  `provider="simulated"` success so the pipeline and tests keep working
  without any setup.
- **`app/models/delivery_log.py`** — a `DeliveryLog` row is written for
  *every* send attempt (real or simulated), success or failure, including
  the provider's error message — the durable audit trail a single
  `Campaign.status` field can't hold on its own.
- **Approve and Send are now two separate, explicit human actions** (not
  one implicit step): `POST /api/campaigns/{id}/approve` only moves a
  campaign to `APPROVED` — it does not send anything. `POST
  /api/campaigns/{id}/send` performs the real send and sets `SENT` or
  `FAILED`. `POST /api/campaigns/{id}/retry` re-sends a `FAILED` campaign
  through the same path. The full-autonomous orchestrator path still sends
  immediately on auto-approval — same underlying `send_campaign()` function
  as the human `/send` endpoint, so there's exactly one send code path,
  not two that could drift.
- **Campaign Center** (`/kampanyalar`, `CampaignCenterPage.tsx`) — the
  dedicated cross-customer view Sprint 4/5 deferred: four tabs (Bekleyen /
  Onaylanan / Gönderilen / Başarısız), 30-second auto-refresh, inline
  Onayla/Reddet/Gönder/Yeniden Dene actions, and the latest delivery error
  shown inline on failed campaigns.
- **Config** (`backend/.env`): `NOTIFICATIONS_ENABLED`, `SMTP_HOST/PORT/USER/PASSWORD`,
  `MAIL_FROM`, `TWILIO_ACCOUNT_SID/AUTH_TOKEN/FROM_NUMBER`. Gmail requires a
  16-digit **App Password** (not your account password) with 2-Step
  Verification enabled. Twilio's free trial account only sends to
  phone numbers you've verified in the Twilio console, and prefixes
  messages with "Sent from a Twilio trial account" — fine for a demo, a
  one-line swap to a paid number for production.

## Dinamik Otonom Strateji Ajanı

The biggest architectural change since Sprint 4: `RetentionStrategyAgent`
is no longer a copywriter reformatting five fixed offer types — it's a
strategist that invents customer-specific retention offers from scratch.

- **Input**: the agent now also receives the Explainability Agent's
  `why_at_risk` narrative and top SHAP factors (`app/agents/orchestrator.py`
  passes `explanation` into `strategy_agent.generate()`), so the LLM can
  target the actual reason a customer is leaving — e.g. "hasn't ordered in
  92 days" gets a win-back offer, not a generic discount.
- **Output**: up to 3 freeform strategies (`app/models/campaign.py::StrategyType.DYNAMIC`),
  each with an LLM-authored title, description, and self-estimated cost /
  retention improvement / confidence — genuinely different offers per
  customer (verified against real Azure OpenAI output: e.g. "30 Günlük
  Sabit Market Fiyatı" for a price-sensitive grocery shopper, "Mahalle
  Sepeti Geri Dönüş Paketi" for a lapsed regular — neither is one of the
  five fixed types).
- **Policy enforcement (the safety net)** — `RetentionStrategyAgent._enforce_policy()`:
  the LLM's raw numbers are never used directly.
  - Cost is clamped to at most 1× the customer's monthly spend.
  - Retention improvement is clamped to at most the customer's actual churn
    probability, and to 90% regardless.
  - Any explicit discount percentage the LLM states is clamped to 50% —
    and if it was reduced, the corrected percentage is substituted back
    into the displayed title/description so the customer is never promised
    more than what's actually clamped.
  - **ROI is never taken from the LLM.** It's recomputed deterministically
    from the clamped cost and retention improvement, exactly like the
    original Sprint 4 rule engine did — an LLM cannot claim a fictitious
    ROI that doesn't match the (already-limited) numbers backing it.
  - Confidence score is a 50/50 blend of the LLM's self-reported confidence
    and the model's own prediction confidence, same weighting as before.
- **Fallback**: if the LLM is unavailable, times out, or returns something
  that fails `_DynamicStrategyBatch` validation, the agent transparently
  falls back to the original deterministic `strategy_rules.py` + template
  narrative path — the pipeline is never left without a strategy.
- Strategies are still always ranked by ROI, deterministically, after
  policy enforcement — never by anything the LLM decides, unchanged from
  the Sprint 4 design principle.

ChurnPilot

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README