内容
="center">
<img src="assets/brand/churncue-mark alt="ChurnCue logo" width="112" />
# ChurnCue
**了解可能流失的用户。识别信号。保护续**
面向 Archestra 的生产导向型客户留存智能，由 MCP 上的确定性机器学习提供支持。
[](https://github.com/Bhaktabahadurthapa/ChurnCue/actions/workflows/ci.yml)
[](https://github.com/Bhaktabahadurthapa/ChurnCue/actions/workflows/codeql.yml)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](Dockerfile)
[](LICENSE)
[快速入门](#快速入门) · [架构](docs/ARCHITECTURE.md) · [Archestra 设置](docs/ARCHESTRA_SETUP.md) · [应用提示](docs/ARCHESTRA_APP_PROMPT.md) · [演示脚本](docs/DEMO_SCRIPT.md)
</div>
<img src="assets/brand/churncue-hero.png" alt="ChurnCue 客户留存智能流程图" width=" />
## 周一的问题
客户在续约风险收入之前，需要反复问题：
哪些客户可能2. 本周哪些客户风险增加？
3. 哪些观察到的了变化？
4暴露了多少经常？
5.接下来应该采取什么
ChurnCue 将匿名客户健康记录转换为优先排序的、基于证据的救援队列。它在确定性 Python 服务中保留模型计算，并在明确的人工审批后将 Slack 通知保留在后台。
## 为什么选择 ChurnCue
| 功能 | 提供内容 |
|---|---|
| 确定性 | 所有指标和概率都来自 scikit-learn — LLM。 |
| 每周变动 | 比较当前概率与之前的风险，并识别新风险的账户。 |
| 收入优先级 | 量化概率加权月度和年度收入暴露。 |
| 证据，而不是猜测 | 返回来自观察到的产品、支付、支持、登录、续约和满意度信号的稳定原因代码。 |
| 受控操作 | 生成 Slack-ready 预览，但发送外部消息。 |
边界 | 验证输入限制II 拒绝、安全工件解析、结构化日志、健康检查和非根容器。 |
## 系统架构
<div align="center">
<img src="docs/assets/churncue-end-to-end-handwritten.png" alt="手写的 ChurnCue 架构图，显示 Archestra、MCP 网关、数据集、实验和评分流程" width="100%" <p><em>客户记录保留在 ChurnC，而紧凑的标识符在 MCP 工具之间安全em></p>
</div>
```mermaid
flowchart LR
Demo[匿名演示 CSV]
subgraph Archestra[Archestra]
AppurnCue 应用 Orchestrator[MCP 调度器]
Approval{ end
[ChurnCue Load[加载和存储数据集]
Profile[配置文件和验证]
Train[训练和比较]
Score[评分和解释]
Report[救援报告]
Runtime[(数据集和评分运行状态)]
end
Demo --> Load
App --> Orchestrator --> Load
Load -->|dataset_id| Profile --> Train --> Score
Score -->|score_run_id| Report
Load --> Runtime
Score --> Runtime
Train --> Metadata[(SQLite 元数据)]
Train -->joblib 工件 Report --> Approval
|仅审批| Slack MCP]
```
**** 是身份验证的应用 MCP 调度器。urnCue MCP** 在内部存储演示行，仅向模型公开紧凑的数据集和评分运行标识符。**Slack MCP** 仅接收人工审批的消息。
## 受控的救援工作流程
<div align="center">
<img src="docs/assets/churncue-governed-rescue-workflow="显示客户成功经理询问 ChurnCue 可能区块图，Archestra 控制工具访问，ChurnCue MCP 运行机器学习流程，模型解释验证结果，并将优先的救援报告返回给经理" width="100%" <p><em>机器学习预测，MCP模型解释，Archestra 控制整个工作流程。</em></</div>
区块图遵循实际的客户成功请求：**“哪些客户本周最，我们应该首先联系谁？”**
1. 经理estra 中提出业务问题。
2. Archestra 代理仅选择已批准的 ChurnCue 工具。访问控制、防护栏和活动日志管理交互。
3. ChurnCue MCP 通过八个有界工具公开预测工作流程。
4. 确定性机器学习流程训练、评分和排名客户，返回验证的分数和紧凑的标识符。
5. 模型解释工具生成的无需发明计算的结果。
6. Archestra 呈现优先的救援报告，以便经理知道首先联系谁。
## 每周审查流程
```text
加载演示 → dataset_id → 配置文件质量 → 训练 3 个模型 → experiment_id
→ 评分客户 → score_run_id → 比较风险 → 救援报告
→ 预览 Slack 消息 → 人工审批 → Slack MCP 发送
```
## 快速入门
### 在本地运行
```bash
git clone https://github.com/Bhaktabahadurthapa/ChurnCue.git
cd ChurnCue
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
python scripts/generate_demo_data.py
ch
```
验证服务：bash
curl http://localhost:8000/health
npx -y @modelcontextprotocol/inspector
```
将检查器连接到 `http://localhost:8000/mcp`，使用 **Streamable HTTP**。
### 使用 Docker 运行
```bash
docker compose up --build -d
docker compose ps
curl http://localhost:8000/health
```
使用 `docker compose down` 停止服务。SQLite 元数据和模型工件保留在命名卷中。
## 连接到 Archestra
在 Archestra 的私有 MCP 注册表中注册远程 Streamable HTTP 服务器：
```text
名称：ChurnCue
网址： http://host.docker.internal:8000/mcp
```
基于 Linux 的 Archestra 容器可能需要 `host.docker.internal:host-gateway`。将所有八个工具分配给应用，然后将[即用应用提示](docs/ARCHESTRA_APP_PROMPT.md)粘贴到 Archestra Chat 中。
## MCP 工具表面
| 工具 | 责任 | 关键输出 |
|---|---|---|
| `health_check` | 运行时准备情况 | 名称、版本、传输、时间戳 |
| `load_demo_dataset` | 存储有界匿名演示数据 | 数据集 ID、计数、摘要 |
| `profile | 模式和质量分析 | 类型、缺失重复项、摘要 |
| `train_models` | 可复制的模型评估 | 指标、混淆矩阵、推荐模型 |
| `score_customers` | 按 ID 评分数据集 | 评分运行 ID、总数、风险预览 |
| `compare_weekly_risk` | 比较按 ID 评分的运行情况 | 移动总数和顶部变化预览 |
| `explain_risk` | 确定性原因代码 | 证据和非因果声明 |
| `generate_rescue_report` | 操作优先级 | 总数、优先级队列、Slack-ready 预览 |
推荐的调用顺序：
```text
load_demo_dataset → dataset_id → profile_dataset + train_models
dataset_id + experiment_id → score_customers → score_run_id
score_run_id → compare_weekly_risk + explain_risk + generate_rescue_report
```
## 机器学习流程
| 阶段 | 实现 |
|---|---|
| 验证 | 二进制目标、两类、最小样本大小、有界标量记录 |
| 泄漏控制 | 删除 `customer_id`、目标和预测派生字段 |
| 缺失值 | 数值中位数填补；分类中最频繁的填补 |
| 编码 | 标准缩放和未知安全的一热编码 |
| 评估 | 固定 80/20 分层分割，随机状态为 42 |
| 模型 | 逻辑回归、随机森林、梯度提升 |
| 指标 | 准确率、精度、召回率、F1-AUC、混淆矩阵 |
| 选择 | 最高的 ROC-AUC，F1 作为 tie-break| 持久性 | 完整的流程在 joblib 中；SQLite 中的不可变实验元数据 |
包含的数据集包含 50 个可复制的合成客户，不真实的个人数据。
## 配置
所有运行时变量都使用 `CHURNCUE_` 前缀。安全默认值在 [.env.example](.env.example) 中| 变量 | | 目的 |
---:|---|
|URNCUE_HOST`.0.0.0` | 地址 |
| `CHUE_PORT` |0` | MCP 和健康检查端口 |
|NCUE_DATABASE_PATH` | `data/churn` | 实验元数据库 |
| `CHUE_ARTIFACT_DIR` | `data/art | 受信任的模型工件目录 |
| `NCUE_DEMO_DATA_PATH` | `data_churn_demo.csv` | 打包演示源 |
CHURNCUE_ROWS` | `5000` | 最大 MCP |
| `CHURNCUE_MAX_DEMO_ROWS` | `50` | 一个演示数据集中存储的最大记录数 |
| `CHUR_STRING_LENGTH`200` | 字符串边界 |
|URNCUE_RANDOM_STATE` | `42` | 可复制的 ML | `CHURNCUE_PUBLISHED_PORT `8000` | 可选的 Compose 主机 |
存储库中不包含任何 API 密钥或客户凭证。
## 安全性和隐私
- 仅限匿名 `CUST-*` 标识符；公共 P字段在 MCP 边界被拒绝。
- 数据集和评分行保留在 ChurnCue 进程中；MCP 调用使用不透明的标识符。
- 行、字段、字符串、概率和模式限制保护资源边界。
- 实验 ID 仅解析为服务创建的工件，位于配置目录下方。
- 服务不执行任意代码执行、任意路径读取、浏览器获取或外部消息。
- 容器以 UID/GID `10001` 运行，删除 Linux 功能，并启用 `no-new-privileges`。
- 生产部署应在 Archestra 或受信任的网关处终止身份验证的 TLS。
在生产使用或漏洞报告前，请查看 [SECURITY.md](SECURITY.md)。
## 存储库布局
```text
.
├── assets/brand/ # 存储库身份和英雄艺术作品
├── data/demo/ # 可复制的匿名数据集
├── data/artifacts/ # 运行时模型流程（已忽略）
├── docs/ # Archestra、架构和演示指南
├── scripts/ # 演示数据生成
├── src/churncue/ # MCP 服务器和确定性业务逻辑
├── tests/ # 核心行为和边界覆盖
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml
```
## 工程质量
```bash
ruff check .
ruff format --check .
pytest
```
测试配置强制执行至少 80% 的核心覆盖率。CI 在每次拉取请求上运行 linting、格式化、测试、软件包安装和容器构建。
## 文档
| 指南 | 受众 |
|---|---|
| [架构](docsITECTURE.md) | 工程师和安全审查员 |
| [Archestra 设置](docs/ARCHESTRA_SETUP.md) | 连接 MCP 服务的操作员 |
| [Archestra 应用提示](docs/ARCHESTRA_APP_PROMPT.md) | 生成接口的应用构建者 |
| [三分钟演示](docs/DEMO_SCRIPT.md) | 黑客马拉松演讲者 |
| [贡献](CONTRIBUTING.md) | 贡献者和维护者 |
| [安全](SECURITY.md) | 漏洞报告者和操作员 |
## 演示和截图
存储库包括完整的[小于三分钟的演示运行手册](docs/DEMO_SCRIPT.md)。在此记录最终的公共视频网址和 Archestra 截图；不将模拟浏览器结果作为真实产品输出呈现。
## 已知限制
- 合成训练数据演示工作流程；它不是生产流失策略。
- 阈值原因代码是操作信号，而不是因果或 SHAP 解释。
- SQLite 和本地工件针对单个服务实例。
- 风险阈值是固定的产品规则，应在生产使用前进行校准。
- 身份验证、授权、TLS、Sheets 访问和 Slack 交付是外部部署责任。
## 路线图
- 时间感知评估、概率校准和漂移监测
- 托管元数据存储和基于对象的模型工件
- 租户感知授权和干预审计事件
- 基于反馈的再培训和干预结果衡量
- 发布具有签名出处和 SBOM 的容器版本
## 贡献和许可证
欢迎贡献。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，遵循 [Code of Conduct](CODE_OF_CONDUCT.md)，并使用问题模板进行可复制的报告。
ChurnCue 在 [MIT License](LICENSE) 下可用。
---
<div align="center">
为 Archestra 应用黑客马拉松而建，使用 Python、scikit-learn、FastMCP 和人类判断。
</div>
