Particles API 文档

概述

Particles 是 HeurAMS 的核心组件系统，采用物理粒子模型来组织和管理学习数据。该系统包含四种主要粒子类型，通过统一的 Atom 容器进行协调管理。

架构概览

Atom (统一容器)
├── Electron (算法数据)
├── Nucleon (内容数据)
└── Orbital (策略数据)

Atom 类

类定义

class Atom()

构造函数

def __init__(self, ident = "")

参数:

• ident (str): 原子的唯一标识符，默认为空字符串

核心方法

link(key, value)

链接组件到原子

参数:

• key (str): 组件键名，支持 nucleon, electron, orbital 及其对应的路径和格式
• value: 组件对象或路径

异常:

• ValueError: 当键名不受支持时抛出

persist(key)

持久化组件数据到文件

参数:

• key (str): 组件键名，支持 nucleon, electron, orbital

异常:

• KeyError: 当持久化格式不受支持时抛出
• TypeError: 当路径未初始化时抛出

__getitem__(key)

字典式访问组件

参数:

• key (str): 组件键名

返回: 组件对象

异常:

• KeyError: 当键名不受支持时抛出

__setitem__(key, value)

字典式设置组件

参数:

• key (str): 组件键名
• value: 组件对象

异常:

• KeyError: 当键名不受支持时抛出

静态方法

placeholder()

生成占位符原子

返回: 包含占位符电子、核子和空字典的元组

Electron 类

类定义

class Electron:

构造函数

def __init__(self, ident: str, algodata: dict = {}, algo: str = "supermemo2")

参数:

• ident (str): 算法的唯一标识符
• algodata (dict): 算法数据字典，包含算法参数和设置
• algo (str): 使用的算法模块标识，默认为 "supermemo2"

核心方法

activate()

激活此电子，标记为活动状态并更新最后修改时间戳

modify(var, value)

修改算法数据中的指定变量

参数:

• var (str): 变量名
• value: 新值

revisor(quality, is_new_activation)

算法迭代决策机制实现

参数:

• quality (int): 记忆保留率量化参数 (0-5)
• is_new_activation (bool): 是否为初次激活

__str__()

返回电子的详细字符串表示

__getitem__(key)

字典式访问算法数据

参数:

• key (str): 数据键名

返回: 对应的数据值

异常:

• KeyError: 当键名不存在时抛出

__setitem__(key, value)

字典式设置算法数据

参数:

• key (str): 数据键名
• value: 新值

异常:

• AttributeError: 当尝试修改 ident 时抛出

静态方法

placeholder()

生成电子占位符

返回: 包含示例内容的电子对象

Nucleon 类

类定义

class Nucleon:

构造函数

def __init__(self, ident, payload)

参数:

• ident: 核子的唯一标识符
• payload: 内容数据载荷

核心方法

__getitem__(key)

字典式访问载荷数据

参数:

• key (str): 载荷键名

返回: 对应的载荷值

__iter__()

迭代载荷键名

__len__()

获取载荷大小

静态方法

placeholder()

生成核子占位符

返回: 包含示例内容的核子对象

Orbital 类型

类型定义

class Orbital(TypedDict):

字段说明

字段	类型	说明
quick_view	list	快速复习策略列表
recognition	list	识别训练策略列表
final_review	list	最终复习策略列表
puzzle_config	dict	谜题生成配置

使用示例

创建完整的原子

# 创建原子
atom = Atom("learning_unit_001")

# 链接核子 (内容数据)
from heurams.kernel.particles.nucleon import Nucleon
nucleon = Nucleon("content_001", {
    "content": "学习内容",
    "translation": "translation content"
})
atom.link("nucleon", nucleon)
atom.link("nucleon_path", pathlib.Path("content.toml"))

# 链接电子 (算法数据)
from heurams.kernel.particles.electron import Electron
electron = Electron("algo_001", {}, "supermemo2")
atom.link("electron", electron)
atom.link("electron_path", pathlib.Path("algorithm.json"))

# 链接轨道 (策略数据)
from heurams.kernel.particles.orbital import Orbital
orbital: Orbital = {
    "quick_view": [["cloze", 1], ["mcq", 0.5]],
    "recognition": [["recognition", 1]],
    "final_review": [["cloze", 0.7], ["mcq", 0.7]],
    "puzzle_config": {
        "cloze": {"from": "content"},
        "mcq": {"from": "keyword_note"}
    }
}
atom.link("orbital", orbital)
atom.link("orbital_path", pathlib.Path("strategy.toml"))

# 持久化数据
atom.persist("nucleon")
atom.persist("electron")
atom.persist("orbital")

访问原子组件

# 字典式访问
nucleon = atom["nucleon"]
electron = atom["electron"]

# 修改电子数据
electron["efactor"] = 2.5

# 激活电子
electron.activate()

# 算法迭代
electron.revisor(quality=4, is_new_activation=False)

文件格式支持

组件	支持格式	默认格式
Nucleon	TOML	TOML
Electron	JSON	JSON
Orbital	TOML	TOML

版本兼容性

• HeurAMS 0.4.x: 完全支持
• HeurAMS 0.3.x: 部分支持 (需要适配)
• HeurAMS 0.2.x: 不支持