dspy-code 0.0.4

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 • 🚀 Quick Start • 💡 Examples • 🤝 Contributing

---

⚡ Claude Code for DSPy

🚀 Get Started in 30 Seconds

✨ Always install the latest version for best experience ✨

pip install --upgrade dspy-code
dspy-code

Develop DSPy Code → 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?

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?

Generic AI Assistants	DSPy Code
📖 Generic coding help	🎓 DSPy-Native Intelligence - Built-in knowledge of all 10 predictors, 11 optimizers, 4 adapters, and DSPy patterns
🔄 Unaware of your setup	📦 Version-Aware - Indexes YOUR installed DSPy version and generates compatible code
💭 Code suggestions only	🧬 Real GEPA Execution - Actually runs optimization workflows, not just code generation
📁 Basic file reading	📚 Codebase RAG - Deeply understands your entire project structure and patterns
✏️ Syntax checking	✅ DSPy Validation - Enforces signatures, modules, predictors, and best practices
🤷 Generic workflows	⚙️ Complete Automation - End-to-end workflows from /init to /export
🔌 No tool integration	🔗 MCP Client Built-in - Connect to external tools and services seamlessly
📝 Start from scratch	📋 20+ Templates - Pre-built patterns for RAG, QA, classification, and more

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

🎯 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

🚀 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!)

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!)

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

# ❌ DON'T: System-wide installation
pip install dspy-code

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 (example with Ollama)
/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
/connect ollama llama3.1:8b
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

Real results: 75% → 92% accuracy automatically!

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:

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

# OpenAI
/connect openai gpt-4

# Anthropic
/connect anthropic claude-3-5-sonnet-20241022

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

🧬 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

From PyPI (Recommended)

✨ Always install the latest version! ✨

pip install --upgrade dspy-code

💡 Why upgrade? We're actively developing and releasing new features, bug fixes, and improvements regularly. Always use --upgrade to get the best experience!

From Source

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

With uv (Faster)

# Always get the latest version
uv pip install --upgrade dspy-code

🏗️ 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

🤝 Contributing

Contributions are welcome! 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

See CONTRIBUTING.md for detailed guidelines.

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.

⚠️ 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

🙏 Acknowledgments

Built with ❤️ by Superagentic AI

Special thanks to the DSPy community and all contributors!

---

📚 Resources

📖 Documentation • 🐛 Issues • 🤝 Contributing

---

⭐ Show Your Support

If DSPy Code helps your workflow, give us a star! ⭐

It helps others discover the project and motivates us to keep improving it.

---

Made with 💜 for the DSPy community