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.

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

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.

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.

• 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.

# 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

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

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

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.

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