ooai_llm.dspy

Optional DSPy model integration.

Purpose:

Create DSPy LM instances from the same model strings, serializable profiles, and runtime identity used by the LangChain-first OOAI surface.

Design:

• Keep DSPy optional and lazily imported.

• Resolve all model choices to LiteLLM-style provider/model strings, which is DSPy’s constructor shape.

• Expose only model-substrate helpers here. DSPy programs, runnables, LangGraph nodes, optimizers, and artifacts belong in ooai-agents.

Examples

>>> config = DSPyLMConfig(model="openai:gpt-5-mini", temperature=0)
>>> config.resolve_model_name()
'openai/gpt-5-mini'

Attributes

DSPyModelType

DSPy model protocol style passed to dspy.LM.

Exceptions

DSPyDependencyError

Raised when DSPy helpers are used without the optional dependency.

Classes

DSPyLMConfig	Serializable configuration for creating a DSPy LM.
CreatedDSPyLMBundle	DSPy LM plus resolved OOAI metadata.

Functions

resolve_dspy_model_name(→ str)	Resolve a model choice to DSPy's LiteLLM-style model name.
create_dspy_lm(→ Any)	Create a native DSPy LM from OOAI config.
create_dspy_lm_bundle(→ CreatedDSPyLMBundle)	Create a DSPy LM and return resolved OOAI metadata with it.
configure_dspy_lm(→ Any)	Create a DSPy LM, configure DSPy's global settings, and return it.
extract_dspy_usage(→ dict[str, Any] | None)	Extract normalized token usage from a DSPy prediction or LM object.
build_dspy_usage_event(...)	Build a usage event from a DSPy prediction when usage is available.
record_dspy_usage(→ ooai_llm.callbacks.UsageEvent | None)	Record DSPy prediction usage when the prediction exposes counts.

Module Contents

ooai_llm.dspy.DSPyModelType

DSPy model protocol style passed to dspy.LM.

exception ooai_llm.dspy.DSPyDependencyError

Bases: ImportError

Raised when DSPy helpers are used without the optional dependency.

class ooai_llm.dspy.DSPyLMConfig(/, **data: Any)

Bases: pydantic.BaseModel

Serializable configuration for creating a DSPy LM.

Parameters:

• model – Explicit OOAI model string, such as "openai:gpt-5-mini".

• alias – Optional configured model alias when model is omitted.

• provider – Optional provider for alias/preset resolution.

• preset – Provider preset name when resolving by provider.

• model_type – DSPy LM type: "chat", "text", or "responses".

• lm_kwargs – DSPy/LiteLLM passthrough kwargs for provider-specific needs.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model: str | None = None

alias: ooai_llm.settings.ModelAliasName | None = None

provider: str | ooai_llm.providers.Provider | None = None

preset: ooai_llm.settings.ModelPresetName = 'default'

model_type: DSPyModelType = 'chat'

temperature: float | None = None

max_tokens: int | None = None

top_p: float | None = None

frequency_penalty: float | None = None

presence_penalty: float | None = None

seed: int | None = None

stop: str | list[str] | None = None

cache: bool | None = None

callbacks: list[Any] = None

num_retries: int | None = None

timeout: float | None = None

parallel_tool_calls: bool | None = None

reasoning: ooai_llm.reasoning.ReasoningInput = None

finetuning_model: str | None = None

launch_kwargs: dict[str, Any] | None = None

train_kwargs: dict[str, Any] | None = None

use_developer_role: bool | None = None

lm_kwargs: dict[str, Any] = None

auto_refresh_models: bool | None = None

force_model_refresh: bool = False

runtime_id: str | None = None

runtime_uuid: uuid.UUID | str | None = None

profile_id: str | None = None

tags: list[str] = None

metadata: dict[str, Any] = None

cost_labels: dict[str, str] = None

classmethod from_profile(profile: ooai_llm.profiles.ChatModelProfile, *, model_type: DSPyModelType = 'chat') → DSPyLMConfig

Build a DSPy config from a serializable chat-model profile.

classmethod from_runtime(runtime: ooai_llm.profiles.LLM, *, model_type: DSPyModelType = 'chat') → DSPyLMConfig

Build a DSPy config from an LLM runtime.

resolve_model_string(*, settings: ooai_llm.settings.AppSettings | None = None) → ooai_llm.types.ModelString

Resolve this config to an OOAI model string.

resolve_model_name(*, settings: ooai_llm.settings.AppSettings | None = None) → str

Resolve this config to DSPy’s LiteLLM-style model name.

trace_metadata(*, model: ooai_llm.types.ModelString | None = None, settings: ooai_llm.settings.AppSettings | None = None) → dict[str, Any]

Return JSON-safe runtime/model metadata for downstream wrappers.

to_lm_kwargs(*, settings: ooai_llm.settings.AppSettings | None = None) → dict[str, Any]

Return keyword arguments for dspy.LM.

class ooai_llm.dspy.CreatedDSPyLMBundle

DSPy LM plus resolved OOAI metadata.

model: ooai_llm.types.ModelString

lm: Any

metadata: ooai_llm.metadata.ModelInfo

config: DSPyLMConfig

trace_metadata: dict[str, Any]

ooai_llm.dspy.resolve_dspy_model_name(model: str | ooai_llm.types.ModelString | None = None, *, settings: ooai_llm.settings.AppSettings | None = None, alias: ooai_llm.settings.ModelAliasName | None = None, provider: ooai_llm.providers.Provider | str | None = None, preset: ooai_llm.settings.ModelPresetName = 'default', auto_refresh_models: bool | None = None, force_model_refresh: bool = False) → str

Resolve a model choice to DSPy’s LiteLLM-style model name.

ooai_llm.dspy.create_dspy_lm(config: ooai_llm.profiles.ChatModelProfile | DSPyLMConfig | ooai_llm.profiles.LLM | str | ooai_llm.types.ModelString | None = None, *, settings: ooai_llm.settings.AppSettings | None = None, **kwargs: Any) → Any

Create a native DSPy LM from OOAI config.

Unknown keyword arguments are passed through to dspy.LM via DSPyLMConfig.lm_kwargs.

ooai_llm.dspy.create_dspy_lm_bundle(config: ooai_llm.profiles.ChatModelProfile | DSPyLMConfig | ooai_llm.profiles.LLM | str | ooai_llm.types.ModelString | None = None, *, settings: ooai_llm.settings.AppSettings | None = None, **kwargs: Any) → CreatedDSPyLMBundle

Create a DSPy LM and return resolved OOAI metadata with it.

ooai_llm.dspy.configure_dspy_lm(config: ooai_llm.profiles.ChatModelProfile | DSPyLMConfig | ooai_llm.profiles.LLM | str | ooai_llm.types.ModelString | None = None, *, settings: ooai_llm.settings.AppSettings | None = None, configure_kwargs: collections.abc.Mapping[str, Any] | None = None, **kwargs: Any) → Any

Create a DSPy LM, configure DSPy’s global settings, and return it.

ooai_llm.dspy.extract_dspy_usage(value: Any) → dict[str, Any] | None

Extract normalized token usage from a DSPy prediction or LM object.

ooai_llm.dspy.build_dspy_usage_event(*, prediction: Any, model: str | ooai_llm.types.ModelString, settings: ooai_llm.settings.AppSettings | None = None, budget: ooai_llm.callbacks.BudgetPolicy | None = None, profile: collections.abc.Mapping[str, Any] | None = None, run_name: str | None = None, tags: list[str] | tuple[str, Ellipsis] | None = None, metadata: collections.abc.Mapping[str, Any] | None = None, cost_labels: collections.abc.Mapping[str, str] | None = None) → ooai_llm.callbacks.UsageEvent | None

Build a usage event from a DSPy prediction when usage is available.

ooai_llm.dspy.record_dspy_usage(recorder: ooai_llm.callbacks.UsageRecorder, *, prediction: Any, model: str | ooai_llm.types.ModelString, settings: ooai_llm.settings.AppSettings | None = None, budget: ooai_llm.callbacks.BudgetPolicy | None = None, profile: collections.abc.Mapping[str, Any] | None = None, run_name: str | None = None, tags: list[str] | tuple[str, Ellipsis] | None = None, metadata: collections.abc.Mapping[str, Any] | None = None, cost_labels: collections.abc.Mapping[str, str] | None = None) → ooai_llm.callbacks.UsageEvent | None

Record DSPy prediction usage when the prediction exposes counts.