dspy-profiles 0.4.0

Awesome profiles support for D

DSPy Profiles

A companion tool for the DSPy framework to manage configuration profiles, inspired by the AWS CLI and Databricks.

dspy-profiles allows you to define, switch between, and manage different DSPy configurations for various environments (e.g., development, staging, production) without cluttering your code.

---

📘 Read the full documentation at nielsgl.github.io/dspy-profiles for installation, tutorials, CLI reference, and examples.

---

Requirements

• Python 3.12+
• DSPy 3.0+ (installed alongside your project)

---

The Problem

When working with DSPy, you often need to switch between different language models, retrieval models, and settings. Managing this directly in your code can be messy, error-prone, and insecure.

The Solution

dspy-profiles moves this configuration out of your code and into a simple profiles.toml file. It provides a powerful CLI and a clean Python API to manage and use these profiles seamlessly. The tool will automatically find your profiles.toml whether it's in your local project directory or in the global ~/.dspy/ folder.

---

Key Features

• Declarative Profiles: Define all your environment settings in a clear, human-readable TOML file.
• Powerful CLI: A rich command-line interface lets you manage your profiles without ever leaving the terminal.
• Seamless Python API: Activate profiles in your Python code with an elegant and intuitive API.
• Profile Inheritance: Create base profiles and extend them for different environments to avoid repetition.
• Environment Precedence: A clear and predictable activation logic ensures the right profile is always used.
• Validation & Testing: validate and test commands to ensure your profiles are correct and your models are reachable.

---

Installation

# With pip
pip install dspy-profiles

# With uv
uv add dspy-profiles

# Or run it directly without installation
uvx dspy-profiles --help

# Or as a tool in your cli
uv tool install dspy-profiles
dspy-profiles --help

Quickstart

1. Initialize a default profile interactively:

   dspy-profiles init
   

   This will prompt you for your language model and optionally your API key and API base.

2. Use it in your Python code:

   import dspy
   from dspy_profiles import profile
   
   with profile("default"):
       # Your DSPy code here, now using the settings from your 'default' profile.
       predictor = dspy.Predict("question -> answer")
       response = predictor(question="What is the capital of France?")
       print(response.answer)
   

3. Run any script with a profile, without changing your code:

   # The new, convenient way to run any script with a profile
   dspy-run my_script.py
   
   # Specify a different profile, or run non-python commands
   dspy-run --profile production -- pytest
   

---

Documentation

The documentation site contains tutorials, API/CLI references, examples, and release notes: https://nielsgl.github.io/dspy-profiles/

Quick links:

• CLI overview: https://nielsgl.github.io/dspy-profiles/cli-reference/
• dspy-run command: https://nielsgl.github.io/dspy-profiles/cli-run-reference/
• Configuration reference: https://nielsgl.github.io/dspy-profiles/config-reference/
• CI & testing guide: https://nielsgl.github.io/dspy-profiles/ci-testing/
• Project roadmap: ROADMAP.md
• Release notes: CHANGELOG.md

---

Project Status & Roadmap

The project is under active development. All core features are implemented and stable.

• [x] Phase 1: DX, Packaging & Documentation: Professional PyPI packaging, CI/CD, and a full documentation site.
• [x] Phase 2: Core CLI & Env Var Enhancements: import, diff, run, and robust activation precedence.
• [x] Phase 3: Advanced Profile Features: Profile composition (extends), inline overrides, and validate/test commands.
• [x] Phase 4: Python API & Runtime Utilities: Programmatic shortcuts like lm() and runtime introspection with current_profile().
• [x] Phase 5: Developer Experience Overhaul: A major refactor of the CLI, API, and documentation for clarity, stability, and ease of use.
• [x] Phase 6: QoL & Advanced Workflows: An interactive init wizard, profile import/export, and async-friendly decorators.

See the Project Overview for detailed specifications.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.