Skip to content

[docs] Add GEPA gepa_kwargs documentation #8998

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[docs] Add GEPA gepa_kwargs documentation #8998

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d00cf4f
Add GEPA gepa_kwargs documentation
GabrielLoiseau Oct 29, 2025
85dcbef
Remove unnecessary arguments
GabrielLoiseau Oct 31, 2025
b665b28
Add MLflow args
GabrielLoiseau Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions dspy/teleprompt/gepa/gepa.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ def metric(
Note: When both instruction_proposer and reflection_lm are set, the instruction_proposer is called
in the reflection_lm context. However, reflection_lm is optional when using a custom instruction_proposer.
Custom instruction proposers can invoke their own LLMs if needed.
component_selector: Custom component selector implementing the ReflectionComponentSelector protocol,
component_selector: Custom component selector implementing the [ReflectionComponentSelector](https://github.com/gepa-ai/gepa/blob/main/src/gepa/proposer/reflective_mutation/base.py) protocol,
or a string specifying a built-in selector strategy. Controls which components (predictors) are selected
for optimization at each iteration. Defaults to 'round_robin' strategy which cycles through components
one at a time. Available string options: 'round_robin' (cycles through components sequentially),
Expand Down Expand Up @@ -274,7 +274,34 @@ def metric(
called with and without the pred_name. This flag (defaults to True) determines whether a warning is
raised if a mismatch in module-level and predictor-level score is detected.
seed: The random seed to use for reproducibility. Default is 0.
gepa_kwargs: (Optional) provide additional kwargs to be passed to [gepa.optimize](https://github.com/gepa-ai/gepa/blob/main/src/gepa/api.py) method
gepa_kwargs: (Optional) Additional keyword arguments to pass directly to [gepa.optimize](https://github.com/gepa-ai/gepa/blob/main/src/gepa/api.py).
Useful for accessing advanced GEPA features not directly exposed through DSPy's GEPA interface.

Available parameters:
- batch_sampler: Strategy for selecting training examples. Can be a [BatchSampler](https://github.com/gepa-ai/gepa/blob/main/src/gepa/strategies/batch_sampler.py) instance or a string
('epoch_shuffled'). Defaults to 'epoch_shuffled'. Only valid when reflection_minibatch_size is None.
- merge_val_overlap_floor: Minimum number of shared validation ids required between parents before
attempting a merge subsample. Only relevant when using `val_evaluation_policy` other than 'full_eval'.
Default is 5.
- stop_callbacks: Optional stopper(s) that return True when optimization should stop. Can be a single
[StopperProtocol](https://github.com/gepa-ai/gepa/blob/main/src/gepa/utils/stop_condition.py) or a list of StopperProtocol instances.
Examples: [FileStopper](https://github.com/gepa-ai/gepa/blob/main/src/gepa/utils/stop_condition.py),
[TimeoutStopCondition](https://github.com/gepa-ai/gepa/blob/main/src/gepa/utils/stop_condition.py),
[SignalStopper](https://github.com/gepa-ai/gepa/blob/main/src/gepa/utils/stop_condition.py),
[NoImprovementStopper](https://github.com/gepa-ai/gepa/blob/main/src/gepa/utils/stop_condition.py),
or custom stopping logic. Note: This overrides the default
max_metric_calls stopping condition.
- use_cloudpickle: Use cloudpickle instead of pickle for serialization. Can be helpful when the
serialized state contains dynamically generated DSPy signatures. Default is False.
- val_evaluation_policy: Strategy controlling which validation ids to score each iteration. Can be
'full_eval' (evaluate every id each time) or an [EvaluationPolicy](https://github.com/gepa-ai/gepa/blob/main/src/gepa/strategies/eval_policy.py) instance. Default is 'full_eval'.
- use_mlflow: If True, enables MLflow integration to log optimization progress.
MLflow can be used alongside Weights & Biases (WandB).
- mlflow_tracking_uri: The tracking URI to use for MLflow (when use_mlflow=True).
Copy link
Collaborator

@TomeHirata TomeHirata Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have mlflow_tracking_uri and mlflow_experiment_name which are configured globally.

Copy link
Author

@GabrielLoiseau GabrielLoiseau Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are used within GEPA optimize function, should we remove them?

- mlflow_experiment_name: The experiment name to use for MLflow (when use_mlflow=True).

Note: Parameters already handled by DSPy's GEPA class will be overridden by the direct parameters
and should not be passed through gepa_kwargs.

Note:
Budget Configuration: Exactly one of `auto`, `max_full_evals`, or `max_metric_calls` must be provided.
Expand Down