Presets API

预设用于复用常见问题类型的求解策略。教程式说明见 策略配置。

本页标题只显示对象名或方法名，便于右侧目录扫描。签名、字段类型、参数含义和返回值放在正文中。

接口分组

分组	对象
问题特征	ProblemFeatures、detect_problem_features
预设对象	BuiltInStrategyPreset、StrategyPreset
推荐结果	StrategyRecommendation
工具函数	recommend_preset、list_strategy_presets、get_strategy_preset、load_strategy_preset、describe_preset、describe_recommendation

ProblemFeatures

ProblemFeatures 是对模型结构的摘要，用于驱动自动预设推荐。

字段	类型	含义
problem_type	str	问题类型，例如 scheduling、routing、knapsack、general。
estimated_search_space	str	粗粒度搜索空间大小：small、medium、large、huge。
num_variables	int	变量数量。
num_constraints	int	约束数量。
num_objectives	int	目标数量。
has_scheduling	bool	是否包含调度结构。
has_blackbox	bool	是否包含黑盒调用。
has_linear	bool	目标和约束是否线性友好。
has_sequence	bool	是否包含序列变量。
has_interval	bool	是否包含 interval 变量。
has_sequence_blackbox	bool	是否包含序列变量和黑盒调用的组合。
has_sequence_path_linear	bool	是否是序列路径线性场景。

from optagent.presets import detect_problem_features

# 1. 对已冻结的 program 做结构识别。
features = detect_problem_features(program)

# 2. 读取关键特征，判断系统会把它归入哪类问题。
print(features.problem_type)
print(features.has_linear)
print(features.num_variables)

detect_problem_features

签名：detect_problem_features(program: ExecutableProgram) -> ProblemFeatures

参数	类型	含义
program	ExecutableProgram	ModelBuilder.freeze() 生成的可执行模型。

返回值：ProblemFeatures，模型结构摘要。

# 1. 冻结模型后再做特征识别。
program = builder.freeze()

# 2. detect_problem_features 不求解模型，只分析模型结构。
features = detect_problem_features(program)

# 3. 根据特征决定是否需要手动覆盖预设。
if features.problem_type == "knapsack" and features.has_linear:
    print("可以优先考虑 linear_* 预设")

BuiltInStrategyPreset

BuiltInStrategyPreset 是稳定的内置预设枚举，适合在业务代码中引用。

典型前缀	场景
SCHEDULING_*	调度问题。
SEQUENCE_*	排列、路径、顺序问题。
ROUTING_*	路由或序列黑盒问题。
LINEAR_*	线性、整数规划问题。
GENERAL_*	通用启发式问题。
HYBRID_*	混合求解路径。

from optagent import BuiltInStrategyPreset, Orchestrator

# 1. 用枚举值显式选择线性精确优先策略。
result = Orchestrator().run(
    program,
    preset=BuiltInStrategyPreset.LINEAR_EXACT_FIRST,
)

# 2. 返回结果中会记录实际选中的预设名和来源。
print(result.selected_preset_name)
print(result.selected_preset_source)

StrategyPreset

StrategyPreset 是已编译好的策略预设对象。

字段	类型	含义
name	str	预设名称。
description	str	预设说明。
orchestrator_config	OrchestratorConfig	顶层编排配置。
execution_plan	ExecutionPlan	编译后的执行计划。
family	str	预设族，例如 heuristic、exact、hybrid。
objective	str	策略目标倾向，例如 speed、balanced、quality。
tags	tuple[str, ...]	标签。
requirements	tuple[str, ...]	适用前提。

from optagent.presets import get_strategy_preset

# 1. 按名称取出一个与当前 program 匹配的预设对象。
preset = get_strategy_preset(program, "linear_exact_first")

# 2. 查看预设的目标倾向和阶段配置。
print(preset.family)
print(preset.objective)
print(len(preset.orchestrator_config.phases))

StrategyRecommendation

StrategyRecommendation 是自动推荐流程的解释对象，内部推荐路径会使用它。

字段	类型	含义
preset	StrategyPreset	推荐出的预设对象。
features	ProblemFeatures	用于推荐的问题特征。
recommendation_source	str	推荐来源，例如 rules 或 benchmark。
recommendation_reason	str	推荐原因。
matched_benchmark_cases	tuple[str, ...]	命中的 benchmark case。
benchmark_wins	dict[str, int]	benchmark 胜出统计。

from optagent.presets import describe_recommendation

# 1. recommendation 通常由自动推荐流程生成。
# 2. describe_recommendation 可把它转成适合日志记录的 dict。
payload = describe_recommendation(recommendation)
print(payload["recommendation_source"])
print(payload["preset"]["name"])

recommend_preset

签名：recommend_preset(program: ExecutableProgram) -> StrategyPreset

参数	类型	含义
program	ExecutableProgram	已冻结的可执行模型。

返回值：StrategyPreset，系统基于规则为当前模型推荐的预设。

from optagent.presets import recommend_preset

# 1. 让系统根据模型结构推荐一个预设。
preset = recommend_preset(program)

# 2. 可以先打印确认，再决定是否传给 Orchestrator。
print(preset.name)
result = Orchestrator().run(program, preset=preset)

list_strategy_presets

签名：list_strategy_presets(program: ExecutableProgram) -> tuple[StrategyPreset, ...]

参数	类型	含义
program	ExecutableProgram	已冻结的可执行模型。

返回值：tuple[StrategyPreset, ...]，所有匹配当前模型特征的内置预设。

from optagent.presets import list_strategy_presets

# 1. 列出当前模型可用的预设，而不是所有内置预设。
presets = list_strategy_presets(program)

# 2. 展示名称、族和目标倾向，方便人工选择。
for preset in presets:
    print(preset.name, preset.family, preset.objective)

get_strategy_preset

签名：get_strategy_preset(program: ExecutableProgram, preset_name: str | BuiltInStrategyPreset) -> StrategyPreset

参数	类型	含义
program	ExecutableProgram	已冻结的可执行模型。
preset_name	str | BuiltInStrategyPreset	预设名称或内置预设枚举。

返回值：StrategyPreset，名称匹配且适用于当前模型的预设。

from optagent import BuiltInStrategyPreset
from optagent.presets import get_strategy_preset

# 1. 枚举写法适合长期维护的业务代码。
preset = get_strategy_preset(program, BuiltInStrategyPreset.LINEAR_EXACT_FIRST)

# 2. 字符串写法适合配置文件或命令行参数。
same_preset = get_strategy_preset(program, "linear_exact_first")

load_strategy_preset

签名：load_strategy_preset(path: str | Path, *, program: ExecutableProgram | None = None, validate_match: bool = True) -> StrategyPreset

参数	类型	含义
path	str | Path	外部 preset manifest 文件路径。
program	ExecutableProgram | None	可选模型；传入后可校验预设是否匹配模型特征。
validate_match	bool	是否启用匹配校验。

返回值：StrategyPreset，从 manifest 编译出的预设对象。

from optagent.presets import load_strategy_preset

# 1. 从外部 manifest 加载自定义预设。
# 2. 传入 program 时会校验该预设是否适配当前模型。
preset = load_strategy_preset(
    "custom_preset.json",
    program=program,
    validate_match=True,
)

# 3. 加载成功后可直接传给 Orchestrator。
result = Orchestrator().run(program, preset=preset)

describe_preset

签名：describe_preset(preset: StrategyPreset) -> dict[str, Any]

参数	类型	含义
preset	StrategyPreset	要描述的预设对象。

返回值：dict[str, Any]，包含名称、描述、族、目标、标签、要求、执行概要和编排配置的字典。

from optagent.presets import describe_preset, get_strategy_preset

# 1. 取出预设对象。
preset = get_strategy_preset(program, "linear_exact_first")

# 2. 转成 dict，适合打印、日志或 JSON 序列化。
payload = describe_preset(preset)
print(payload["family"])
print(payload["strategy_outline"])

describe_recommendation

签名：describe_recommendation(recommendation: StrategyRecommendation) -> dict[str, Any]

参数	类型	含义
recommendation	StrategyRecommendation	要描述的推荐结果。

返回值：dict[str, Any]，包含推荐预设、问题特征、推荐来源、推荐原因和 benchmark 反馈的字典。

# 1. 将推荐解释对象转成结构化 payload。
payload = describe_recommendation(recommendation)

# 2. 记录推荐原因，方便排查自动策略选择。
print(payload["recommendation_reason"])
print(payload["problem_features"])