规则器

hscredit.core.models 提供规则集合、规则分类器与组合工具。

class hscredit.core.models.RuleSet(name='RuleSet', logic=LogicOperator.AND, rules=None, weight=1.0, description='', n_jobs=-1, parallel_backend=None, parallel_config=None)

基类：ParallelizableMixin

规则集类.

支持规则的层次化组合，可以包含单规则或嵌套规则集。 支持且/或逻辑操作。

参数:

• name (str) -- 规则集名称，默认为"RuleSet"

• logic (str | LogicOperator) -- 逻辑操作符，'and' 表示所有规则都命中才算命中，'or' 表示任一规则命中就算命中

• rules (List[Rule | RuleSet] | None) -- 规则列表，可以是 Rule 或 RuleSet 对象

• weight (float) -- 规则集权重，用于最终得分计算，默认为1.0

• description (str) -- 规则集描述

• n_jobs (int | float | None) -- 并行任务数，默认为-1

• parallel_backend (str | None) -- joblib并行后端，默认为None

• parallel_config (Mapping[str, Any] | None) -- joblib扩展配置，默认为None

参考样例

>>> from hscredit.core.rules import Rule
>>> from hscredit.core.models.rule_classifier import RuleSet
>>> rule1 = Rule("age < 18", name="未成年")
>>> rule2 = Rule("income > 100000", name="高收入")
>>> rule_set = RuleSet(
...     name="高风险用户",
...     logic="and",
...     rules=[rule1, rule2],
...     description="年龄小且收入高"
... )
>>> inner_set = RuleSet(name="子规则集", logic="or", rules=[rule1])
>>> outer_set = RuleSet(name="外层规则集", logic="and",
...                     rules=[inner_set, rule2])

add_rule(rule)

添加规则到规则集.

参数:

rule (Rule | RuleSet) -- Rule 或 RuleSet 对象

返回:

self，支持链式调用

返回类型:

RuleSet

remove_rule(index)

移除指定索引的规则.

参数:

index (int) -- 规则索引

返回:

self，支持链式调用

返回类型:

RuleSet

evaluate(X, return_details=True)

评估规则集.

参数:

• X (DataFrame) -- 输入数据

• return_details (bool) -- 是否返回详细结果

返回:

(整体命中结果, 各规则详细结果列表)

返回类型:

Tuple[ndarray, List[RuleResult]]

get_all_rules(flatten=False)

获取所有规则.

参数:

flatten (bool) -- 是否扁平化返回（展开嵌套规则集）

返回:

规则列表

返回类型:

List[Rule | RuleSet]

class hscredit.core.models.RulesClassifier(rules=None, logic=LogicOperator.OR, output_mode='final', weights=None, threshold=0.5, target='target', verbose=False, n_jobs=-1, parallel_backend=None, parallel_config=None)

基类：ArtifactSerializableMixin, ParallelizableMixin, BaseEstimator, ClassifierMixin

参数:

• rules (Rule | RuleSet | List[Rule | RuleSet] | None)

• logic (str | LogicOperator)

• output_mode (str)

• weights (List[float] | None)

• threshold (float)

• target (str)

• verbose (bool)

• n_jobs (int | float | None)

• parallel_backend (str | None)

• parallel_config (Mapping[str, Any] | None)

artifact_kind = '风险模型'

规则分类器 - 统一入口.

支持传入单规则或规则集（支持嵌套）进行分类预测。 最外层支持选择且/或逻辑组合，内层规则逻辑由各自的RuleSet定义。 支持输出单规则命中结果或规则集最终结果，支持输出规则命中原因。

代码风格参考 binning 模块。

参数:

• rules -- 规则或规则集列表/单个对象，可以是 Rule、RuleSet 或混合

• logic -- 最外层逻辑操作符，'and' 或 'or'，默认为 'or'

• output_mode -- 输出模式 - 'final': 只输出最终分类结果 - 'individual': 输出每条规则的命中结果 - 'both': 同时输出最终结果和单规则结果 - 'reason': 输出带命中原因的结果

• weights -- 各规则/规则集的权重列表，用于加权投票，默认为None（等权重）

• threshold -- 分类阈值，用于概率输出，默认为0.5

• target -- 目标变量列名，用于scorecardpipeline风格，默认为'target'

• verbose -- 是否输出详细信息，默认为False

• n_jobs -- 并行任务数，默认为-1

• parallel_backend -- joblib并行后端，默认为None

• parallel_config -- joblib扩展配置，默认为None

属性: - classes_: 类别标签 - n_features_in_: 输入特征数 - feature_names_in_: 特征名称

参考样例

>>> rules = [
...     Rule("age < 18", name="未成年", description="用户未成年"),
...     Rule("income > 100000", name="高收入", description="月收入超过10万"),
...     Rule("credit_score < 500", name="低信用分", description="信用分低于500")
... ]
>>> clf = RulesClassifier(rules=rules, logic='or', output_mode='both')
>>> clf.fit(X_train)
>>> final, individual = clf.predict(X_test)
>>> high_risk = RuleSet(
...     name="高风险",
...     logic="and",
...     rules=[
...         Rule("age < 25", name="年轻"),
...         Rule("debt_ratio > 0.6", name="高负债")
...     ],
...     description="年轻且高负债"
... )
>>> medium_risk = RuleSet(
...     name="中风险",
...     logic="or",
...     rules=[
...         Rule("credit_score < 550"),
...         Rule("employment_years < 1")
...     ]
... )
>>> clf = RulesClassifier(
...     rules=[high_risk, medium_risk],
...     logic='or',
...     output_mode='reason'
... )
>>> clf.fit(X_train)
>>> result, reasons = clf.predict(X_test, return_reason=True)
    >>> # 方式3：混合使用单规则和规则集
    >>> nested_rules = RuleSet(
    ...     name="嵌套规则",
    ...     logic="and",
    ...     rules=[
    ...         Rule("age > 60", name="高龄"),
    ...         RuleSet(  # 内层规则集
    ...             name="健康风险",
    ...             logic="or",
    ...             rules=[
    ...                 Rule("income < 3000"),
    ...                 Rule("debt_ratio > 0.5")
    ...             ]
    ...         )
    ...     ]
    ... )
    >>> clf = RulesClassifier(rules=[nested_rules, Rule("fraud_flag == 1")])

fit(X, y=None, **kwargs)

拟合分类器（学习特征名）.

支持三种模式: 1. sklearn风格: fit(X, y) - X是特征矩阵，y是目标变量 2. scorecardpipeline风格: fit(df) - df包含特征列和目标列（由target参数指定） 3. 仅验证: fit(X) - 仅验证特征，不学习y

参数:

• X (DataFrame | ndarray) -- 训练数据 - sklearn风格: 特征矩阵，shape (n_samples, n_features) - scorecardpipeline风格: 完整数据框，包含特征列和目标列

• y (ndarray | Series | None) -- 目标变量（可选） - sklearn风格: 传入目标变量 - scorecardpipeline风格: 不传，从X中提取target列

• kwargs -- 其他参数

返回:

拟合后的分类器

返回类型:

RulesClassifier

get_feature_importances(importance_type='frequency')

获取特征重要性（基于规则使用频率）.

规则分类器通过统计特征在规则中的使用频率来计算重要性。

参数:

importance_type (str) -- 重要性类型，默认'frequency' - 'frequency': 特征在规则中出现的次数 - 'weighted': 考虑规则权重的加权频率

返回:

特征重要性Series

返回类型:

Series

predict(X, return_reason=False)

预测.

无需fit即可直接预测。

参数:

• X (DataFrame | ndarray) -- 输入数据

• return_reason (bool) -- 是否返回命中原因，当output_mode='reason'时自动为True

返回:

根据output_mode返回不同格式的结果 - 'final': np.ndarray，最终分类结果 - 'individual': pd.DataFrame，每条规则的命中结果 - 'both': tuple，(最终结果, 单规则结果) - 'reason': tuple，(最终结果, 命中原因列表)

返回类型:

ndarray | DataFrame | Tuple

predict_proba(X)

预测概率.

无需fit即可直接预测概率。

参数:

X (DataFrame | ndarray) -- 输入数据

返回:

概率数组，shape (n_samples, 2)

返回类型:

ndarray

get_rule_summary()

获取规则摘要.

返回:

规则摘要DataFrame

返回类型:

DataFrame

add_rule(rule)

添加规则（拟合前使用）.

参数:

rule (Rule | RuleSet) -- Rule 或 RuleSet 对象

返回:

self，支持链式调用

返回类型:

RulesClassifier

class hscredit.core.models.RuleResult(rule_id, rule_name, expression, matched, matched_indices, matched_count, details=<factory>)

基类：object

规则评估结果.

参数:

• rule_id (str) -- 规则标识

• rule_name (str) -- 规则名称

• expression (str) -- 规则表达式

• matched (bool) -- 是否命中

• matched_indices (ndarray) -- 命中的样本索引

• matched_count (int) -- 命中样本数

• details (Dict[str, Any]) -- 额外详情

rule_id: str

rule_name: str

expression: str

matched: bool

matched_indices: ndarray

matched_count: int

details: Dict[str, Any]

to_dict()

转换为字典格式.

返回类型:

Dict[str, Any]

class hscredit.core.models.LogicOperator(value)

基类：str, Enum

规则组合逻辑操作符枚举（继承 str，可直接与字符串比较）。

成员：

• AND = "and"：与逻辑，所有子规则同时命中才算命中（取交集）

• OR = "or"：或逻辑，任一子规则命中即算命中（取并集）

AND = 'and'

OR = 'or'

hscredit.core.models.create_and_ruleset(rules, name='AND_RuleSet', description='')

创建且逻辑规则集.

参数:

• rules (List[Rule | RuleSet]) -- 规则列表

• name (str) -- 规则集名称

• description (str) -- 规则集描述

返回:

RuleSet对象

返回类型:

RuleSet

hscredit.core.models.create_or_ruleset(rules, name='OR_RuleSet', description='')

创建或逻辑规则集.

参数:

• rules (List[Rule | RuleSet]) -- 规则列表

• name (str) -- 规则集名称

• description (str) -- 规则集描述

返回:

RuleSet对象

返回类型:

RuleSet

hscredit.core.models.combine_rules(*rules, logic='or', name='Combined', description='')

组合多个规则为规则集.

参数:

• rules (Rule | RuleSet) -- 多个规则或规则集

• logic (str) -- 逻辑操作符，'and' 或 'or'

• name (str) -- 规则集名称

• description (str) -- 规则集描述

返回:

RuleSet对象

返回类型:

RuleSet

参考样例

>>> from hscredit.core.rules import Rule
>>> rule1 = Rule("age < 18", name="未成年")
>>> rule2 = Rule("income > 100000", name="高收入")
>>> combined = combine_rules(rule1, rule2, logic='and', name="高风险")