Quickstart¶

This guide will walk you through the basics of setting up and using dspy-profiles.

Requirements¶

• Python 3.12+
• DSPy 3.0+ (installed as a dependency where needed)

If you plan to build docs or run tests locally, install the dev tools listed in pyproject.toml using uv sync --all-extras --group dev.

1. Installation¶

First, install the package from PyPI:

2. Core Concepts¶

A profile is a named collection of settings for DSPy. It can define:

• A Language Model (lm)
• A Retrieval Model (rm)
• Global settings (e.g., cache_dir, retries)

Profiles are stored in a profiles.toml file. dspy-profiles locates this file with a clear, git-like precedence:

1. Environment Variable: Set DSPY_PROFILES_PATH to point to a specific configuration file.
2. Project-Specific File: Search for a profiles.toml in the current directory and its parent directories.
3. Global File: If neither of the above is found, it falls back to the global default at ~/.dspy/profiles.toml.

By default, the init command will create or edit the global file.

Note: Environment variables are automatically loaded from a local .env file when present. You can also import a profile directly from a .env file using dspy-profiles import --profile <name> --from .env.

Profile Inheritance¶

Profiles can inherit and extend other profiles using the extends key. This allows you to create a base configuration and then create specialized variations without repeating yourself.

For example, you could have a base profile with common settings, and dev and prod profiles that extend it but use different language models.

graph TD
    A[base] --> B[dev];
    A --> C[prod];
    subgraph profiles.toml
        B --> D{lm: gpt-4o-mini};
        C --> E{lm: gpt-4-turbo};
    end

3. Initialize Your First Profile¶

The easiest way to get started is with the interactive init command. This will create a default profile for you.

This command will ask for the language model, and optionally, your API key and an API base. It will then create the configuration file at ~/.dspy/profiles.toml.

4. View Your Profile¶

You can view the contents of any profile with the show command:

5. Using Profiles in Your Code¶

dspy-profiles provides multiple ways to activate a profile, catering to different use cases.

import dspy
from dspy_profiles import profile

# DSPy settings are configured automatically within this block
with profile("default"):
    predictor = dspy.Predict("question -> answer")
    result = predictor(question="What is the color of the sky?")
    print(result.answer)

import dspy
from dspy_profiles import with_profile

@with_profile("default")
def my_dspy_program(question):
    predictor = dspy.Predict("question -> answer")
    return predictor(question=question)

result = my_dspy_program("What is the capital of Spain?")
print(result.answer)

# my_script.py
import dspy

# This script is clean. No dspy-profiles code is needed.
predictor = dspy.Predict("question -> answer")
result = predictor(question="What is the capital of Spain?")
print(f"The capital of Spain is {result.answer}.")

6. Next Steps¶

You've now learned the basics of dspy-profiles. From here, you can:

• Explore the CLI Reference to see all available commands.
• Dive into the API Reference for advanced usage.
• Learn about creating more complex profiles with inheritance.