Refinements

Author: andressrg

docs/docs/api/optimizers/GEPA.md

@@ -147,7 +147,7 @@ gepa = dspy.GEPA(
 
 We invite community contributions of new instruction proposers for specialized domains as the [GEPA library](https://github.com/gepa-ai/gepa) continues to grow.
 
-### How to Implement Custom Proposer
+### How to Implement Custom Instruction Proposers
 
 Custom instruction proposers must implement the `ProposalFn` protocol:
 
@@ -167,7 +167,7 @@ def __call__(
 - `ReflectiveExample` TypedDict contains:
   - `Inputs: dict[str, Any]` - Predictor inputs (may include dspy.Image objects)
   - `Generated_Outputs: dict[str, Any] | str` - Success: output fields dict, Failure: error message
-  - `Feedback: str` - Always a string from metric function or parsing error
+  - `Feedback: str` - Always a string from metric function or auto-generated by GEPA
 
 #### Basic Example: Word Limit Proposer
 
@@ -210,7 +210,7 @@ class WordLimitProposer(ProposalFn):
             result = self.instruction_improver(
                 current_instruction=current_instruction,
                 issues_found=feedback_text,
-                max_words=str(self.max_words)
+                max_words=self.max_words
             )
 
             updated_components[component_name] = result.improved_instruction
@@ -243,7 +243,7 @@ class GenerateDocumentationQuery(dspy.Signature):
 
     failure_patterns: str = dspy.OutputField(desc="Summarize the common failure patterns identified in the examples")
 
-    retrieval_queries: list[str] = dspy.OutputField(desc="Specific search query to find relevant documentation in the database that addresses the common issue patterns identified in the problematic examples")
+    retrieval_queries: list[str] = dspy.OutputField(desc="Specific search queries to find relevant documentation in the database that addresses the common issue patterns identified in the problematic examples")
 
 class GenerateRAGEnhancedInstruction(dspy.Signature):
     """Generate improved instructions using retrieved documentation and examples analysis."""
@@ -273,19 +273,22 @@ class RAGInstructionImprover(dspy.Module):
         )
 
         # Retrieve relevant documentation using multiple queries
-        all_retrieved_docs = []
-        for query in query_result.retrieval_queries:
-            retrieved_docs = self.retrieve(query)
-            if hasattr(retrieved_docs, 'passages'):
-                all_retrieved_docs.extend(retrieved_docs.passages)
-            else:
-                all_retrieved_docs.append(str(retrieved_docs))
+        results = self.retrieve.query(
+            query_texts=query_result.retrieval_queries,
+            n_results=3
+        )
+        
+        # Format retrieved documentation by query
+        relevant_docs_parts = []
+        for i, (query, query_docs) in enumerate(zip(query_result.retrieval_queries, results['documents'])):
+            if query_docs:  # Only include queries that found results
+                docs_formatted = "\n".join([f"  - {doc}" for doc in query_docs])
+                relevant_docs_parts.append(
+                    f"**Search Query #{i+1}**: {query}\n"
+                    f"**Retrieved Guidelines**:\n{docs_formatted}"
+                )
 
-        # Format retrieved documentation
-        relevant_docs = "\n\n".join([
-            f"Guideline {i+1}: {doc}" 
-            for i, doc in enumerate(all_retrieved_docs)
-        ])
+        relevant_docs = "\n\n" + "="*60 + "\n\n".join(relevant_docs_parts) + "\n" + "="*60
 
         # Generate improved instruction with retrieved context
         result = self.generate_answer(
@@ -327,22 +330,18 @@ class DocumentationEnhancedProposer(ProposalFn):
 
         return updated_components
 
-# Usage - Setup specialized documentation retriever
-import dspy
-from dspy.retrieve.chromadb_rm import ChromadbRM
+# Usage - Connect to existing ChromaDB collection
+import chromadb
 
-# Setup retriever for your specialized documentation
-doc_retriever = ChromadbRM(
-    collection_name="instruction_guidelines",
-    persist_directory="./specialized_docs_db",
-    k=5  # Retrieve top 5 relevant documents
-)
+# Connect to existing ChromaDB collection with instruction guidelines
+client = chromadb.Client()
+collection = client.get_collection("instruction_guidelines")
 
 # Configure the RAG-enhanced proposer
 gepa = dspy.GEPA(
     metric=task_specific_metric,
     reflection_lm=dspy.LM(model="gpt-5", temperature=1.0, max_tokens=32000, api_key=api_key),
-    instruction_proposer=DocumentationEnhancedProposer(doc_retriever),
+    instruction_proposer=DocumentationEnhancedProposer(collection),
     auto="medium"
 )
 ```