Metadata-Version: 2.4
Name: certiflow
Version: 0.1.0
Summary: Confidence fusion, risk scoring & drift detection pipeline — from raw logits to actionable risk levels in five layers.
Author: 刘秉其
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/certiflow
Project-URL: Repository, https://github.com/your-org/certiflow
Project-URL: Issues, https://github.com/your-org/certiflow/issues
Project-URL: Documentation, https://github.com/your-org/certiflow#readme
Keywords: confidence,fusion,risk,drift-detection,ema,pipeline
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Dynamic: license-file

# CertiFlow

零依赖（仅 numpy）的置信度融合与风险评分工具包。从分类器的原始 logits 到最终的风险评级，五层流水线即插即用。

## 安装

```bash
# 从 PyPI 安装（发布后）
pip install certiflow

# 或从源码安装（开发模式）
git clone https://github.com/your-org/certiflow.git
cd certiflow
pip install -e .

# 安装可选 YAML 支持
pip install -e ".[yaml]"

# 安装开发依赖
pip install -e ".[dev]"
```

## 快速开始

```python
from certiflow import ConfidencePipeline, ConfidenceConfig

config = ConfidenceConfig.from_dict({"alpha": 0.6, "output_threshold": 0.2})
pipeline = ConfidencePipeline(config)

# 逐帧流式处理
result = pipeline.process_logits(logits_array)  # -> FusionResult | None
if result:
    print(result.event_type, result.confidence)

# 批量处理事件列表
events = [
    {"event_type": "alarm", "confidence": 0.85, "start_sec": 0.0, "end_sec": 1.0},
    {"event_type": "alarm", "confidence": 0.90, "start_sec": 0.8, "end_sec": 1.8},
]
full = pipeline.process_events(events)
print(full.events_merged)   # 合并后的事件
print(full.risk.score)      # 风险分 [0, 1]
print(full.drift.detected)  # 是否漂移
```

## 架构

```
              ┌─────────────┐
              │   logits    │
              └──────┬──────┘
                     │
                     ▼
        ┌────────────────────────┐
        │  Layer 1 · softmax     │  logits → 概率向量
        └───────────┬────────────┘
                    │
                    ▼
        ┌────────────────────────┐
        │  Layer 2 · EMA 融合    │  p̃_t = α·p_t + (1−α)·p̃_{t−1}
        └───────────┬────────────┘
                    │
              ┌─────┴──────┐
              │   events   │
              └─────┬──────┘
                    │
                    ▼
        ┌────────────────────────┐
        │  Layer 3 · 事件合并    │  合并同类重叠/相邻事件
        └───────────┬────────────┘
                    │
                    ▼
        ┌────────────────────────┐
        │  Layer 4 · 风险评分    │  → low / medium / high
        └───────────┬────────────┘
                    │
                    ▼
        ┌────────────────────────┐
        │  Layer 5 · 漂移检测    │  threshold / z_test / page_hinkley
        └───────────┬────────────┘
                    │
                    ▼
              ┌───────────┐
              │  result   │
              └───────────┘
```

| 层级 | 模块 | 类 / 函数 | 作用 |
|------|------|-----------|------|
| 1 | `confidence_fusion` | `softmax()` | logits → 概率向量 |
| 2 | `confidence_fusion` | `ConfidenceFusion` | 因果 EMA 平滑：`p̃_t = α·p_t + (1−α)·p̃_{t−1}` |
| 3 | `event_merger` | `merge_events()` | 合并同类重叠/相邻事件，保留最高置信度 |
| 4 | `risk_engine` | `RiskEngine` | 从置信度统计量加权评分 → low / medium / high |
| 5 | `drift_monitor` | `DriftMonitor` | 在线漂移检测（threshold / z_test / page_hinkley） |

每层可独立使用，也可通过 `ConfidencePipeline` 一键串联。

## 配置

所有参数通过 `ConfidenceConfig` 统一管理，支持三种初始化方式：

```python
# 1. 直接构造
from certiflow import ConfidenceConfig, FusionConfig, DriftConfig
config = ConfidenceConfig(
    fusion=FusionConfig(alpha=0.7, output_threshold=0.15),
    drift=DriftConfig(mode="z_test"),
)

# 2. 扁平字典
config = ConfidenceConfig.from_dict({
    "alpha": 0.6,
    "output_threshold": 0.2,
    "mode": "threshold",
})

# 3. YAML 文件（需安装 pyyaml）
config = ConfidenceConfig.from_yaml("config.yaml")
```

### 核心参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `alpha` | 0.6 | EMA 平滑因子 ∈ (0, 1]，越大越偏向最新帧 |
| `output_threshold` | 0.2 | 融合后置信度低于此值的结果被过滤 |
| `base_threshold` | 0.05 | 单帧置信度低于此值时跳过（减少噪声） |
| `max_gap_sec` | 0.10 | 事件合并的最大时间间隔（秒） |
| `medium_threshold` | 0.40 | 风险等级 medium 的分界线 |
| `high_threshold` | 0.70 | 风险等级 high 的分界线 |
| `drift.mode` | `"threshold"` | 漂移检测模式：`threshold` / `z_test` / `page_hinkley` |

## 单独使用各层

```python
import numpy as np
from certiflow import ConfidenceFusion, softmax, merge_events, RiskEngine, DriftMonitor

# Layer 1-2: 仅做置信度融合
fusion = ConfidenceFusion(alpha=0.6)
fusion.update(softmax(logits))
result = fusion.query()

# Layer 3: 仅做事件合并
merged = merge_events(raw_events)

# Layer 4: 仅做风险评分
risk = RiskEngine().assess(merged)

# Layer 5: 仅做漂移检测
monitor = DriftMonitor()
drift = monitor.evaluate(batch_1)
drift = monitor.evaluate(batch_2)  # 与 batch_1 对比
```

## 运行 Demo

```bash
python -m certiflow.demo
```

输出示例：

```
Synthetic data: 40 frames × 10 classes

============================================================
  Layer 1-2: Softmax + EMA Fusion
============================================================
  frame  15  →  class=3  conf=0.2766  fused=True
  frame  20  →  class=3  conf=0.7439  fused=True
  ...

============================================================
  Layer 3: Merged Events
============================================================
  type=3  conf=0.7677  [7.50s – 15.50s]  dur=8.00s

============================================================
  Layer 4: Risk Assessment
============================================================
  Score:       0.6152
  Level:       medium
  Uncertainty: 0.5063

============================================================
  Layer 5: Drift Detection
============================================================
  Detected:    False
  Mode:        threshold
```

## 文件结构

```
CertiFlow/
├── pyproject.toml           # 打包配置 (pip install -e .)
├── README.md
├── LICENSE
└── certiflow/               # Python 包
    ├── __init__.py           # 包导出 & 版本号
    ├── confidence_config.py  # 统一配置 dataclass
    ├── confidence_fusion.py  # Layer 1-2: softmax + EMA
    ├── event_merger.py       # Layer 3: 事件合并
    ├── risk_engine.py        # Layer 4: 风险评分
    ├── drift_monitor.py      # Layer 5: 漂移检测
    ├── pipeline.py           # 全流水线编排
    └── demo.py               # 可运行演示
```

## 设计原则

- **零耦合** — 仅依赖 numpy，不绑定任何框架、数据库或网络协议
- **不可变输出** — 每层返回 dataclass 结果对象（`FusionResult` / `RiskResult` / `DriftResult`）
- **关注点分离** — 每个模块单一职责，可独立导入使用
- **双模式 API** — streaming（逐帧 `process_logits`）和 batch（`process_events`）
- **配置集中** — 所有参数通过 `ConfidenceConfig` 统一管理，支持 dict / YAML / 直接构造

## 算法参考

- EMA 理论：Brown, R.G. (1956). *Exponential Smoothing for Predicting Demand*
- 当信号为随机游走时，Kalman 滤波退化为 EMA（最优线性因果估计器）
- Page-Hinkley 变点检测：Page (1954), Hinkley (1971)
- 总变差距离（TVD）：离散分布间 L1 差的一半

## License

MIT
