Open AI and Deep agents fix

Author: Shashikant86

docs/guides/deepagents-integration.md

@@ -8,12 +8,10 @@
     Learn how to build, run, evaluate, and optimize DeepAgents from scratch in 30 minutes:
 
     - ✅ Step-by-step with real expected outputs
-    - ✅ Tested with FREE Gemini API
+    - ✅ Works with FREE Gemini API
     - ✅ Persistent memory, real file access, hybrid storage
-    - ✅ GEPA optimization (+200% improvements)
+    - ✅ GEPA optimization guide
     - ✅ Production deployment guide
-    
-    **Everything tested and working!** 🎉
 
 ---
 
@@ -50,12 +48,19 @@ The biggest addition is the **backend abstraction** that lets you choose where a
 ## 📦 Installation
 
 ```bash
+# Install SuperOptiX with DeepAgents support
 pip install superoptix[frameworks-deepagents]
+
+# REQUIRED: Install Gemini integration (or your preferred LLM provider)
+pip install langchain-google-genai  # For Gemini
+# pip install langchain-anthropic   # For Claude
+# pip install langchain-openai      # For GPT-4
 ```
 
 **Includes:**
 - **deepagents 0.2.0+** with pluggable backends
 - SuperOptiX core with GEPA
+- LangChain integration (provider-specific packages need to be installed separately)
 - LangChain, LangGraph integration
 
 **Requirements:**
@@ -90,7 +95,7 @@ super agent run research_agent_deepagents --goal "What is LangGraph?"
 super agent evaluate research_agent_deepagents
 super agent optimize research_agent_deepagents --auto medium
 
-# ✅ Done! Agent optimized with 100% FREE Gemini calls
+# ✅ Done! Agent optimized with FREE Gemini calls
 ```
 
 **📖 Detailed Gemini Guide**: See `DEEPAGENTS_GEMINI_TEST.md` in repo root
@@ -174,8 +179,8 @@ super agent evaluate research_agent_deepagents --load-optimized
 ```
 
 **Expected Results:**
-- Baseline: 33.3% → After GEPA: 100% (+200% improvement!)
-- Cost: $0.00 with FREE Gemini
+- Baseline performance → After GEPA: Significant improvement (results vary by hardware and model)
+- Cost: $0.00 with FREE Gemini tier
 - Time: 5-10 minutes
 
 !!! success "📖 Want Detailed Step-by-Step Guide?"
@@ -184,10 +189,8 @@ super agent evaluate research_agent_deepagents --load-optimized
     This comprehensive tutorial shows you:
     - ✅ What to expect at each step (real outputs!)
     - ✅ How to configure all 3 backend types
-    - ✅ GEPA optimization walkthrough (33.3% → 100%)
+    - ✅ GEPA optimization walkthrough with examples
     - ✅ Production deployment guide
-    
-    **Everything tested and verified working!** 🎉
 
 ---
 
@@ -1110,7 +1113,7 @@ GEPA automatically:
 **Before (Baseline):**
 ```
 System Prompt: "You are an expert researcher."
-Pass Rate: 33.3%
+Pass Rate: Baseline performance (varies by hardware/model)
 ```
 
 **After GEPA Optimization:**
@@ -1120,7 +1123,7 @@ System Prompt: "You are an expert researcher. When answering questions:
 2. Save findings to research_notes.md
 3. Synthesize information before responding
 ..."
-Pass Rate: 66.7%
+Pass Rate: Improved (results vary by hardware/model)
 ```
 
 ---
@@ -1225,12 +1228,10 @@ SuperOptiX lets you:
     **30 minutes from zero to production:**
 
     - 🎯 Step 1-10: Build, run, evaluate, and optimize
-    - 📊 See real results: 33.3% → 100% with GEPA
+    - 📊 See real results with GEPA optimization
     - 🗄️ Learn all 3 backend types with examples
     - 🚀 Deploy production-ready agents
-    - 💰 100% FREE with Gemini
-    
-    **Everything tested and working!**
+    - 💰 FREE tier with Gemini
 
 **OR start exploring on your own:**
 

docs/guides/multi-framework.md

@@ -149,48 +149,60 @@ spec:
 
 ### 2. OpenAI Agents SDK (Simple & Fast)
 
-**Best for**: Simple agents, fast prototyping, Ollama compatibility
+**Best for**: Simple agents, fast prototyping, 100% local & free with Ollama
 
 #### Quick Start
 
 ```bash
-# Pull demo agent
+# Pull demo agent (already configured for Ollama!)
 super agent pull assistant_openai
 
-# Compile
+# Install Ollama (if not already installed)
+brew install ollama
+ollama pull gpt-oss:120b
+
+# Compile & Run (no API keys needed!)
 super agent compile assistant_openai --framework openai
+super agent run assistant_openai --goal "Hello!"
 
 # Evaluate
 super agent evaluate assistant_openai
 
 # Optimize
 super agent optimize assistant_openai --auto medium
-
-# Run
-super agent run assistant_openai
 ```
 
 #### Configuration
 
+**Default (FREE Ollama - already configured!)**:
 ```yaml
 # playbook.yaml
 spec:
   target_framework: openai
   language_model:
+    location: local
     provider: ollama
-    model: llama3.1:8b
+    model: ollama:gpt-oss:120b  # FREE, powerful!
     api_base: http://localhost:11434
-  persona:
-    instructions: |
-      You are a helpful AI assistant.
-      Provide clear, concise responses.
+```
+
+**Optional Cloud Models** (requires API key):
+```yaml
+# For OpenAI
+spec:
+  target_framework: openai
+  language_model:
+    location: cloud
+    provider: openai
+    model: openai:gpt-4o
+    # Set: export OPENAI_API_KEY="sk-..."
 ```
 
 #### What GEPA Optimizes
 
 - Agent instructions (the main system prompt)
 
-**Proven Results**: 100% pass rate
+**Proven Results**: Excellent performance with Ollama (results vary by hardware/model)
 
 ---
 
@@ -260,7 +272,7 @@ GEPA can optimize:
 - **Task configuration**: description, expected_output
 - **Combined optimization**: agent profile + task configuration for better results
 
-**Proven Results**: 100% pass rate
+**Proven Results**: Excellent performance with Ollama (results vary by hardware/model)
 
 ---
 
@@ -469,9 +481,9 @@ super agent evaluate my_agent
 
 | Framework | Demo Agent | Baseline | After GEPA | Improvement |
 |-----------|------------|----------|------------|-------------|
-| DSPy | sentiment_analyzer | 37.5% | 80.0% | +42.5 pts |
-| OpenAI SDK | assistant_openai | 100% | 100% | Maintained |
-| CrewAI | content_creator_crew | 75% | 100% | +25 pts |
+| DSPy | sentiment_analyzer | Good | Improved | Significant improvement (results vary) |
+| OpenAI SDK | assistant_openai | Excellent | Excellent | Maintained performance (results vary) |
+| CrewAI | content_creator_crew | Good | Improved | Significant improvement (results vary) |
 | Google ADK | assistant_adk | TBD | TBD | Ready |
 | Microsoft | assistant_microsoft | TBD | TBD | Ready |
 | DeepAgents | research_agent | TBD | TBD | Ready |

docs/guides/openai-sdk-integration.md

@@ -2,7 +2,7 @@
 
 **SuperOptiX now supports OpenAI Agents SDK - a lightweight, provider-agnostic framework that works PERFECTLY with Ollama!**
 
-✅ **100% Pass Rate Achieved with Ollama gpt-oss:20b on First Try!**
+✅ **Works great with FREE Ollama (No API Keys Needed!)**
 
 ---
 
@@ -49,28 +49,41 @@ super agent pull assistant_openai
 
 ### 2. Configure Model
 
-**✅ Works with Ollama!** (Recommended for local development)
+**✅ Uses Ollama by Default!** (FREE, no API keys needed!)
+
+The `assistant_openai` agent now defaults to Ollama `gpt-oss:120b`:
 
 ```yaml
 language_model:
   location: local
   provider: ollama
-  model: ollama:gpt-oss:20b
+  model: ollama:gpt-oss:120b  # Most powerful free model
   temperature: 0.7
   api_base: http://localhost:11434
 ```
 
-**Also Works With:**
+**Just install Ollama and run:**
+```bash
+brew install ollama  # macOS
+ollama pull gpt-oss:120b
+super agent run assistant_openai --goal "Hello!"
+```
+
+**Also Works With Cloud Models** (requires API key):
 ```yaml
-# OpenAI (cloud)
+# OpenAI GPT-4
 language_model:
+  location: cloud
   provider: openai
-  model: gpt-4.1
+  model: openai:gpt-4o
+  # Set: export OPENAI_API_KEY="sk-..."
 
-# OpenAI (alternative)
+# Anthropic Claude
 language_model:
-  provider: openai
-  model: gpt-4-turbo
+  location: cloud
+  provider: anthropic
+  model: anthropic:claude-sonnet-4-20250514
+  # Set: export ANTHROPIC_API_KEY="sk-ant-..."
 ```
 
 ### 3. Run the Workflow
@@ -79,7 +92,7 @@ language_model:
 # Compile
 super agent compile assistant_openai --framework openai
 
-# Evaluate (expect 100% pass rate!)
+# Evaluate
 super agent evaluate assistant_openai
 
 # Optimize with GEPA
@@ -226,7 +239,7 @@ GEPA will test variations to find the best instructions!
 super agent evaluate assistant_openai
 ```
 
-See if GEPA improved the already perfect 100% pass rate!
+See if GEPA improved the pass rate!
 
 ### Step 7: Run
 
@@ -319,7 +332,7 @@ class AssistantOpenAiPipeline:
 | Feature | DSPy | DeepAgents | OpenAI SDK |
 |---------|------|------------|------------|
 | **Ollama Support** | ✅ Full | ❌ Blocked | ✅ Perfect |
-| **Baseline Pass Rate** | 37.5% | N/A | 100% 🏆 |
+| **Baseline Performance** | Good | N/A | Excellent |
 | **API Complexity** | Medium | High | Low |
 | **Planning** | Manual | Built-in | Manual |
 | **Multi-Agent** | Manual | Subagents | Handoffs |
@@ -491,7 +504,7 @@ persona:
   goal: Provide clear responses
 
 → instructions = "Helpful AI Assistant\nGoal: Provide clear responses"
-→ Baseline: 75% pass rate
+→ Baseline: Good performance (results vary by hardware/model)
 ```
 
 **After GEPA:**
@@ -506,7 +519,7 @@ When answering questions:
 
 Goal: Provide clear, helpful responses that directly address the user's query."
 
-→ Optimized: 90% pass rate (15% improvement!)
+→ Optimized: Improved performance (results vary by hardware/model)
 ```
 
 ---
@@ -576,11 +589,11 @@ language_model:
 - ✅ Free inference
 - ✅ Privacy (data stays local)
 - ✅ Fast development iteration
-- ✅ 100% baseline pass rate!
+- ✅ Good baseline performance
 
 **Supported Ollama Models:**
-- `ollama:gpt-oss:20b` (recommended, 100% pass rate)
-- `ollama:gpt-oss:120b` (more capable)
+- `ollama:gpt-oss:120b` (default, most capable)
+- `ollama:gpt-oss:20b` (faster alternative)
 - `ollama:llama3.1:8b` (faster, lower capability)
 - `ollama:qwen3:8b` (alternative)
 
@@ -601,7 +614,7 @@ Set API key: `export OPENAI_API_KEY=your_key`
 
 ### OpenAI SDK Advantages
 - ✅ **Ollama compatibility** (unlike DeepAgents)
-- ✅ **100% baseline performance**
+- ✅ **Good baseline performance**
 - ✅ **Simple, clean API**
 - ✅ **Built-in tracing and sessions**
 - ✅ **Fast compilation and execution**
@@ -686,19 +699,19 @@ spec:
 
 ### Baseline Comparison (Same BDD Scenarios)
 
-| Framework | Model | Pass Rate | Cost | Speed |
-|-----------|-------|-----------|------|-------|
-| **OpenAI SDK** | gpt-oss:20b | **100%** 🏆 | Free | Fast |
-| **DSPy** | llama3.1:8b | 37.5% | Free | Fast |
+| Framework | Model | Performance | Cost | Speed |
+|-----------|-------|-------------|------|-------|
+| **OpenAI SDK** | gpt-oss:120b | Excellent | Free | Medium |
+| **DSPy** | llama3.1:8b | Good | Free | Fast |
 | **DSPy** | gpt-4 | 85% | $$$ | Medium |
 | **DeepAgents** | Claude | N/A | $$ | Medium |
 
 ### After GEPA Optimization
 
 | Framework | Baseline | After GEPA | Improvement |
 |-----------|----------|------------|-------------|
-| **OpenAI SDK** | 100% | 100% | 0% (already perfect!) |
-| **DSPy** | 37.5% | 55% | +17.5% |
+| **OpenAI SDK** | High | High | Moderate improvement |
+| **DSPy** | Good | Better | Significant improvement (results vary) |
 
 **Key Insight:** OpenAI SDK achieves better baseline with Ollama!
 
@@ -801,7 +814,7 @@ This is based on the official OpenAI Agents SDK example for Ollama!
 
 ### Baseline Performance
 
-**"We got 100% pass rate on the FIRST evaluation!"**
+**"Great results on the first evaluation!"**
 
 With simple, clear BDD scenarios and gpt-oss:20b model, the OpenAI SDK achieved perfect baseline performance. This demonstrates:
 
@@ -864,7 +877,7 @@ scenarios:
 ## ❓ FAQ
 
 **Q: Why use OpenAI SDK instead of DSPy?**  
-A: OpenAI SDK has simpler API and better Ollama baseline (100% vs 37.5%). Use DSPy for maximum optimization potential.
+A: OpenAI SDK has simpler API and works well with Ollama out of the box. Use DSPy for maximum optimization flexibility. Performance varies by hardware and model.
 
 **Q: Does it work with Ollama?**  
 A: Yes! Perfectly! Unlike DeepAgents, OpenAI SDK has no function-calling limitations.
@@ -897,7 +910,7 @@ A: Use `handoffs` for agent delegation. Works similar to CrewAI's crew concept.
 **SuperOptiX now supports THREE frameworks:**
 1. ✅ DSPy (Ollama compatible, max optimization)
 2. ✅ DeepAgents (planning & complexity, Claude/GPT-4 only)
-3. ✅ OpenAI SDK (simple & powerful, **100% with Ollama!** 🏆)
+3. ✅ OpenAI SDK (simple & powerful, great Ollama support)
 
 **All with:**
 - Same SuperSpec YAML format
@@ -907,6 +920,6 @@ A: Use `handoffs` for agent delegation. Works similar to CrewAI's crew concept.
 
 ---
 
-*Try it now: `super agent pull assistant_openai` and experience 100% pass rate with Ollama!* 🚀
+*Try it now: `super agent pull assistant_openai` and experience great performance with Ollama!* 🚀