Metadata-Version: 2.4
Name: pgm-toolkit
Version: 0.1.1
Summary: Probabilistic Graph Model
License-Expression: MIT
Author: Zhi-Hua Zhu
Author-email: 767746811@qq.com
Requires-Python: ==3.10.*
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: ipytest (>=0.14.2,<0.15.0)
Requires-Dist: matplotlib (>=3.4.0,<4.0.0)
Requires-Dist: networkx (==2.6.0)
Requires-Dist: numpy (>=1.21.0,<2.0.0)
Requires-Dist: scipy (>=1.7.0,<2.0.0)
Requires-Dist: twine (>=6.2.0,<7.0.0)
Description-Content-Type: text/markdown

# pgm-toolkit

`pgm-toolkit` 是一个面向教学、实验和原型开发的概率图模型工具库。当前版本聚焦小规模离散概率图模型：因子代数、Bayesian Network、Markov Network、精确推断、采样、结构学习、图-分布唯一性分析，以及离散 Tabular POMDP。

当前发布版本：`0.1.1`。

项目仍处于 `0.x` Alpha 阶段。API 会优先服务于概率语义正确、实现可读和研究代码可维护性，不承诺长期冻结。

## 安装

```bash
pip install pgm-toolkit
```

本地开发建议使用 Python `3.10`：

```bash
poetry install
poetry run pytest
```

## 核心能力

- `pgm_toolkit.core`：`Node`、`Edge`、`Graph`、`Factor`、`Categorical`
- `pgm_toolkit.models`：`BayesianNetwork`、`MarkovNetwork`
- `pgm_toolkit.inference.exact_inference`：`VariableElimination`、`BeliefPropagation`、`JunctionTree`
- `pgm_toolkit.sampling`：`ExactSampler`、`GibbsSampler`
- `pgm_toolkit.learning.structure_learning`：BDeu/G2 条件独立检验、PC 结构学习
- `pgm_toolkit.analysis`：Bayesian / Markov 图结构与分布唯一性检查
- `pgm_toolkit.dynamical_models.pomdp`：离散 Tabular POMDP 环境、内部模型、belief、滤波、策略和 agent

顶层包只重新导出最常用的基础对象：

```python
from pgm_toolkit import Categorical, Edge, Factor, Graph, Node
```

常用模型与推断入口：

```python
from pgm_toolkit.inference.exact_inference import VariableElimination
from pgm_toolkit.models import BayesianNetwork, MarkovNetwork
from pgm_toolkit.sampling import ExactSampler, GibbsSampler
```

POMDP 入口：

```python
from pgm_toolkit.dynamical_models.pomdp import (
    BayesianFilter,
    Belief,
    HMMEnvironment,
    InternalModel,
    PBVIPolicy,
    POMCPPolicy,
    POMDPAgent,
    QMDPPolicy,
    RandomPolicy,
    uniform_belief,
)
```

## 快速示例

### Factor 后验更新

```python
import numpy as np

from pgm_toolkit import Factor

domains = {"Disease": [0, 1], "Test": [0, 1]}

prior = Factor(["Disease"], np.array([0.99, 0.01]), domains)
likelihood = Factor(
    ["Test", "Disease"],
    np.array([[0.95, 0.10], [0.05, 0.90]]),
    domains,
)

joint = Factor.multiply([prior, likelihood])
posterior = joint.reduce({"Test": 1}).normalize()

print(posterior.scope)
print(posterior.table.round(3).tolist())
```

输出：

```text
['Disease']
[0.846, 0.154]
```

### Bayesian Network 查询

```python
import numpy as np

from pgm_toolkit.inference.exact_inference import VariableElimination
from pgm_toolkit.models import BayesianNetwork

bn = BayesianNetwork("wet_grass")
for var in ["Rain", "Sprinkler", "WetGrass"]:
    bn.add_node(var, domain=[0, 1])

bn.add_edge("Rain", "WetGrass")
bn.add_edge("Sprinkler", "WetGrass")

bn.add_cpd("Rain", np.array([0.8, 0.2]))
bn.add_cpd("Sprinkler", np.array([0.7, 0.3]))

p_wet = np.array([[0.02, 0.75], [0.80, 0.95]])
bn.add_cpd(
    "WetGrass",
    np.stack([1 - p_wet, p_wet], axis=0),
    parents=["Rain", "Sprinkler"],
)

posterior = VariableElimination().query(
    bn,
    ["Rain"],
    evidence={"WetGrass": 1},
)
print(posterior.table.round(3).tolist())
```

输出：

```text
[0.531, 0.469]
```

## POMDP 模块

POMDP 子包是离散 Tabular 实现，明确区分六层职责：

- `HMMEnvironment`：真实状态推进、观测生成、外部奖励
- `InternalModel`：智能体用于推断和规划的表格模型
- `Belief`：隐状态后验分布
- `BayesianFilter`：基于动作和观测更新 belief
- `Policy`：根据 belief 选择动作，当前包括 `RandomPolicy`、`QMDPPolicy`、`PBVIPolicy`、`POMCPPolicy`
- `POMDPAgent`：编排 belief、filter、policy 和交互历史

当前 POMDP 的张量约定：

- `T[s, a, s_next] = P(s_next | s, a)`
- `O[s_next, a, o] = P(o | s_next, a)`
- `R` 输入可为 `(S, A)` 或 `(S, A, S')`

## 当前边界

- `Factor.scope` 的顺序就是 `Factor.table` 的轴顺序。
- `VariableElimination` 是当前最通用的精确查询入口。
- `BeliefPropagation` 只支持单变量查询；有环图上是 loopy BP 近似。
- `JunctionTree` 要求查询变量包含在同一个 clique 中。
- `ExactSampler` 会构造全联合分布，只适合小型离散模型。
- `PCStructure.learn_bn_structure()` 只学习结构，不学习 CPD。
- 参数学习模块仍是占位。
- POMDP 当前是离散 Tabular 实现，不是连续 POMDP 框架。

## 文档

- `docs/API_REFERENCE.md`：当前实现的完整 API 参考。
- `docs/pgm_toolkit_usage_guide.html`：讲解用 HTML 文档，包含模块层级、POMDP 图示和多个可运行例子。
- `docs/gibbs_sampler.md`：Gibbs 采样说明。
- `docs/pc_algorithm.md`：PC 结构学习说明。
- `src/pgm_toolkit/dynamical_models/docs/POMDP.md`：POMDP 理论与实现映射。

## 0.1.1 更新要点

- 更新公开 API 文档，使其以当前实现为准。
- 补充讲解用 HTML 文档，覆盖核心模块、POMDP 层级、policy 对比和例子展示。
- 明确未实现能力和已知边界，避免把历史实验代码描述为当前主线功能。

