Skip to content

feature: split fleet-sim optimizer kernels from public export surfaces #1594

@Xunzhuo

Description

@Xunzhuo

Describe the feature

Create a bounded cleanup workstream for the fleet-sim optimizer/public API surface so contributors can narrow the current hotspot without widening the public export contract accidentally.

Primary files and seams:

  • src/fleet-sim/fleet_sim/optimizer/base.py
  • src/fleet-sim/fleet_sim/optimizer/__init__.py
  • src/fleet-sim/fleet_sim/__init__.py
  • optimizer-facing tests and API callers under src/fleet-sim/**

Primary layer

global level

Why this layer?

This is not one new optimizer feature. It is a cross-cutting architecture cleanup covering internal analytical kernels, package exports, and contributor-facing module boundaries.

Why do you need this feature?

The current repo audit found that the fleet-sim optimizer surface still collapses too many responsibilities into one seam:

  • src/fleet-sim/fleet_sim/optimizer/base.py is still a relaxed legacy hotspot in tools/agent/structure-rules.yaml
  • current structure_check still reports the file at 1730 lines with multiple oversized functions
  • optimizer/__init__.py and fleet_sim/__init__.py both re-export a broad optimizer surface, so one optimizer change can force edits in internal modeling code and multiple public export layers

This gap is tracked in docs/agent/tech-debt/td-027-fleet-sim-optimizer-and-public-surface-boundary-collapse.md and execution planning already exists in docs/agent/plans/pl-0009-fleet-sim-optimizer-and-operator-config-boundary-ratchet.md, but there is currently no dedicated GitHub issue for external contributors.

Additional context

Suggested acceptance criteria:

  • analytical sizing, DES verification/calibration, power or flexibility analysis, and report helpers are split into narrower sibling modules instead of continuing to accumulate in base.py
  • src/fleet-sim/fleet_sim/optimizer/__init__.py becomes the primary optimizer export seam
  • src/fleet-sim/fleet_sim/__init__.py curates a deliberate subset instead of mirroring broad optimizer internals
  • future optimizer changes can land without reopening both internal kernels and root export lists unless the change is intentionally public API work
  • validation follows the fleet-sim harness path (make vllm-sr-sim-test plus the relevant agent gates for touched files)

Relevant local rules:

  • src/fleet-sim/AGENTS.md
  • src/fleet-sim/fleet_sim/optimizer/AGENTS.md

This is a good help wanted item, but it is not a good first issue: the work crosses runtime math, exports, and package-boundary decisions.

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

Status

In progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions