Skip to content

Commit 7d64e7a

Browse files
committed
docs(gepa): update tool optimization docs for ReAct-only support
1 parent 3fd9a0a commit 7d64e7a

File tree

1 file changed

+9
-11
lines changed

1 file changed

+9
-11
lines changed

docs/docs/api/optimizers/GEPA/GEPA_Advanced.md

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -459,7 +459,7 @@ Many DSPy programs use tools, with modules like `dspy.ReAct` as canonical exampl
459459

460460
### Tool Module Optimization Prompt
461461

462-
GEPA uses `ToolModuleProposer` to optimize tool-using modules when `enable_tool_optimization=True`. For each module, the proposer builds a dynamic signature from the base `GenerateImprovedToolModuleDescriptionsFromFeedback` signature shown below, then appends output fields for each tool description and each tool argument description in that module. For ReAct modules, the proposer also appends input and output fields for the extract instruction.
462+
GEPA uses `ToolProposer` to optimize tool-using modules when `enable_tool_optimization=True`. For each module, the proposer builds a dynamic signature from the base `GenerateImprovedToolModuleDescriptionsFromFeedback` signature shown below, then appends output fields for each tool description and each tool argument description in that module. For ReAct modules, the proposer also appends input and output fields for the extract instruction.
463463

464464
```python
465465
class GenerateImprovedToolModuleDescriptionsFromFeedback(dspy.Signature):
@@ -509,12 +509,12 @@ The reflection LM uses this dynamically-built signature to jointly propose updat
509509

510510
When `enable_tool_optimization=True`, GEPA:
511511

512-
1. **Discovers tool-using modules** - Identifies any module that uses `dspy.Tool` instances, including `dspy.ReAct` and generic predictors with `dspy.Tool` as an input field type in their signatures
512+
1. **Discovers ReAct modules** - Identifies `dspy.ReAct` modules and their associated tools
513513
2. **Treats them as joint optimization units** - Instead of only optimizing predictor instructions, GEPA optimizes predictor instructions and tool descriptions together as a coordinated set; for ReAct this includes both the react and extract instructions
514514
3. **Routes to specialized proposer** - Separates components by type and routes them appropriately:
515-
- **With custom `instruction_proposer`**: Your custom proposer receives both tool-using modules and plain predictors, and is responsible for updating all components
516-
- **With default proposer**: Plain predictors use the default instruction proposer; tool-using modules use `ToolModuleProposer`, which employs the dynamic signature mechanism described above
517-
4. **Optimizes jointly** - `ToolModuleProposer` improves predictor instructions and tool descriptions together based on execution feedback, coordinating updates across all components rather than tuning them in isolation
515+
- **With custom `instruction_proposer`**: Your custom proposer receives both ReAct modules and plain predictors, and is responsible for updating all components
516+
- **With default proposer**: Plain predictors use the default instruction proposer; ReAct modules use `ToolProposer`, which employs the dynamic signature mechanism described above
517+
4. **Optimizes jointly** - `ToolProposer` improves predictor instructions and tool descriptions together based on execution feedback, coordinating updates across all components rather than tuning them in isolation
518518
5. **Applies updates** - Improved instructions update predictor signatures; improved tool descriptions and argument descriptions update all `dspy.Tool` objects with matching tool names throughout the program
519519

520520
Modules without tools (like `dspy.Predict` or `dspy.ChainOfThought`) continue using standard GEPA instruction-only optimization.
@@ -660,15 +660,14 @@ When you provide a custom `instruction_proposer`, GEPA routes **all components**
660660
**What your proposer receives:**
661661

662662
- **Plain predictors**: instruction strings keyed by predictor name
663-
- **Tool-using modules**: JSON strings keyed by module identifier, containing predictor instructions and tool schemas
664-
- Generic tool modules: `f"{TOOL_MODULE_PREFIX}:{predictor_name}"`
663+
- **ReAct modules**: JSON strings keyed by module identifier, containing predictor instructions and tool schemas
665664
- ReAct modules: `f"{REACT_MODULE_PREFIX}:{extract_predictor_name}"`
666665

667666
**Your proposer's responsibilities:**
668667

669668
```python
670669
import json
671-
from dspy.teleprompt.gepa.gepa_utils import REACT_MODULE_PREFIX, TOOL_MODULE_PREFIX
670+
from dspy.teleprompt.gepa.gepa_utils import REACT_MODULE_PREFIX
672671

673672
def custom_proposer(candidate, reflective_dataset, components_to_update):
674673
"""Custom instruction proposer for GEPA with tool optimization.
@@ -677,7 +676,6 @@ def custom_proposer(candidate, reflective_dataset, components_to_update):
677676
candidate: dict[str, str] - All components in the program
678677
{
679678
"predictor_name": "instruction string",
680-
"tool_module:pred_name": '{"pred_name": "...", "tools": {...}}',
681679
"react_module:extract_name": '{"react_name": "...", "extract_name": "...", "tools": {...}}'
682680
}
683681
reflective_dataset: dict[str, list[dict]] - Execution examples with feedback per component
@@ -689,7 +687,7 @@ def custom_proposer(candidate, reflective_dataset, components_to_update):
689687
improved_components = {}
690688

691689
for component_key in components_to_update:
692-
if component_key.startswith(REACT_MODULE_PREFIX) or component_key.startswith(TOOL_MODULE_PREFIX):
690+
if component_key.startswith(REACT_MODULE_PREFIX):
693691
config = json.loads(candidate[component_key])
694692
# Example: {"pred": "instruction", "tools": {"search": {"desc": "...", "args": {...}}}}
695693

@@ -746,4 +744,4 @@ ReAct:
746744
**What to preserve:**
747745
- `config["tools"][tool_name]["args"][arg_name]["type"]` and other schema metadata (changing these breaks the tool since they must match the underlying function's parameter types)
748746

749-
See [`ToolModuleProposer`](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/gepa/instruction_proposal.py) for reference.
747+
See [`ToolProposer`](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/gepa/instruction_proposal.py) for reference.

0 commit comments

Comments
 (0)