Update Optimas docs

Author: Shashikant86

docs/environment-setup.md

@@ -194,7 +194,7 @@ Virtual environments isolate project dependencies, preventing conflicts between
 === "⚡ uv (Recommended)"
     ```bash
     # Install SuperOptiX
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
 
     # Install with optional dependencies
     uv pip install "superoptix[vectordb,ui,observability]"
@@ -485,7 +485,7 @@ which pip
     curl -LsSf https://astral.sh/uv/install.sh | sh
 
     # Use uv instead of pip
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
     ```
 
 === "📦 Using Conda for Better Dependency Resolution"

docs/examples/agents/optimas-examples.md

@@ -6,6 +6,16 @@ title: Optimas Examples
 
 Working examples and demos for all Optimas integration targets. These examples have been verified to work correctly with the latest SuperOptiX version.
 
+Background reading and references:
+
+- Optimas website: [optimas.stanford.edu](https://optimas.stanford.edu)
+- Optimas paper (Wu et al., 2025): [arXiv: 2507.03041](https://www.arxiv.org/pdf/2507.03041)
+- DSPy: [dspy.ai](https://dspy.ai)
+- CrewAI: [docs.crewai.com](https://docs.crewai.com)
+- AutoGen: [microsoft.github.io/autogen](https://microsoft.github.io/autogen/)
+- OpenAI Agent SDK: [platform.openai.com/docs/agents](https://platform.openai.com/docs/agents)
+- LiteLLM: [github.com/BerriAI/litellm](https://github.com/BerriAI/litellm)
+
 ## 🚀 Quick Demo
 
 ### Pull Demo Playbooks

docs/guides/optimas-integration.md

@@ -6,6 +6,67 @@ title: Optimas Integration Guide
 
 SuperOptiX integrates seamlessly with the **Optimas** framework, enabling you to use advanced prompt optimization techniques (OPRO, MIPRO, COPRO) with multiple LLM frameworks including **OpenAI SDK**, **CrewAI**, **AutoGen**, and **DSPy**.
 
+> About Optimas: Optimas optimizes compound AI systems using globally aligned Local Reward Functions (LRFs) so that local improvements translate to higher end‑to‑end performance. Learn more on the official site and paper:
+
+- Optimas website: [optimas.stanford.edu](https://optimas.stanford.edu)
+- Optimas paper (Wu et al., 2025): [arXiv: 2507.03041](https://www.arxiv.org/pdf/2507.03041)
+
+Related frameworks supported by this guide:
+
+- DSPy: [dspy.ai](https://dspy.ai)
+- CrewAI: [docs.crewai.com](https://docs.crewai.com)
+- AutoGen: [microsoft.github.io/autogen](https://microsoft.github.io/autogen/)
+- OpenAI Agent SDK: [platform.openai.com/docs/agents](https://platform.openai.com/docs/agents)
+- LiteLLM (used by some targets): [github.com/BerriAI/litellm](https://github.com/BerriAI/litellm)
+
+## What Optimas is (and why it matters)
+
+[Optimas](https://optimas.stanford.edu) is a unified optimization framework for compound AI systems:
+
+- Learns a Local Reward Function (LRF) per component that remains globally aligned, so local updates are safe and beneficial to the whole system. This enables efficient optimization without always running the entire pipeline. See: [arXiv: 2507.03041](https://www.arxiv.org/pdf/2507.03041).
+- Supports heterogeneous configuration types:
+  - Prompts and textual instructions via metric‑guided search
+  - Hyperparameters and discrete choices (e.g., top‑k, tool/model selection, routing)
+  - Model parameters where supported (e.g., RL with PPO)
+- Works across frameworks via target adapters: [OpenAI Agent SDK](https://platform.openai.com/docs/agents), [CrewAI](https://docs.crewai.com), [AutoGen](https://microsoft.github.io/autogen/), and [DSPy](https://dspy.ai)
+- Compound‑system optimization: operates across multiple components and tools, not just single prompts
+- Multiple optimizers available: OPRO (single‑iteration), MIPRO (multi‑iteration), COPRO (cooperative)
+
+## What this unlocks
+
+- Optimize prompts, hyperparameters, model parameters, and model routers across compound AI systems
+- Run OPRO, MIPRO, and COPRO optimization loops through a single CLI workflow
+- Keep your preferred agent stack (DSPy, CrewAI, AutoGen, OpenAI SDK) and get consistent optimization behavior
+
+## Why this is impactful
+
+- Globally aligned local rewards: maximizing a component’s local reward increases overall system quality, improving data efficiency by reducing full system runs
+- Heterogeneous updates across prompts, hyperparameters, routing/model selection, and (where applicable) model parameters via RL
+- Reported average relative improvement of 11.92% across five compound systems with theoretical guarantees and strong empirical results:
+  - Optimas site: [optimas.stanford.edu](https://optimas.stanford.edu)
+  - Paper: [arXiv: 2507.03041](https://www.arxiv.org/pdf/2507.03041)
+
+## Where Optimas fits in SuperOptiX
+
+Optimas integrates into the standard SuperOptiX lifecycle:
+
+1. Compile your agent for a specific target
+2. Evaluate to establish a baseline
+3. Optimize with Optimas (OPRO/MIPRO/COPRO) using the same CLI across targets
+4. Run the optimized agent
+
+This extends optimization beyond prompts to hyperparameters, model selection/routing, and parameters where supported.
+
+- Focus‑aligned: SuperOptiX is built for optimization; Optimas operationalizes it across agents and tools
+- Beyond prompts: optimize prompts, hyperparameters, parameters, and routers for production workflows
+- One CLI to rule them all: compile → evaluate → optimize → run across all targets
+
+## Optimas vs. DSPy (complementary)
+
+- [DSPy](https://dspy.ai) is a framework for composing LLM pipelines and programmatic teleprompting
+- Optimas is an optimization engine that runs globally aligned local updates across multi‑component systems, regardless of the underlying framework (including DSPy)
+- In practice: build in your preferred stack; use Optimas to optimize end‑to‑end. If using DSPy, try `--optimizer mipro` for deeper prompt refinement (OPRO and COPRO also supported)
+
 ## 🚀 Quick Start
 
 ### 1. Install SuperOptiX with Optimas Support
@@ -447,4 +508,14 @@ SUPEROPTIX_OPRO_COMPILE_TIMEOUT=300
 - [CLI Reference](../reference/cli.md) - Complete command reference
 - [Agent Development](../guides/agent-development.md) - Building custom agents
 
+## 📖 External References
+
+- Optimas website: [optimas.stanford.edu](https://optimas.stanford.edu)
+- Optimas paper (Wu et al., 2025): [arXiv: 2507.03041](https://www.arxiv.org/pdf/2507.03041)
+- DSPy: [dspy.ai](https://dspy.ai)
+- CrewAI: [docs.crewai.com](https://docs.crewai.com)
+- AutoGen: [microsoft.github.io/autogen](https://microsoft.github.io/autogen/)
+- OpenAI Agent SDK: [platform.openai.com/docs/agents](https://platform.openai.com/docs/agents)
+- LiteLLM: [github.com/BerriAI/litellm](https://github.com/BerriAI/litellm)
+
 

docs/quick-start.md

@@ -61,7 +61,7 @@ Choose your preferred method:
     curl -LsSf https://astral.sh/uv/install.sh | sh
     
     # Install SuperOptiX
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
     
     # Verify installation
     super --help

docs/setup.md

@@ -39,13 +39,13 @@ Choose your preferred installation method:
     ### Install SuperOptiX with UV
     ```bash
     # Basic installation
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
 
     # With specific extras
     uv pip install "superoptix[ui,vectordb,observability]"
 
     # Latest from PyPI
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
     ```
 
 === "🐍 Pip"
@@ -93,7 +93,7 @@ Choose your preferred installation method:
     curl -LsSf https://astral.sh/uv/install.sh | sh
 
     # Install SuperOptiX
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
     ```
 
     ### Using Conda
@@ -121,7 +121,7 @@ Choose your preferred installation method:
     curl -LsSf https://astral.sh/uv/install.sh | sh
 
     # Install SuperOptiX
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
     ```
 
     ### CentOS/RHEL/Fedora
@@ -136,7 +136,7 @@ Choose your preferred installation method:
     curl -LsSf https://astral.sh/uv/install.sh | sh
 
     # Install SuperOptiX
-    uv pip install superoptix --prerelease=allow
+    uv pip install superoptix
     ```
 
 === "🪟 Windows"

docs/troubleshooting.md

@@ -129,7 +129,7 @@ pip install --upgrade pip
 pip search superoptix
 
 # Install from PyPI
-pip install superoptix --prerelease=allow
+pip install superoptix
 ```
 
 ## 🚀 Still Having Issues?