Sweeper

Sweeper searches deployment configurations with a black-box optimizer. It turns every suggestion into a versioned ReplaySpec, sends that specification to an injected RunnerFactory, and returns ranked candidates or a Pareto front.

The aisimulate package owns only backend-neutral simulation behavior. Optional feature packages can register a SweepConfigProvider that contributes search dimensions and materializes its part of a replay. Sweeper imports a provider only when its adapter name appears in the configuration.

Start Here

• Quickstart runs a small backend-neutral sweep.
• Tutorial explains a complete sweep configuration.
• Architecture shows the provider, replay, and worker boundaries.
• Configuration describes core and adapter-owned search spaces.
• Traffic defines trace, request-rate, concurrency, and KV-load workloads.
• Optimization Goals defines scalar and Pareto objectives.
• Results describes ReplaySpec and Candidate output.
• Sweep Configuration Providers documents the extension ABI.

Python Entry Point

Sweeper is the only public execution interface. Supply a replay runtime explicitly:

from aisimulate.sweeper import SmartSearchConfig, Sweeper
config = SmartSearchConfig.from_yaml("sweep.yaml")
candidates = Sweeper(runner_factory=my_runner_factory).run(config)

For the public YAML contract and stack discovery, use aisimulate recommend --config recommendation.yaml. The Sweeper class remains available for callers that need the legacy Python SDK configuration and an explicitly injected runtime.

Compatibility

• A provider is imported only when its adapter name appears under adapters.
• The runner advertises supported ReplaySpec versions, backend/topology pairs, and runtime hooks before a study starts.
• Every Sweeper.run call owns fresh optimizer studies, result caches, runners, and worker pools.
• KVBM search fields are rejected. The AISimulate engine and replay path do not support those fields and provide no adapter migration for the old host or disk offload settings.