> This page is for version v1.5.1.
> For other versions, use one of these documentation indexes:
> - Latest (v1.5.1) (default): https://docs.nvidia.com/dynamo/latest/llms.txt
> - dev: https://docs.nvidia.com/dynamo/dev/llms.txt
> - v1.5.1: https://docs.nvidia.com/dynamo/v1.5.1/llms.txt
> - v1.5.0: https://docs.nvidia.com/dynamo/v1.5.0/llms.txt
> - v1.4.2: https://docs.nvidia.com/dynamo/v1.4.2/llms.txt
> - v1.4.1: https://docs.nvidia.com/dynamo/v1.4.1/llms.txt
> - v1.4.0: https://docs.nvidia.com/dynamo/v1.4.0/llms.txt
> - v1.3.0: https://docs.nvidia.com/dynamo/v1.3.0/llms.txt
> - v1.2.1: https://docs.nvidia.com/dynamo/v1.2.1/llms.txt
> - v1.2.0: https://docs.nvidia.com/dynamo/v1.2.0/llms.txt
> - v1.1.1: https://docs.nvidia.com/dynamo/v1.1.1/llms.txt
> - v1.1.0: https://docs.nvidia.com/dynamo/v1.1.0/llms.txt
> - v1.0.2: https://docs.nvidia.com/dynamo/v1.0.2/llms.txt
> - v1.0.1: https://docs.nvidia.com/dynamo/v1.0.1/llms.txt
> - v1.0.0: https://docs.nvidia.com/dynamo/v1.0.0/llms.txt
> - v0.9.1: https://docs.nvidia.com/dynamo/v-0-9-1/llms.txt
> - v0.9.0: https://docs.nvidia.com/dynamo/v-0-9-0/llms.txt
> - v0.8.1: https://docs.nvidia.com/dynamo/v-0-8-1/llms.txt
> - v0.8.0: https://docs.nvidia.com/dynamo/v-0-8-0/llms.txt
> - v0.7.1: https://docs.nvidia.com/dynamo/v-0-7-1/llms.txt
> - v0.7.0: https://docs.nvidia.com/dynamo/v-0-7-0/llms.txt

> 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

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

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.