Metadata-Version: 2.4
Name: dspy-code
Version: 0.1.5
Summary: Claude Code for DSPy: AI-powered interactive development environment for DSPy
Project-URL: Homepage, https://github.com/SuperagenticAI/dspy-code
Project-URL: Documentation, https://superagenticai.github.io/dspy-code/
Project-URL: Repository, https://github.com/SuperagenticAI/dspy-code
Project-URL: Bug Tracker, https://github.com/SuperagenticAI/dspy-code/issues
Project-URL: Changelog, https://github.com/SuperagenticAI/dspy-code/blob/main/CHANGELOG.md
Author-email: Shashi Jagtap <shashi@super-agentic.ai>, Shashi Jagtap <shashikant.jagtap@icloud.com>
Maintainer-email: Shashi Jagtap <team@super-agentic.ai>, Shashi Jagtap <shashikant.jagtap@icloud.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,code,dspy,interactive,language-models,nlp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: anyio>=4.5
Requires-Dist: click>=8.0.0
Requires-Dist: dspy>=3.0.4
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx>=0.27.1
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: mcp>=1.2.1
Requires-Dist: packaging>=23.0
Requires-Dist: pydantic<3.0.0,>=2.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich<15.0.0,>=13.7.0
Provides-Extra: anthropic
Requires-Dist: anthropic<1.0.0,>=0.39.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai<2.0.0,>=1.52.0; extra == 'gemini'
Provides-Extra: llm-all
Requires-Dist: anthropic<1.0.0,>=0.39.0; extra == 'llm-all'
Requires-Dist: google-genai<2.0.0,>=1.52.0; extra == 'llm-all'
Requires-Dist: openai<3.0.0,>=2.8.1; extra == 'llm-all'
Provides-Extra: mcp-ws
Requires-Dist: websockets>=15.0.1; extra == 'mcp-ws'
Provides-Extra: openai
Requires-Dist: openai<3.0.0,>=2.8.1; extra == 'openai'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/SuperagenticAI/dspy-code/main/docs/resource/dspy-code.png" alt="DSPy Code Logo" width="140"/>

<br/>

<img src="https://raw.githubusercontent.com/SuperagenticAI/dspy-code/main/docs/resource/dspy-code-banner.png" alt="DSPy Code" width="600"/>

<br/>

<img src="https://raw.githubusercontent.com/SuperagenticAI/dspy-code/main/docs/resource/dspy-code-text.svg" alt="DSPy Code" width="400"/>

<br/>

### 🚀 Your AI-Powered DSPy Development & Optimization Assistant

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/dspy-code.svg)](https://badge.fury.io/py/dspy-code)
[![Beta](https://img.shields.io/badge/status-beta-orange.svg)](https://github.com/SuperagenticAI/dspy-code)
[![CI](https://github.com/SuperagenticAI/dspy-code/actions/workflows/ci.yml/badge.svg)](https://github.com/SuperagenticAI/dspy-code/actions/workflows/ci.yml)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

[📖 Documentation](https://superagenticai.github.io/dspy-code/) •
[🤝 Contributing](CONTRIBUTING.md)

</div>

---

## 🎯 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.

---

<div style="background: linear-gradient(135deg, rgba(147, 51, 234, 0.1) 0%, rgba(236, 72, 153, 0.1) 100%); padding: 1.5em; border-radius: 12px; margin: 1.5em 0; text-align: left;">

**📚 New to DSPy Code?** You have two options:
- **📖 View Full Documentation** - Comprehensive guides, tutorials, and reference at [superagenticai.github.io/dspy-code](https://superagenticai.github.io/dspy-code/)
- **⚡ Continue Reading Below** - Explore more sections in this README

**Choose what works best for you!** 👇

</div>

---

## 📑 Table of Contents

- [What is DSPy Code?](#-what-is-dspy-code) *(Overview above)*
- [What is DSPy Code? (Detailed)](#-what-is-dspy-code-detailed)
- [Why DSPy Code?](#-why-dspy-code)
- [Two Core Workflows](#-two-core-workflows)
- [Code Examples](#-code-examples)
- [Key Features](#-key-features)
- [What's New](#-whats-new)
- [Quick Start](#-quick-start)
- [Available Commands](#-available-commands)
- [Primary Use Cases](#-primary-use-cases)
- [Model Connection](#-model-connection)
- [GEPA Optimization](#-gepa-optimization)
- [Requirements](#-requirements)
- [Installation Options](#-installation-options)
- [Architecture](#-architecture)
- [Documentation](#-documentation)
- [Need Help?](#-need-help)
- [Contributing](#-contributing)
- [License](#-license)
- [Roadmap](#-roadmap)
- [Development Status](#-development-status)
- [Show Support](#-show-support)
- [Acknowledgments](#-acknowledgments)

---

### ⚡ Claude Code for DSPy

<div align="center">

**🚀 Get Started in 30 Seconds**

> ✨ Always install the latest version for best experience ✨

```bash
pip install --upgrade dspy-code
```

</div>

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

</div>

</div>

> **💡 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)

<div align="center">

**The Complete DSPy Development & Optimization Platform**

</div>

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:**
```bash
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:**
```bash
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

```bash
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

```bash
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

```bash
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](CHANGELOG.md)

## 🚀 Quick Start

### Installation

<div align="center">

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

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

</div>

<div style="background: linear-gradient(135deg, rgba(147, 51, 234, 0.1) 0%, rgba(236, 72, 153, 0.1) 100%); padding: 2em; border-radius: 12px; border-left: 4px solid #9333ea; margin: 1.5em 0;">

**📁 Step 1:** Create a project directory
```bash
mkdir my-dspy-project
cd my-dspy-project
```

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

**Recommended: Using `uv` (faster)**
```bash
uv venv
```

**Or using standard Python:**
```bash
python -m venv .venv
```

**⚡ Step 3:** Activate it
```bash
# 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)**
```bash
uv pip install --upgrade dspy-code
```

**Or using pip:**
```bash
pip install --upgrade dspy-code
```

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

</div>

<div align="center">

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

</div>

**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:**
```bash
# ❌ DON'T: Virtual env outside project
cd ~/
python -m venv my_global_venv


```

### Your First Program (5 minutes)

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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:**

```bash
# 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:

```bash
# 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:

```bash
# 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)

<div align="center">

<div style="background: linear-gradient(90deg, #9333ea, #ec4899, #f97316); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; font-size: 1.2em; font-weight: bold; margin: 1em 0;">

**✨ Always install the latest version! ✨**

</div>

</div>

<div style="background: rgba(147, 51, 234, 0.05); padding: 1.5em; border-radius: 10px; border: 2px dashed #9333ea; margin: 1em 0;">

```bash
uv pip install --upgrade dspy-code
```

</div>

<div align="center">

> 💡 **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!

</div>

### With pip (Alternative)

```bash
pip install --upgrade dspy-code
```

### From Source

```bash
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:

```bash
# 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/](https://superagenticai.github.io/dspy-code/)

### Quick Links

- [📦 Installation Guide](https://superagenticai.github.io/dspy-code/getting-started/installation/)
- [⚡ Quick Start](https://superagenticai.github.io/dspy-code/getting-started/quick-start/)
- [💬 Interactive Mode](https://superagenticai.github.io/dspy-code/guide/interactive-mode/)
- [⌨️ Slash Commands](https://superagenticai.github.io/dspy-code/guide/slash-commands/)
- [🔗 MCP Integration](https://superagenticai.github.io/dspy-code/advanced/mcp-integration/)
- [🎯 Optimization Guide](https://superagenticai.github.io/dspy-code/guide/optimization/)

---

## 🆘 Need Help?

- 🐛 [Report a Bug](https://github.com/SuperagenticAI/dspy-code/issues) - Found an issue? Let us know!
- 💬 [Ask a Question](https://github.com/SuperagenticAI/dspy-code/discussions) - Need help? Start a discussion!
- 📖 [Full Documentation](https://superagenticai.github.io/dspy-code/) - Complete guides and reference
- ❓ [FAQ](https://superagenticai.github.io/dspy-code/reference/faq/) - Common questions answered
- 🔧 [Troubleshooting](https://superagenticai.github.io/dspy-code/reference/troubleshooting/) - Fix common issues

## 🤝 Contributing

<div style="background: linear-gradient(135deg, rgba(147, 51, 234, 0.1) 0%, rgba(236, 72, 153, 0.1) 100%); padding: 2em; border-radius: 12px; border-left: 4px solid #9333ea; margin: 1.5em 0;">

**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](CONTRIBUTING.md) for detailed guidelines and best practices.

</div>

### Quick Development Setup

```bash
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](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](https://github.com/SuperagenticAI/dspy-code/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](https://github.com/SuperagenticAI/dspy-code/issues)
- ⭐ [Star the repo](https://github.com/SuperagenticAI/dspy-code) to show your support

## 🌟 Show Support

<div style="background: rgba(147, 51, 234, 0.05); padding: 2em; border-radius: 12px; margin: 2em 0;">

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

</div>

---

## 🙏 Acknowledgments

<div align="center">

Brought to you by **[Superagentic AI](https://super-agentic.ai)**

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

</div>

---

<div align="center">

### 📚 Resources

**[📖 Documentation](https://superagenticai.github.io/dspy-code/)** •
**[🐛 Issues](https://github.com/SuperagenticAI/dspy-code/issues)** •
**[🤝 Contributing](CONTRIBUTING.md)**

---

---

<img src="https://raw.githubusercontent.com/SuperagenticAI/dspy-code/main/docs/resource/dspy-code.png" alt="DSPy Code" width="100"/>

**Made for the DSPy community**

</div>
