certiflow 0.1.0

Confidence fusion, risk scoring & drift detection pipeline — from raw logits to actionable risk levels in five layers.

CertiFlow

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

安装

# 从 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]"

快速开始

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 统一管理，支持三种初始化方式：

# 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

单独使用各层

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

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