e2m2e.api.catalog#

轨道库接口类：catalog 数据管理与批量生成（ADR 0043 决策 2）。

Catalog 是接口层的轨道库类：catalog 数据管理（query/get/delete/tag/ export/sweep/terminology）与族生成（orbit_family_generation—— catalog_sweep 是它的批量编排，两者共用同一个 Rust 族生成内核）。 MCP/CLI/sidecar 经单一工具清单到达这些方法；进程内调用方从 Facade().catalog 取实例或直接构造（ADR 0043，ADR 0014 决策 2 的类分家）。

Classes#

Catalog

轨道库接口类（ADR 0043 决策 2）：数据管理 + 批量生成。

Module Contents#

class e2m2e.api.catalog.Catalog(config: e2m2e.api.config.Config | None = None)#

轨道库接口类（ADR 0043 决策 2）：数据管理 + 批量生成。

Catalog(config=Config(...)) 构造注入配置；进程内调用方通常经 Facade().catalog 取同一实例。auto_ingest 与 load_record_ephemeris 是同包任务方法（Facade 的 design/control/ transfer 自动入库与 input_record_id 输入解析）的接缝，非 MCP 工具。

_config#

_catalog_store: e2m2e.data.catalog.CatalogStore | None = None#

property config: e2m2e.api.config.Config#: 运行配置（只读视图）。

_open_catalog() → e2m2e.data.catalog.CatalogStore#

懒打开库目录（首次使用时才产生目录副作用）。

未显式指定目录（Config(catalog_dir=...) 或 $E2M2E_CATALOG_DIR）时报 CATALOG_NOT_CONFIGURED，不建目录、不猜路径（ADR 0047）。

auto_ingest(builder: collections.abc.Callable[[], tuple[dict, dict[str, Any]] | None]) → str | None#

单条产物自动入库（ADR 0031 决策 8；Facade 任务方法经此接缝入库）。

无产物（站保星历缺失）返回 None；入库失败抛 CATALOG_WRITE_FAILED，不静默降级、不冒名为计算失败（ADR 0020）。

auto_ingest_family(builder: collections.abc.Callable[[], tuple[str, list[tuple[dict, dict[str, Any]]]] | None]) → str | None#

族产物逐成员自动入库（ADR 0045：一轨一记录），返回 family_id。

无产物（零成员）返回 None。逐条写入、无跨记录事务（决策 7）：中途失败时已写成员保留（诚实的部分结果）并抛 CATALOG_WRITE_FAILED；运行级溯源随每条成员走，同一 builder 单点写入，不会漂移（决策 2）。

load_record_ephemeris(record_id: str) → tuple[dict, e2m2e.data.types.trajectory.EphemerisTable]#: 取库中记录的元数据与星历段（control_orbit 的 input_record_id 输入源）。

_get_record(record_id: str) → Any#: 取完整记录；不存在抛 RECORD_NOT_FOUND，记录损坏抛 CATALOG_READ_FAILED。

_ingest_sweep_outcome(outcome: Any, family_request: Any) → str | None#: 扫描单点结果逐成员入库，返回 family_id；硬失败点（result=None）无记录。

orbit_family_generation(progress_callback: e2m2e.api.facade.ProgressCallback | None = None, **params) → e2m2e.api.models.FamilyGenerationResponse#

轨道族生成（二档）。

Pydantic 模型校验 → 按 orbit_type 分派到算法层族生成入口 → 结构化错误。九族均已实现，成功返回统一容器 FamilyGenerationResponse``（兼容 ``OrbitFamily 读取接口）； Lissajous 是拟周期参数采样，族上显式标注 periodicity=quasi-periodic。软失败使用同一响应保留部分族。 progress_callback(fraction, message) 上报阶段级进度（族生成是单次 Rust 调用，仅起止两端；逐成员进度待 Rust 侧通道）。

catalog_query(**params) → e2m2e.api.models.CatalogQueryResponse#: 多维过滤查询，返回摘要列表（不含数组段与请求快照）。

catalog_get(**params) → e2m2e.api.models.CatalogRecordResponse#: 按 record_id 取完整记录（含数组段）；不存在抛 RECORD_NOT_FOUND。

catalog_delete(**params) → e2m2e.api.models.CatalogDeleteResponse#: 按 record_id 删除记录（文件与索引条目）；删除不可撤销。

catalog_tag(**params) → e2m2e.api.models.CatalogTagResponse#: 写教学标注入 JSON 记录（随文件走）；tags 整体替换，note=None 保留。

catalog_export(**params) → e2m2e.api.models.CatalogExportResponse#: 把查询子集打包导出（标注随包）；包可直接作为库打开。

catalog_terminology() → e2m2e.api.models.CatalogTerminologyResponse#: 术语清单（ADR 0044）：分类学标签图例 + orbit_family 闭值集 + transfer_type 闭值集，无参数。包版本即术语版本：调用方每会话取一次、升级后刷新，未知标签按可读规范串原样渲染。

catalog_sweep(**params) → e2m2e.api.models.CatalogSweepResponse#

参数空间扫描批量生成并入库（编排复用 ADR 0029 的 Rust 族生成）。

网格 = 族 × 平动点 × 主参数维度（一维振幅/近月点高度、能量窗口、 LISSAJOUS 二维振幅，三选一）；部分参数点失败时已产出的记录保留，失败原因逐点可查（ADR 0020 软失败语义）。