pgm-toolkit

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

当前发布版本：0.1.1。

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

安装

pip install pgm-toolkit

本地开发建议使用 Python 3.10：

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

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

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

常用模型与推断入口：

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

POMDP 入口：

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

快速示例

Factor 后验更新

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())

输出：

['Disease']
[0.846, 0.154]

Bayesian Network 查询

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())

输出：

[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 对比和例子展示。
• 明确未实现能力和已知边界，避免把历史实验代码描述为当前主线功能。