dspy-code 0.1.5

Claude Code for DSPy: AI-powered interactive development environment for DSPy

🚀 Your AI-Powered DSPy Development & Optimization Assistant

Develop DSPy Applications • Optimize with GEPA • Deploy with Confidence. Think of it as Claude Code for DSPy

📖 Documentation • 🤝 Contributing

---

🎯 What is DSPy Code?

DSPy Code is an AI-powered interactive development environment for building and optimizing DSPy applications. Think of it as Claude Code for DSPy - a specialized CLI that understands DSPy deeply and helps you:

• 🏗️ Develop DSPy applications with natural language
• 🧬 Optimize with real GEPA (Genetic Pareto) workflows
• 📚 Learn DSPy concepts as you build
• ✅ Validate code against best practices
• 🚀 Deploy production-ready applications

Perfect for beginners and experts alike - No matter if you just started learning DSPy or optimizing production systems, DSPy Code adapts to your needs.

---

📚 New to DSPy Code? You have two options:

• 📖 View Full Documentation - Comprehensive guides, tutorials, and reference at superagenticai.github.io/dspy-code
• ⚡ Continue Reading Below - Explore more sections in this README

Choose what works best for you! 👇

---

📑 Table of Contents

• What is DSPy Code? (Overview above)
• What is DSPy Code? (Detailed)
• Why DSPy Code?
• Two Core Workflows
• Code Examples
• Key Features
• What's New
• Quick Start
• Available Commands
• Primary Use Cases
• Model Connection
• GEPA Optimization
• Requirements
• Installation Options
• Architecture
• Documentation
• Need Help?
• Contributing
• License
• Roadmap
• Development Status
• Show Support
• Acknowledgments

---

⚡ Claude Code for DSPy

🚀 Get Started in 30 Seconds

✨ Always install the latest version for best experience ✨

pip install --upgrade dspy-code

Develop DSPy Applications → Optimize with GEPA → Deploy Production-Ready Apps

💡 Note: DSPy Code is in its initial release and under active development. The quality and effectiveness of generated code depends on several factors: the language model you connect, MCP (Model Context Protocol) servers you integrate, and the context you provide to DSPy Code. We're continuously improving based on community feedback.

---

✨ What is DSPy Code? (Detailed)

The Complete DSPy Development & Optimization Platform

DSPy Code is a dual-purpose CLI that empowers you to:

🏗️ Develop DSPy Applications

Build, learn, and create DSPy programs with natural language. Generate signatures, modules, and complete applications with AI-powered assistance.

🧬 Optimize with GEPA

Transform your DSPy code into production-ready applications using GEPA (Genetic Pareto). Automatically improve accuracy, evolve prompts, and achieve better performance.

The Complete Workflow:

Develop → Validate → Optimize with GEPA → Deploy

💡 Learn as you build. Whether you're a complete beginner or a DSPy expert, the CLI adapts to your level and guides you through every step.

🎯 Perfect For:

🏗️ Development	🧬 Optimization
🎓 Learning DSPy concepts	⚡ GEPA optimization workflows
🚀 Building new projects	📊 Automated metric evaluation
📝 Code generation	🔄 Prompt evolution
✅ Validation & best practices	📈 Performance improvement
📚 Codebase understanding	🎯 Production-ready code

🎯 Why DSPy Code?

"Why not just use Claude Code or Cursor, DeepWiki, CodeWiki with the DSPy repository?" While general AI assistants can help with DSPy, they lack the deep specialization that makes DSPy Code uniquely powerful:

What Makes DSPy Code Special?

Feature	Generic AI Assistants	DSPy Code
DSPy Knowledge	❌ Generic	✅ Deep, comprehensive - All 10 predictors, 11 optimizers, 4 adapters
Version Awareness	❌ None	✅ Adapts to your version - Indexes YOUR installed DSPy version
GEPA Optimization	❌ Code only	✅ Real execution - Actually runs optimization workflows
Codebase Understanding	❌ File reading	✅ Full RAG indexing - Deeply understands your project
Validation	❌ Syntax only	✅ DSPy-specific - Enforces signatures, modules, best practices
Workflow Automation	❌ Manual	✅ Complete automation - End-to-end workflows from /init to /export
MCP Integration	❌ None	✅ Built-in client - Connect to external tools seamlessly
Templates	❌ None	✅ 20+ templates - Pre-built patterns for RAG, QA, classification

Real-World Impact

Learning DSPy:

• Generic AI: Hours of reading docs, piecing together concepts
• DSPy Code: Ask "What is ChainOfThought?" → Get comprehensive answer with examples instantly

Building a RAG System:

• Generic AI: Days of manual setup, configuration, testing
• DSPy Code: /init → "Create a RAG system" → /validate → /optimize → Done in hours

Optimizing Code:

• Generic AI: Manual GEPA setup, metric functions, data formatting
• DSPy Code: /optimize my_program.py → Automated workflow with progress tracking

The Bottom Line

DSPy Code is a purpose-built development environment that embeds DSPy expertise into every interaction, automates tedious workflows, and accelerates your development from hours to minutes.

🔄 Two Core Workflows

Workflow 1: Develop DSPy Applications

From idea to working code in minutes:

1. Start - /init to create or scan your project
2. Describe - Tell DSPy Code what you want in natural language
3. Generate - Get working DSPy code (signatures, modules, programs)
4. Validate - Ensure code follows DSPy best practices
5. Iterate - Refine and improve with interactive Q&A

Example:

dspy-code
/init
→ "Create a sentiment analyzer for customer reviews"
/validate

Workflow 2: Optimize with GEPA

From working code to production-ready in hours:

1. Prepare - Have your DSPy program ready
2. Generate Data - Create training examples with /data
3. Optimize - Run GEPA optimization with /optimize
4. Evaluate - Test performance improvements
5. Deploy - Export optimized, production-ready code

Example:

dspy-code
/data sentiment 20  # Generate 20 training examples
/optimize my_program.py  # Run GEPA optimization
/eval  # Evaluate performance
/export  # Package for deployment

The Complete Journey

┌─────────────────────────────────────────────────────────┐
│  Development Phase                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │   Init   │→ │  Generate │→ │ Validate │            │
│  └──────────┘  └──────────┘  └──────────┘            │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  Optimization Phase                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │   Data   │→ │ Optimize  │→ │  Deploy  │            │
│  └──────────┘  └──────────┘  └──────────┘            │
└─────────────────────────────────────────────────────────┘

Result: Production-ready DSPy applications with optimized performance

💻 Code Examples

Example 1: Creating a Sentiment Analyzer

dspy-code
/init
/model  # Interactive model selection (or use /connect ollama llama3.1:8b)
→ Create a sentiment analyzer that takes text and outputs positive or negative
/save sentiment.py
/validate
/run

Result: Complete, validated sentiment analyzer in minutes!

Example 2: GEPA Optimization Workflow

dspy-code
/init
→ Generate 50 examples for sentiment analysis
/optimize sentiment_analyzer.py training_data.jsonl
/optimize-status
/eval
/export

Result: Optimized program with improved accuracy

Example 3: Building a RAG System with MCP

dspy-code
/init
/mcp-connect filesystem
→ Create a RAG system that uses MCP to read documents and answer questions
/save rag_system.py
/validate

Result: Production-ready RAG system with external tool integration!

---

🎯 Key Features

🏗️ Development Features

• 🗣️ Natural Language Interface - Describe your DSPy task in plain English
• 🧠 Version-Aware Intelligence - Adapts to your installed DSPy version
• 📚 Codebase RAG - Understands your project with intelligent indexing
• ✅ Smart Validation - Ensures code follows DSPy best practices
• 🚀 Code Generation - Generate signatures, modules, and complete programs
• 🔗 Built-in MCP Client - Connect to any MCP server for external tools
• 📋 20+ Templates - Pre-built patterns for RAG, QA, classification

🧬 Optimization Features

• 🧬 GEPA Optimization - Real Genetic Pareto integration
• 📊 Automated Metrics - Built-in evaluation (Accuracy, F1, ROUGE, BLEU)
• 🔄 Prompt Evolution - Automatically improve instructions and examples
• 📈 Performance Tracking - Monitor optimization progress in real-time
• 💾 Session Management - Save and resume optimization workflows
• 🎯 Production Ready - Export optimized code for deployment
• 📦 Export/Import - Package and share optimized DSPy projects

---

🆕 What's New

Latest Release (v0.1.1)

• ✨ UV Support: Full support for uv as an alternative to python -m venv for creating virtual environments (recommended for faster setup)
• ⚡ Performance Toggles: New /fast-mode [on|off], /disable-rag, and /enable-rag commands for controlling RAG indexing and response speed
• 🔍 Venv Detection: Automatic detection of virtual environment in project root with startup warnings if missing

View Full Changelog: CHANGELOG.md

🚀 Quick Start

Installation

⚠️ CRITICAL: Always create your virtual environment INSIDE your project directory!

✨ Always install the latest version for the best experience! ✨

📁 Step 1: Create a project directory

mkdir my-dspy-project
cd my-dspy-project

🐍 Step 2: Create virtual environment IN this directory (not elsewhere!)

Recommended: Using uv (faster)

uv venv

Or using standard Python:

python -m venv .venv

⚡ Step 3: Activate it

# For bash/zsh:
source .venv/bin/activate

# For fish shell:
source .venv/bin/activate.fish

# On Windows:
.venv\Scripts\activate

🚀 Step 4: Install latest dspy-code (always upgrade to get newest features!)

Recommended: Using uv (faster)

uv pip install --upgrade dspy-code

Or using pip:

pip install --upgrade dspy-code

🎯 Step 5: Run dspy-code (everything stays in this directory!)

dspy-code

💡 Pro Tip: Always use pip install --upgrade dspy-code to get the latest features, bug fixes, and improvements!

Why virtual environment IN your project directory?

• 🔒 Security: All file scanning stays within your project directory
• 📦 Isolation: Your project dependencies are self-contained
• 🚀 Portability: Share your project by zipping the entire directory
• 🎯 Simplicity: Everything in one place - no scattered files
• 🧹 Clean: Delete the project folder to remove everything

Project Structure

When you follow this setup, your project will be fully self-contained:

my-dspy-project/          # Your CWD
├── .venv/                # Virtual environment (packages installed here)
├── .dspy_cache/          # DSPy's LLM response cache
├── .dspy_code/           # dspy-code's internal data
│   ├── cache/            # RAG index cache
│   ├── sessions/         # Session state
│   ├── optimization/     # GEPA workflow data
│   └── history.txt       # Command history
├── generated/            # Your generated code
├── modules/              # Your modules
├── signatures/           # Your signatures
└── dspy_config.yaml      # Your config

Everything in one directory! Delete the folder, and it's all gone. Zip it, and share with others.

Never run dspy-code from:

• ❌ Your home directory (~/)
• ❌ Desktop, Documents, Downloads, or Pictures folders
• ❌ System directories
• ❌ With a virtual environment outside your project

Never do this:

# ❌ DON'T: Virtual env outside project
cd ~/
python -m venv my_global_venv

Your First Program (5 minutes)

# From your project directory with activated venv:
dspy-code

# Initialize your project (creates config and scans your environment)
/init

# Connect to a model (interactive selection recommended)
/model
# Or connect directly: /connect ollama llama3.1:8b

# Generate your first program using natural language
Create a sentiment analyzer that takes text and outputs positive or negative

# Save the generated code
/save sentiment.py

# Validate and run
/validate
/run

That's it! You just created, validated, and ran your first DSPy program. 🎉

📋 Available Commands

DSPy Code is interactive-only - all commands are slash commands. Here are the main categories:

🏁 Getting Started

• /init - Initialize or scan your DSPy project
• /intro - Show introduction and getting started guide
• /help - Show all available commands
• /exit - Exit the interactive session

🤖 Model Connection

• /connect <provider> <model> - Connect to LLM (ollama, openai, anthropic, gemini)
• /disconnect - Disconnect current model
• /models - List available models
• /status - Show current connection status

💻 Code Generation & Management

• /demo - Generate demo DSPy code
• /save <filename> - Save generated code to file
• /validate - Validate DSPy code
• /run - Execute your DSPy program
• /test - Run tests on your code

🧬 Optimization

• /optimize - Start optimization workflow
• /optimize-start - Begin GEPA optimization
• /optimize-status - Check optimization progress
• /optimize-cancel - Cancel running optimization
• /optimize-resume - Resume paused optimization
• /eval - Evaluate your DSPy program

🔗 MCP Integration

• /mcp-connect <server> - Connect to MCP server
• /mcp-disconnect <server> - Disconnect MCP server
• /mcp-servers - List configured MCP servers
• /mcp-tools - Show available MCP tools
• /mcp-call <tool> <args> - Call an MCP tool
• /mcp-resources - List MCP resources
• /mcp-read <resource> - Read MCP resource
• /mcp-prompts - List MCP prompts
• /mcp-prompt <name> - Get MCP prompt

💾 Session Management

• /sessions - List all saved sessions
• /session <name> - Load or switch session

📦 Export & Import

• /export <path> - Export project as package
• /import <path> - Import project package

📚 Reference & Examples

• /reference <topic> - Get DSPy reference documentation
• /examples - Show example DSPy programs
• /predictors - Show available DSPy predictors
• /adapters - Show DSPy adapters
• /retrievers - Show DSPy retrievers
• /async - Show async patterns
• /streaming - Show streaming examples
• /data - Show data handling examples
• /explain <concept> - Explain DSPy concepts

🔧 Project Management

• /project - Show project information
• /refresh-index - Rebuild codebase index
• /index-status - Show index status
• /save-data - Save training/evaluation data

🗂️ History & Context

• /history - Show conversation history
• /clear - Clear current context

💡 Primary Use Cases

1. 🏗️ Developing New DSPy Applications

Perfect for:

• Building new AI applications from scratch
• Prototyping ideas quickly
• Learning DSPy fundamentals

dspy-code
/init
/model  # Interactive model selection (or use /connect directly)
Create a RAG system for document Q&A
/save rag_system.py
/validate

✅ Complete project structure
✅ Code generation with natural language
✅ Validation & best practices
✅ Ready to code in minutes

2. 🧬 Optimizing Existing DSPy Programs with GEPA

Perfect for:

• Improving accuracy of existing programs
• Automatic prompt engineering
• Production optimization

dspy-code
/init
/data sentiment 20  # Generate training examples
/optimize my_program.py training_data.jsonl
/optimize-status
/eval

✅ Real GEPA execution (not just code generation)
✅ Automated metric functions
✅ Progress tracking & resumption
✅ Production-ready optimized code
✅ Performance improvements documented

3. 📚 Learning DSPy (No Docs Required!)

Perfect for:

• First time using DSPy
• Understanding DSPy concepts
• Exploring different patterns

dspy-code
/intro
/examples
/explain ChainOfThought
/predictors

Just ask questions in natural language - the CLI answers using YOUR installed DSPy version!

4. 🔗 Using MCP for External Tools

Perfect for:

• Connecting to external APIs and services
• Building powerful, connected AI applications

dspy-code
/mcp-connect filesystem
/mcp-tools
/mcp-call read_file {"path": "data.json"}

🔌 Model Connection

Connect to any LLM provider. The easiest way is to use the interactive /model command:

# Recommended: Interactive model selection
/model

This will guide you through:

• Picking a provider (Ollama, OpenAI, Anthropic, Gemini)
• Choosing a model (for Ollama we auto-list local models; for cloud providers you can type the model name)

Alternative: Direct connection with /connect

If you prefer to connect directly without the interactive prompt:

# Ollama (local, free)
/connect ollama llama3.1:8b

# OpenAI
/connect openai gpt-4o

# Anthropic (requires API key)
/connect anthropic claude-sonnet-4-5

# Google Gemini
/connect gemini gemini-2.0-flash-exp

API Keys Required (for cloud providers):

Make sure the right API keys are set in your environment before starting dspy-code:

• OpenAI: OPENAI_API_KEY
• Anthropic: ANTHROPIC_API_KEY
• Gemini: GEMINI_API_KEY

💡 Tip: Use /model for the easiest experience - it guides you through everything interactively. For automation or scripts, use /connect directly. Check your provider docs for the latest model names.

🧬 GEPA Optimization

DSPy Code includes real GEPA (Genetic Pareto) optimization:

# Start optimization workflow
/optimize my_program.py training_data.jsonl

# Or use step-by-step optimization
/optimize-start my_program.py training_data.jsonl
/optimize-status
/optimize-resume

📋 Requirements

• Python: 3.10 or higher
• DSPy: 3.0.4 or higher (automatically installed)
• Dependencies: All dependencies are automatically installed

🛠️ Installation Options

With uv (Recommended - Faster)

✨ Always install the latest version! ✨

uv pip install --upgrade dspy-code

💡 Why uv? uv is significantly faster than pip and is now the recommended installation method. Always use --upgrade to get the latest features, bug fixes, and improvements!

With pip (Alternative)

pip install --upgrade dspy-code

From Source

git clone https://github.com/SuperagenticAI/dspy-code.git
cd dspy-code
pip install -e .

Optional: Install with Model Provider Extras

For cloud providers, install optional dependencies:

# OpenAI support
pip install --upgrade "dspy-code[openai]"

# Anthropic support
pip install --upgrade "dspy-code[anthropic]"

# Gemini support
pip install --upgrade "dspy-code[gemini]"

# All providers
pip install --upgrade "dspy-code[llm-all]"

🏗️ Architecture

DSPy Code is built with a modular architecture:

• Commands - Interactive slash commands
• Models - LLM connection and code generation
• MCP - Model Context Protocol client
• Optimization - GEPA workflow management
• Validation - Code quality and best practices
• RAG - Codebase indexing and search
• Execution - Sandboxed code execution
• Session - State management
• Export - Project packaging

📚 Documentation

Full documentation available at: https://superagenticai.github.io/dspy-code/

Quick Links

• 📦 Installation Guide
• ⚡ Quick Start
• 💬 Interactive Mode
• ⌨️ Slash Commands
• 🔗 MCP Integration
• 🎯 Optimization Guide

---

🆘 Need Help?

• 🐛 Report a Bug - Found an issue? Let us know!
• 💬 Ask a Question - Need help? Start a discussion!
• 📖 Full Documentation - Complete guides and reference
• ❓ FAQ - Common questions answered
• 🔧 Troubleshooting - Fix common issues

🤝 Contributing

Contributions are welcome! We're building DSPy Code for the community, and your help makes it better.

We follow modern Python best practices:

• Code Quality: Ruff for linting and formatting
• Testing: pytest with coverage
• CI/CD: GitHub Actions
• Pre-commit: Automated quality checks

First time contributing? Check out our Contributing Guide for detailed guidelines and best practices.

Quick Development Setup

git clone https://github.com/SuperagenticAI/dspy-code.git
cd dspy-code

# Using uv (recommended)
uv venv
source .venv/bin/activate  # For fish: source .venv/bin/activate.fish
uv pip install -e ".[dev,test,docs]"
pre-commit install

# Or using pip
python -m venv .venv
source .venv/bin/activate  # For fish: source .venv/bin/activate.fish
pip install -e ".[dev,test,docs]"
pre-commit install

# Run tests
pytest

# Run linting
ruff check .

# Format code
ruff format .

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🗺️ Roadmap

Coming Soon

• Plan / Code modes in interactive CLI (explicit "planning" vs "coding" flows for complex tasks)
• Open-source model support via third-party providers (OpenRouter, Groq and similar gateways)
• Improved intent routing to further reduce/eliminate duplicate code generation

View planned features and contribute: GitHub Issues

---

⚠️ Development Status

DSPy Code is currently in Beta and under active development. While it's functional and ready for experimentation, it's not yet production-ready. We're actively adding features to make it production-worthy so you can use it in real projects to enhance your workflow.

We'd love your feedback! Try it out, share your experience, and help us shape the future of DSPy development:

• 🐛 Report issues
• ⭐ Star the repo to show your support

🌟 Show Support

Show your support for DSPy Code!

• ⭐ Star us on GitHub - Help others discover DSPy Code
• 🐛 Report Issues - Found a bug? Let us know!
• 💡 Request Features - Have an idea? Share it!
• 🤝 Contribute - Help make DSPy Code better
• 📢 Share - Tell others about DSPy Code

Your support helps us build better tools for the DSPy Code!

---

🙏 Acknowledgments

Brought to you by Superagentic AI

Special thanks to the DSPy community and awesome GEPA project and all contributors so far!

---

📚 Resources

📖 Documentation • 🐛 Issues • 🤝 Contributing

---

---

Made for the DSPy community