> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.nvidia.com/dynamo/llms.txt. For full content including API reference and SDK examples, see https://docs.nvidia.com/dynamo/llms-full.txt.

# Sweeper

<!--
Generated from `aisimulate/docs/sweeper/overview.md` by `docs/fern/scripts/sync_aisimulate_docs.py`.
Edit the canonical source instead of this Fern copy.
-->

<Warning>
**Experimental.** Sweeper is intended for evaluation and feedback, not production capacity
planning. Its API, configuration schema, search behavior, and output may change without a
standard deprecation period.
</Warning>

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](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/quickstart) runs a small backend-neutral sweep.
- [Tutorial](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/tutorial) explains a complete sweep configuration.
- [Architecture](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/architecture) shows the provider, replay, and worker boundaries.
- [Configuration](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/configuration) describes core and adapter-owned search spaces.
- [Traffic](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/traffic) defines trace, request-rate, concurrency, and KV-load workloads.
- [Optimization Goals](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/optimization-goals) defines scalar and Pareto objectives.
- [Results](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/results) describes `ReplaySpec` and `Candidate` output.
- [Sweep Configuration Providers](/dynamo/dev/knowledge-base/modular-components/ai-simulate/sweeper/sweep-configuration-providers) documents the extension ABI.

## Python Entry Point

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

```python
from aisimulate.sweeper import SmartSearchConfig, Sweeper

config = SmartSearchConfig.from_yaml("sweep.yaml")
candidates = Sweeper(runner_factory=my_runner_factory).run(config)
```

The standalone `python -m aisimulate.sweeper` command validates configuration but deliberately does
not choose a replay implementation.

## 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. Native G2 replaces that path; Sweeper does not forward the old
  host or disk offload settings.