# hmmkit

**Repository Path**: southwind957/hmmkit

## Basic Information

- **Project Name**: hmmkit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-18
- **Last Updated**: 2026-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hmmkit

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个轻量级、sklearn 风格的隐马尔可夫模型（HMM）库，专为序列建模和推荐系统设计。

**hmmkit** 让开发者无需深入理解 HMM 原理即可快速完成：

- 序列模式训练
- 用户隐藏状态推断
- 下一步行为预测
- 基于状态的个性化推荐

适合作为通用的序列分析或推荐算法模块，轻松集成到任意 Python 项目中。

---

## 核心特性

- **Sklearn 风格 API** - `fit()`, `predict()`, `save()`, `load()` 一目了然
- **全自动训练** - 基于 Baum-Welch (EM) 算法，支持收敛检测
- **多种预测方式** - Viterbi 解码、后验概率、行为预测
- **灵活的推荐策略** - 支持状态推荐、加权推荐、排除已交互项
- **类型友好** - 支持整数、字符串等任意可哈希类型作为行为标识
- **零重型依赖** - 仅依赖 NumPy，轻量易部署

---

## 安装

### 本地安装（开发模式）

```bash
git clone https://github.com/your-username/hmmkit.git
cd hmmkit
pip install -e .
```

### Git 依赖

在 `pyproject.toml` 中添加：

```toml
[project]
dependencies = [
    "hmmkit @ git+https://github.com/your-username/hmmkit.git",
]
```

---

## 快速开始

### 基础用法

```python
from hmmkit import HMMRecommender

# 准备用户行为序列数据
sequences = [
    [1, 2, 3, 4, 3],
    [2, 3, 5, 5, 4],
    [1, 1, 2, 3],
    [3, 4, 5, 1, 2],
]

# 训练模型
model = HMMRecommender(n_states=4, random_state=42)
model.fit(sequences, n_iter=100)

# 预测用户当前隐藏状态分布
state_dist = model.predict_state([1, 2, 3])
# array([0.0, 1.0, 0.0, 0.0])

# 预测下一个最可能的行为
recommendations = model.predict_next([1, 2, 3], top_k=3)
# [(4, 0.85), (5, 0.10), (2, 0.03)]

# 解码最可能的隐藏状态路径
path, prob = model.predict_path([1, 2, 3])
# ([0, 2, 1], 0.48)

# 保存与加载模型
model.save("hmm_model.json")
loaded = HMMRecommender.load("hmm_model.json")
```

### 字符串类型支持

```python
# 支持字符串作为行为标识
sequences = [
    ["首页", "搜索", "商品详情", "加购"],
    ["首页", "分类", "商品详情", "下单"],
    ["搜索", "商品详情", "商品详情", "加购"],
]

model = HMMRecommender(n_states=3)
model.fit(sequences)

recs = model.predict_next(["首页", "搜索"], top_k=3)
# [('商品详情', 0.72), ('分类', 0.18), ('首页', 0.05)]
```

---

## API 文档

### HMMRecommender

主要接口类，提供 sklearn 风格的 HMM 训练和预测功能。

#### 初始化参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `n_states` | int | 4 | 隐藏状态数量 |
| `n_observations` | int \| None | None | 观测值数量，None 时自动推断 |
| `random_state` | int \| None | None | 随机种子，保证结果可复现 |

#### 核心方法

| 方法 | 说明 |
|------|------|
| `fit(sequences, n_iter=100, tol=1e-4, verbose=False)` | 训练模型 |
| `predict_state(obs_seq)` | 返回序列末尾的隐藏状态分布 |
| `predict_proba(obs_seq)` | 返回每个时间步的隐藏状态后验概率 |
| `predict_path(obs_seq)` | Viterbi 解码，返回最可能的状态路径 |
| `predict_next(obs_seq, top_k=5)` | 预测下一个行为，返回 top-k 推荐列表 |
| `predict_next_prob(obs_seq)` | 返回下一个观测的概率分布 |
| `predict_by_state(state_idx, top_k=5)` | 基于指定状态推荐 |
| `predict_weighted(obs_seq, top_k=5, exclude=None)` | 加权推荐，可排除已交互项 |
| `score(sequences)` | 计算序列集合的对数似然 |
| `save(path)` | 保存模型到 JSON 文件 |
| `load(path)` | 类方法，从文件加载模型 |

#### 属性

| 属性 | 说明 |
|------|------|
| `transition_matrix` | 状态转移矩阵 A，形状 (n_states, n_states) |
| `emission_matrix` | 发射矩阵 B，形状 (n_states, n_observations) |
| `initial_probs` | 初始状态概率 π，形状 (n_states,) |
| `engine` | 推荐引擎实例，用于高级定制 |

---

## 项目结构

```
hmmkit/
├── src/hmmkit/
│   ├── __init__.py           # 入口，导出 HMMRecommender
│   ├── api/
│   │   └── model_api.py      # sklearn 风格统一接口
│   ├── core/
│   │   └── hmm_model.py      # HMM 核心算法实现
│   ├── recommender/
│   │   └── engine.py         # 推荐策略引擎
│   └── utils/
│       └── preprocessing.py  # 数据预处理工具
├── tests/                    # 单元测试
├── examples/                 # 使用示例
│   └── example_recommender.py
├── pyproject.toml            # 项目配置
└── README.md
```

---

## 算法原理

### 隐马尔可夫模型 (HMM)

HMM 是一种统计模型，用于描述隐藏状态序列与观测序列之间的概率关系。模型包含三类参数：

- **π (pi)** - 初始状态概率分布
- **A** - 状态转移矩阵，A[i,j] 表示从状态 i 转移到状态 j 的概率
- **B** - 发射矩阵，B[i,k] 表示在状态 i 下观测到行为 k 的概率

### 核心算法

| 算法 | 用途 |
|------|------|
| **Baum-Welch (EM)** | 无监督训练，迭代优化参数使观测序列似然最大化 |
| **Forward-Backward** | 计算隐藏状态的后验概率分布 |
| **Viterbi** | 解码最可能的隐藏状态路径 |

### 推荐逻辑

模型训练后，可以通过以下方式生成推荐：

1. **行为预测** - 根据当前状态分布，预测下一个最可能的观测
2. **状态推荐** - 针对特定隐藏状态，推荐该状态下概率最高的行为
3. **加权推荐** - 综合所有状态，按后验概率加权计算推荐分数

---

## 应用场景

| 场景 | 示例 |
|------|------|
| **电商推荐** | 根据用户浏览/加购/下单序列，预测下一个感兴趣的商品 |
| **内容推荐** | 分析用户阅读/观看轨迹，推荐下一篇文章或视频 |
| **用户画像** | 通过隐藏状态识别用户所处阶段（浏览、比价、购买意向） |
| **行为分析** | 发现用户行为模式，识别异常行为 |
| **序列预测** | 任意离散序列的下一步预测任务 |

---

## 运行测试

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

# 运行测试
pytest tests/ -v

# 查看覆盖率
pytest tests/ --cov=src/hmmkit --cov-report=term-missing
```

---

## 项目状态

- [x] 项目结构搭建
- [x] HMM 核心算法（Forward-Backward、Baum-Welch、Viterbi）
- [x] sklearn 风格 API
- [x] 推荐引擎实现
- [x] 模型序列化
- [x] 单元测试（覆盖率 82%）
- [ ] PyPI 发布
- [ ] 详细文档与示例

---

## License

[MIT License](LICENSE)

---

## 贡献

欢迎提交 Issue 和 Pull Request！

开发环境设置：

```bash
git clone https://github.com/your-username/hmmkit.git
cd hmmkit
pip install -e ".[dev]"
pre-commit install  # 可选，安装代码风格检查钩子
```