Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

Add core language model types (#9786)

Maxime Rivestc827fed57da9
diff --git a/dspy/core/types.py b/dspy/core/types.py
new file mode 100644
index 000000000..06bd907db
--- /dev/null
+++ b/dspy/core/types.py
@@ -0,0 +1,1992 @@
+"""Normalized request, response, and stream types for DSPy language models."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from pprint import pformat
+from typing import Annotated, Any, Literal
+from urllib.parse import urlparse
+
+import pydantic
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class LMBasePart(BaseModel):
+ """A single content item in an LM message or output."""
+
+ type: str
+ metadata: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(extra="forbid")
+
+
+class LMSourcePart(LMBasePart):
+ """Content from exactly one provider-addressable source."""
+
+ media_type: str
+ data: str | None = None
+ url: str | None = None
+ file_id: str | None = None
+ path: str | None = None
+
+ @model_validator(mode="after")
+ def validate_one_source(self) -> LMSourcePart:
+ _validate_one_source(self)
+ return self
+
+
+class LMTextPart(LMBasePart):
+ """Text content."""
+
+ type: Literal["text"] = "text"
+ text: str
+
+
+class LMImagePart(LMSourcePart):
+ """Image content from data, a URL, a file ID, or a local path."""
+
+ type: Literal["image"] = "image"
+ media_type: str = "image/png"
+ detail: Literal["low", "high", "auto"] | None = None
+
+
+class LMAudioPart(LMSourcePart):
+ """Audio content from data, a URL, a file ID, or a local path."""
+
+ type: Literal["audio"] = "audio"
+ media_type: str = "audio/wav"
+
+
+class LMVideoPart(LMSourcePart):
+ """Video content from data, a URL, a file ID, or a local path."""
+
+ type: Literal["video"] = "video"
+ media_type: str = "video/mp4"
+
+
+class LMDocumentPart(LMBasePart):
+ """Semantic source/document content, optionally citation-enabled.
+
+ Documents are source material: text, PDFs, reports, contracts, or other
+ provider-addressable evidence that benefits from title/context/citation
+ semantics. Use `LMBinaryPart` for opaque attachments or arbitrary bytes.
+ """
+
+ type: Literal["document"] = "document"
+ media_type: str = "application/pdf"
+ data: str | None = None
+ url: str | None = None
+ file_id: str | None = None
+ path: str | None = None
+ source: dict[str, Any] | None = None
+ citations: dict[str, Any] = Field(default_factory=dict)
+ title: str | None = None
+ context: str | None = None
+
+ @model_validator(mode="after")
+ def validate_source(self) -> LMDocumentPart:
+ has_media_source = any(value is not None for value in (self.data, self.url, self.file_id, self.path))
+ if self.source is not None and has_media_source:
+ raise ValueError("LMDocumentPart accepts either source or one of data, url, file_id, or path, not both.")
+ if self.source is None:
+ _validate_one_source(self)
+ elif not self.source:
+ raise ValueError("LMDocumentPart.source must be non-empty when provided.")
+ return self
+
+
+class LMBinaryPart(LMSourcePart):
+ """Opaque binary content from data, a URL, a file ID, or a local path."""
+
+ type: Literal["binary"] = "binary"
+ media_type: str = "application/octet-stream"
+ filename: str | None = None
+
+
+class LMToolCallPart(LMBasePart):
+ """A model request to call a tool.
+
+ Use `dspy.ToolCall(...)` as a shorter public alias when constructing
+ assistant messages by hand.
+
+ Args:
+ id: Provider call ID, when the backend uses one.
+ name: Name of the tool to call.
+ args: JSON-like arguments for the tool.
+ provider_data: Raw provider fields to keep with the tool call.
+
+ Examples:
+ ```python
+ import dspy
+
+ assistant = dspy.Assistant(
+ dspy.ToolCall(
+ id="call_1",
+ name="search",
+ args={"query": "DSPy"},
+ )
+ )
+ ```
+ """
+
+ type: Literal["tool_call"] = "tool_call"
+ id: str | None = None
+ name: str
+ args: dict[str, Any] = Field(default_factory=dict)
+ provider_data: dict[str, Any] = Field(default_factory=dict)
+
+
+class LMToolResultPart(LMBasePart):
+ """A tool execution result sent back to a model."""
+
+ type: Literal["tool_result"] = "tool_result"
+ call_id: str | None = None
+ name: str | None = None
+ content: list[LMPart] = Field(default_factory=list)
+ is_error: bool = False
+ provider_data: dict[str, Any] = Field(default_factory=dict)
+
+ @model_validator(mode="before")
+ @classmethod
+ def normalize_content(cls, data: Any) -> Any:
+ if isinstance(data, dict) and "content" in data:
+ data = dict(data)
+ content = data["content"]
+ if content is None:
+ data["content"] = []
+ elif isinstance(content, list):
+ data["content"] = [_coerce_part(item) for item in content]
+ else:
+ data["content"] = [_coerce_part(content)]
+ return data
+
+
+class LMThinkingPart(LMBasePart):
+ """Reasoning or thinking content returned by a model."""
+
+ type: Literal["thinking"] = "thinking"
+ text: str
+ redacted: bool = False
+
+
+class LMCitationPart(LMBasePart):
+ """A source citation returned by a model."""
+
+ type: Literal["citation"] = "citation"
+ text: str | None = None
+ title: str | None = None
+ url: str | None = None
+ metadata: dict[str, Any] = Field(default_factory=dict)
+
+ @model_validator(mode="after")
+ def validate_has_content(self) -> LMCitationPart:
+ if self.text is None and self.title is None and self.url is None:
+ raise ValueError("LMCitationPart requires at least one of text, title, or url.")
+ return self
+
+
+class LMRefusalPart(LMBasePart):
+ """A model refusal."""
+
+ type: Literal["refusal"] = "refusal"
+ text: str
+
+
+LMPart = Annotated[
+ LMTextPart
+ | LMImagePart
+ | LMAudioPart
+ | LMVideoPart
+ | LMDocumentPart
+ | LMBinaryPart
+ | LMToolCallPart
+ | LMToolResultPart
+ | LMThinkingPart
+ | LMCitationPart
+ | LMRefusalPart,
+ Field(discriminator="type"),
+]
+
+
+class LMMessage(BaseModel):
+ """A role-attributed sequence of LM parts."""
+
+ role: str
+ parts: list[LMPart]
+ name: str | None = None
+ metadata: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(extra="forbid")
+
+ @model_validator(mode="before")
+ @classmethod
+ def normalize_parts(cls, data: Any) -> Any:
+ if isinstance(data, cls):
+ return data
+ if isinstance(data, dict):
+ data = dict(data)
+ if data.get("role") == "tool" and "parts" not in data:
+ content = data.pop("content", None)
+ call_id = data.pop("tool_call_id", None)
+ name = data.pop("name", None)
+ data["parts"] = [
+ LMToolResultPart(
+ call_id=call_id,
+ name=name,
+ content=_parts_from_openai_content(content),
+ )
+ ]
+ elif "parts" not in data:
+ parts = _parts_from_openai_content(data.pop("content", None)) if "content" in data else []
+ if "tool_calls" in data:
+ parts.extend(_tool_calls_from_openai(data.pop("tool_calls") or []))
+ data["parts"] = parts
+ else:
+ data["parts"] = [_coerce_part(part) for part in data["parts"]]
+ if "tool_calls" in data:
+ data["parts"].extend(_tool_calls_from_openai(data.pop("tool_calls") or []))
+ return data
+
+ @property
+ def text(self) -> str | None:
+ texts = [part.text for part in self.parts if isinstance(part, LMTextPart)]
+ return "".join(texts) if texts else None
+
+
+class LMToolSpec(BaseModel):
+ """Provider-independent schema for a tool available to an LM."""
+
+ type: Literal["function"] = "function"
+ name: str
+ description: str | None = None
+ parameters: dict[str, Any] = Field(default_factory=dict)
+ metadata: dict[str, Any] = Field(default_factory=dict)
+ provider_data: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(extra="forbid")
+
+
+class LMReasoningConfig(BaseModel):
+ """Reasoning controls for models with native reasoning support."""
+
+ effort: str | None = None
+ max_tokens: int | None = None
+ summary: str | None = None
+
+ model_config = ConfigDict(extra="forbid")
+
+ @classmethod
+ def from_value(cls, value: Any = None, **overrides: Any) -> LMReasoningConfig:
+ data = _config_data(value, str_field="effort")
+ if "reasoning_effort" in data and "effort" not in data:
+ data["effort"] = data.pop("reasoning_effort")
+ data.update({key: value for key, value in overrides.items() if value is not _MISSING})
+ return cls(**data)
+
+
+class LMToolChoice(BaseModel):
+ """Tool-choice controls for native tool-capable models."""
+
+ mode: Literal["auto", "required", "none"] = "auto"
+ # Tool names that are allowed for a model request.
+ allowed: list[str] | None = None
+ parallel: bool | None = None
+
+ model_config = ConfigDict(extra="forbid")
+
+ @classmethod
+ def from_value(cls, value: Any = None, **overrides: Any) -> LMToolChoice:
+ data = _config_data(value, str_field="mode")
+ if "parallel_tool_calls" in data and "parallel" not in data:
+ data["parallel"] = data.pop("parallel_tool_calls")
+ data.update({key: value for key, value in overrides.items() if value is not _MISSING})
+ return cls(**data)
+
+
+class LMCacheConfig(BaseModel):
+ """DSPy memoization cache controls for a normalized LM request.
+
+ This cache skips the provider call entirely when DSPy finds an exact
+ request match. Use `LMPromptCacheConfig` for provider-side prompt/token
+ caching that still sends the request to the provider.
+ """
+
+ enabled: bool | None = None
+ rollout_id: int | str | None = None
+
+ model_config = ConfigDict(extra="forbid")
+
+ @classmethod
+ def from_value(cls, value: Any = None, **overrides: Any) -> LMCacheConfig:
+ data = _config_data(value, bool_field="enabled")
+ data.update({key: value for key, value in overrides.items() if value is not _MISSING})
+ return cls(**data)
+
+
+class LMPromptCacheConfig(BaseModel):
+ """Provider-side prompt/token cache controls.
+
+ Prompt caching is not DSPy memoization. The provider call still happens,
+ but the backend may reuse cached prompt prefixes or KV state for lower
+ latency or lower input-token cost.
+ """
+
+ enabled: bool | None = None
+ key: str | None = None
+
+ model_config = ConfigDict(extra="forbid")
+
+ @classmethod
+ def from_value(cls, value: Any = None, **overrides: Any) -> LMPromptCacheConfig:
+ data = _config_data(value, bool_field="enabled")
+ if "prompt_cache_key" in data and "key" not in data:
+ data["key"] = data.pop("prompt_cache_key")
+ data.update({key: value for key, value in overrides.items() if value is not _MISSING})
+ return cls(**data)
+
+
+_MISSING = object()
+
+
+def _config_data(value: Any, *, str_field: str | None = None, bool_field: str | None = None) -> dict[str, Any]:
+ if value is None:
+ return {}
+ if isinstance(value, BaseModel):
+ return value.model_dump(exclude_none=True)
+ if isinstance(value, Mapping):
+ return dict(value)
+ if str_field is not None and isinstance(value, str):
+ return {str_field: value}
+ if bool_field is not None and isinstance(value, bool):
+ return {bool_field: value}
+ raise TypeError(f"Cannot convert {type(value)!r} to a config object.")
+
+
+# Keep existing `dspy.LM(...)` / `lm(...)` keyword aliases in the call compatibility path.
+_KNOWN_CONFIG_KEYS = {
+ "temperature",
+ "max_tokens",
+ "top_p",
+ "stop",
+ "n",
+ "logprobs",
+ "response_format",
+ "reasoning",
+ "reasoning_effort",
+ "tool_choice",
+ "parallel_tool_calls",
+ "cache",
+ "rollout_id",
+ "prompt_cache",
+ "prompt_cache_key",
+ "extensions",
+}
+
+
+def _split_config_kwargs(kwargs: Mapping[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+ data: dict[str, Any] = {}
+ extensions = dict(kwargs.get("extensions", {}) or {})
+
+ for key, value in kwargs.items():
+ if key == "extensions":
+ continue
+ if key in _KNOWN_CONFIG_KEYS:
+ data[key] = value
+ else:
+ extensions[key] = value
+ return data, extensions
+
+
+def _normalize_reasoning_config(data: dict[str, Any]) -> None:
+ if "reasoning_effort" in data:
+ effort = data.pop("reasoning_effort")
+ if data.get("reasoning") is not None or effort is not None:
+ data["reasoning"] = LMReasoningConfig.from_value(data.get("reasoning"), effort=effort)
+ elif "reasoning" in data and data["reasoning"] is not None:
+ data["reasoning"] = LMReasoningConfig.from_value(data["reasoning"])
+
+
+def _normalize_tool_choice_config(data: dict[str, Any]) -> None:
+ parallel = data.pop("parallel_tool_calls", _MISSING)
+ if data.get("tool_choice") is not None or parallel not in (_MISSING, None):
+ data["tool_choice"] = LMToolChoice.from_value(data.get("tool_choice"), parallel=parallel)
+
+
+def _normalize_cache_config(data: dict[str, Any]) -> None:
+ rollout_id = data.pop("rollout_id", _MISSING)
+ if data.get("cache") is not None or rollout_id not in (_MISSING, None):
+ data["cache"] = LMCacheConfig.from_value(data.get("cache"), rollout_id=rollout_id)
+
+
+def _normalize_prompt_cache_config(data: dict[str, Any]) -> None:
+ prompt_cache_key = data.pop("prompt_cache_key", _MISSING)
+ if data.get("prompt_cache") is not None or prompt_cache_key not in (_MISSING, None):
+ data["prompt_cache"] = LMPromptCacheConfig.from_value(data.get("prompt_cache"), key=prompt_cache_key)
+
+
+class LMConfig(BaseModel):
+ """Common generation controls for an LM request."""
+
+ temperature: float | None = None
+ max_tokens: int | None = None
+ top_p: float | None = None
+ stop: list[str] | None = None
+ n: int | None = None
+ logprobs: bool | int | None = None
+ response_format: Any | None = None
+ reasoning: LMReasoningConfig | None = None
+ tool_choice: LMToolChoice | None = None
+ cache: LMCacheConfig | None = None
+ prompt_cache: LMPromptCacheConfig | None = None
+ extensions: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+ @classmethod
+ def from_kwargs(cls, **kwargs: Any) -> LMConfig:
+ data, extensions = _split_config_kwargs(kwargs)
+ _normalize_reasoning_config(data)
+ _normalize_tool_choice_config(data)
+ _normalize_cache_config(data)
+ _normalize_prompt_cache_config(data)
+ data["extensions"] = extensions
+ return cls(**data)
+
+
+def _merge_lm_config(left: LMConfig | None, right: LMConfig | None) -> LMConfig | None:
+ if left is None:
+ return right
+ if right is None:
+ return left
+
+ data = left.model_dump()
+ right_data = right.model_dump(exclude_none=True)
+ for key in ("reasoning", "tool_choice", "cache", "prompt_cache"):
+ if key in right_data and isinstance(data.get(key), dict) and isinstance(right_data[key], dict):
+ right_data[key] = {**data[key], **right_data[key]}
+ extensions = {**left.extensions, **right.extensions}
+ data.update(right_data)
+ data["extensions"] = extensions
+ return LMConfig(**data)
+
+
+def _merge_config_overrides(config: LMConfig, kwargs: dict[str, Any]) -> LMConfig:
+ data = config.model_dump()
+ extensions = dict(config.extensions)
+
+ direct_keys = {
+ "temperature",
+ "max_tokens",
+ "top_p",
+ "stop",
+ "n",
+ "logprobs",
+ "response_format",
+ }
+ for key in direct_keys & kwargs.keys():
+ data[key] = kwargs[key]
+
+ if "reasoning" in kwargs or "reasoning_effort" in kwargs:
+ data["reasoning"] = LMReasoningConfig.from_value(
+ kwargs.get("reasoning", data.get("reasoning")),
+ effort=kwargs.get("reasoning_effort", _MISSING),
+ )
+
+ if "tool_choice" in kwargs or "parallel_tool_calls" in kwargs:
+ data["tool_choice"] = LMToolChoice.from_value(
+ kwargs.get("tool_choice", data.get("tool_choice")),
+ parallel=kwargs.get("parallel_tool_calls", _MISSING),
+ )
+
+ if "cache" in kwargs or "rollout_id" in kwargs:
+ data["cache"] = LMCacheConfig.from_value(
+ kwargs.get("cache", data.get("cache")),
+ rollout_id=kwargs.get("rollout_id", _MISSING),
+ )
+
+ if "prompt_cache" in kwargs or "prompt_cache_key" in kwargs:
+ data["prompt_cache"] = LMPromptCacheConfig.from_value(
+ kwargs.get("prompt_cache", data.get("prompt_cache")),
+ key=kwargs.get("prompt_cache_key", _MISSING),
+ )
+
+ if "extensions" in kwargs:
+ extra = kwargs["extensions"]
+ if extra is None:
+ extensions = {}
+ elif isinstance(extra, Mapping):
+ extensions.update(extra)
+ else:
+ raise TypeError("`extensions` override must be a mapping or None.")
+
+ handled = _KNOWN_CONFIG_KEYS
+ for key, value in kwargs.items():
+ if key not in handled:
+ extensions[key] = value
+ data["extensions"] = extensions
+ return LMConfig(**data)
+
+
+@dataclass
+class LMRequestPatch:
+ """A partial normalized LM request contributed while rendering a DSPy call.
+
+ `LMRequest` is the complete object a `LanguageModel` receives. A patch is
+ the smaller, composable unit that DSPy type strategies can contribute while
+ an adapter is still building that request: extra messages, extra parts,
+ native tools, native config, or signature fields that should be hidden from
+ the outer adapter's ordinary text/JSON/XML rendering.
+ """
+
+ messages: list[LMMessage] = dataclass_field(default_factory=list)
+ system_parts: list[LMPart] = dataclass_field(default_factory=list)
+ user_parts: list[LMPart] = dataclass_field(default_factory=list)
+ assistant_parts: list[LMPart] = dataclass_field(default_factory=list)
+ tools: list[LMToolSpec] = dataclass_field(default_factory=list)
+ config: LMConfig | None = None
+ delete_input_fields: tuple[str, ...] = ()
+ delete_output_fields: tuple[str, ...] = ()
+ metadata: dict[str, Any] = dataclass_field(default_factory=dict)
+
+ def merge(self, other: LMRequestPatch) -> LMRequestPatch:
+ """Return a new patch containing this patch followed by `other`."""
+ return LMRequestPatch(
+ messages=[*self.messages, *other.messages],
+ system_parts=[*self.system_parts, *other.system_parts],
+ user_parts=[*self.user_parts, *other.user_parts],
+ assistant_parts=[*self.assistant_parts, *other.assistant_parts],
+ tools=[*self.tools, *other.tools],
+ config=_merge_lm_config(self.config, other.config),
+ delete_input_fields=(*self.delete_input_fields, *other.delete_input_fields),
+ delete_output_fields=(*self.delete_output_fields, *other.delete_output_fields),
+ metadata={**self.metadata, **other.metadata},
+ )
+
+ def as_lm_kwargs(self) -> dict[str, Any]:
+ """Return the legacy kwargs implied by this patch.
+
+ This keeps the first implementation usable with today's adapter call
+ path, which still passes `lm_kwargs` rather than an `LMRequestPatch` all
+ the way down. Message and part patches are intentionally not flattened
+ here; they require the next adapter-call refactor.
+ """
+ kwargs = self.config.model_dump(exclude_none=True) if self.config is not None else {}
+ extensions = kwargs.pop("extensions", {}) or {}
+ kwargs = {**extensions, **kwargs}
+ if self.tools:
+ kwargs["tools"] = list(self.tools)
+ return kwargs
+
+
+class LMRequest(BaseModel):
+ """A normalized request passed to a `LanguageModel`."""
+
+ model: str
+ messages: list[LMMessage]
+ tools: list[LMToolSpec] = Field(default_factory=list)
+ config: LMConfig = Field(default_factory=LMConfig)
+ metadata: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+ @classmethod
+ def from_call(
+ cls,
+ *,
+ model: str,
+ items: tuple[Any, ...] = (),
+ prompt: str | None = None,
+ messages: list[dict[str, Any] | LMMessage] | None = None,
+ tools: list[Any] | None = None,
+ **kwargs: Any,
+ ) -> LMRequest:
+ if messages is not None and (items or prompt is not None):
+ raise ValueError("Pass messages or direct-call inputs, not both.")
+
+ collected_tools: list[Any] = list(tools or [])
+ if messages is not None:
+ normalized_messages = [_coerce_message(message) for message in messages]
+ else:
+ normalized_messages, positional_tools = _messages_from_items(items, prompt=prompt)
+ collected_tools.extend(positional_tools)
+
+ config = LMConfig.from_kwargs(**kwargs)
+ return cls(
+ model=model,
+ messages=normalized_messages,
+ tools=[_coerce_tool_spec(tool) for tool in collected_tools],
+ config=config,
+ )
+
+ @classmethod
+ def from_prompt_or_messages(
+ cls,
+ *,
+ model: str,
+ prompt: str | None = None,
+ messages: list[dict[str, Any] | LMMessage] | None = None,
+ **kwargs: Any,
+ ) -> LMRequest:
+ return cls.from_call(model=model, prompt=prompt, messages=messages, **kwargs)
+
+ def with_config_overrides(self, **kwargs: Any) -> LMRequest:
+ """Return a copy with explicit request config overrides applied.
+
+ Only fields implied by the supplied keyword arguments are changed. This
+ preserves existing grouped config such as `cache`, `prompt_cache`,
+ `tool_choice`, `reasoning`, `stop`, and provider-specific
+ `extensions` when an unrelated setting is overridden.
+ """
+ if not kwargs:
+ return self
+ merged = _merge_config_overrides(self.config, kwargs)
+ return self.model_copy(update={"config": merged}, deep=True)
+
+
+class LMUsage(BaseModel):
+ """Token and timing usage for one LM request.
+
+ Both DSPy token names and provider token names are populated because both
+ are existing user-visible history/usage interfaces.
+ """
+
+ input_tokens: int | None = None
+ output_tokens: int | None = None
+ total_tokens: int | None = None
+ prompt_tokens: int | None = None
+ completion_tokens: int | None = None
+ reasoning_tokens: int | None = None
+ cache_read_tokens: int | None = None
+ cache_write_tokens: int | None = None
+ input_audio_tokens: int | None = None
+ output_audio_tokens: int | None = None
+ details: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(extra="allow")
+
+ @model_validator(mode="after")
+ def fill_aliases(self) -> LMUsage:
+ if self.input_tokens is None and self.prompt_tokens is not None:
+ self.input_tokens = self.prompt_tokens
+ if self.output_tokens is None and self.completion_tokens is not None:
+ self.output_tokens = self.completion_tokens
+ if self.prompt_tokens is None and self.input_tokens is not None:
+ self.prompt_tokens = self.input_tokens
+ if self.completion_tokens is None and self.output_tokens is not None:
+ self.completion_tokens = self.output_tokens
+ if self.total_tokens is None and self.input_tokens is not None and self.output_tokens is not None:
+ self.total_tokens = self.input_tokens + self.output_tokens
+ return self
+
+
+class LMOutput(BaseModel):
+ """One generated candidate in an LM response."""
+
+ parts: list[LMPart] = Field(default_factory=list)
+ finish_reason: str | None = None
+ truncated: bool = False
+ logprobs: Any | None = None
+ provider_output: Any | None = Field(default=None, exclude=True)
+ provider_data: dict[str, Any] = Field(default_factory=dict)
+ metadata: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+ @model_validator(mode="before")
+ @classmethod
+ def normalize_parts(cls, data: Any) -> Any:
+ if isinstance(data, dict) and "parts" in data:
+ data = dict(data)
+ data["parts"] = [_coerce_part(part) for part in data["parts"]]
+ return data
+
+ @property
+ def text(self) -> str | None:
+ texts = [part.text for part in self.parts if isinstance(part, LMTextPart)]
+ return "".join(texts) if texts else None
+
+ @property
+ def reasoning_content(self) -> str | None:
+ texts = [part.text for part in self.parts if isinstance(part, LMThinkingPart)]
+ return "".join(texts) if texts else None
+
+ @property
+ def tool_calls(self) -> list[LMToolCallPart]:
+ return [part for part in self.parts if isinstance(part, LMToolCallPart)]
+
+ @property
+ def citations(self) -> list[LMCitationPart]:
+ return [part for part in self.parts if isinstance(part, LMCitationPart)]
+
+ @property
+ def images(self) -> list[LMImagePart]:
+ return [part for part in self.parts if isinstance(part, LMImagePart)]
+
+ @property
+ def audio(self) -> list[LMAudioPart]:
+ return [part for part in self.parts if isinstance(part, LMAudioPart)]
+
+ @property
+ def videos(self) -> list[LMVideoPart]:
+ return [part for part in self.parts if isinstance(part, LMVideoPart)]
+
+ @property
+ def documents(self) -> list[LMDocumentPart]:
+ return [part for part in self.parts if isinstance(part, LMDocumentPart)]
+
+ @property
+ def binaries(self) -> list[LMBinaryPart]:
+ return [part for part in self.parts if isinstance(part, LMBinaryPart)]
+
+ @property
+ def refusal(self) -> str | None:
+ refusals = [part.text for part in self.parts if isinstance(part, LMRefusalPart)]
+ return "".join(refusals) if refusals else None
+
+ def to_value(self) -> Any:
+ values = [_part_to_value(part) for part in self.parts]
+ values = [value for value in values if value is not None]
+ if len(values) == 1 and isinstance(values[0], str) and self.logprobs is None:
+ return values[0]
+ return values
+
+ def to_output_dict(self) -> dict[str, Any]:
+ data: dict[str, Any] = {"text": self.text}
+ if self.reasoning_content is not None:
+ data["reasoning_content"] = self.reasoning_content
+ if self.tool_calls:
+ data["tool_calls"] = [_tool_call_to_provider_dict(call) for call in self.tool_calls]
+ if self.citations:
+ data["citations"] = [citation.model_dump(exclude_none=True) for citation in self.citations]
+ if self.logprobs is not None:
+ data["logprobs"] = self.logprobs
+ return data
+
+
+class LMResponse(BaseModel):
+ """The normalized result of one LM request."""
+
+ model: str | None = None
+ outputs: list[LMOutput] = Field(min_length=1)
+ usage: LMUsage | dict[str, Any] | None = None
+ cost: float | None = None
+ cache_hit: bool = False
+ response_id: str | None = None
+ provider_response: Any | None = Field(default=None, exclude=True)
+ provider_data: dict[str, Any] = Field(default_factory=dict)
+ metadata: dict[str, Any] = Field(default_factory=dict)
+
+ model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+ @model_validator(mode="before")
+ @classmethod
+ def normalize_usage(cls, data: Any) -> Any:
+ if isinstance(data, dict) and isinstance(data.get("usage"), dict):
+ data = dict(data)
+ data["usage"] = LMUsage(**data["usage"])
+ return data
+
+ @classmethod
+ def from_text(
+ cls,
+ text: str,
+ *,
+ model: str | None = None,
+ usage: LMUsage | dict[str, Any] | None = None,
+ cost: float | None = None,
+ cache_hit: bool = False,
+ **kwargs: Any,
+ ) -> LMResponse:
+ return cls(
+ model=model,
+ outputs=[LMOutput(parts=[LMTextPart(text=text)])],
+ usage=usage,
+ cost=cost,
+ cache_hit=cache_hit,
+ **kwargs,
+ )
+
+ def __iter__(self):
+ return iter(self.to_values())
+
+ def __getitem__(self, index: int) -> Any:
+ return self.to_values()[index]
+
+ def __len__(self) -> int:
+ return len(self.outputs)
+
+ @property
+ def output(self) -> LMOutput:
+ return self.outputs[0]
+
+ @property
+ def parts(self) -> list[LMPart]:
+ return self.output.parts
+
+ @property
+ def text(self) -> str | None:
+ return self.output.text
+
+ @property
+ def reasoning_content(self) -> str | None:
+ return self.output.reasoning_content
+
+ @property
+ def tool_calls(self) -> list[LMToolCallPart]:
+ return self.output.tool_calls
+
+ @property
+ def citations(self) -> list[LMCitationPart]:
+ return self.output.citations
+
+ @property
+ def images(self) -> list[LMImagePart]:
+ return self.output.images
+
+ @property
+ def audio(self) -> list[LMAudioPart]:
+ return self.output.audio
+
+ @property
+ def videos(self) -> list[LMVideoPart]:
+ return self.output.videos
+
+ @property
+ def documents(self) -> list[LMDocumentPart]:
+ return self.output.documents
+
+ @property
+ def binaries(self) -> list[LMBinaryPart]:
+ return self.output.binaries
+
+ def to_values(self) -> list[Any]:
+ return [output.to_value() for output in self.outputs]
+
+ def to_outputs(self) -> list[Any]:
+ outputs: list[Any] = []
+ for output in self.outputs:
+ if _requires_output_dict(output):
+ outputs.append(output.to_output_dict())
+ else:
+ outputs.append(output.to_value())
+ return outputs
+
+ def to_legacy_outputs(self) -> list[Any]:
+ return self.to_outputs()
+
+ def usage_as_dict(self) -> dict[str, Any]:
+ if self.usage is None:
+ return {}
+ if isinstance(self.usage, LMUsage):
+ return self.usage.model_dump(exclude_none=True)
+ return dict(self.usage)
+
+
+class LMHistoryEntry(BaseModel, Mapping[str, Any]):
+ """A typed history record that can be read like a dictionary.
+
+ Store the canonical request and response, then derive legacy convenience
+ fields such as `outputs`, `usage`, `messages`, and `kwargs` on demand.
+ Because this class implements `Mapping`, existing history code can keep
+ using `entry["messages"]`, `entry.get("prompt")`, `entry.items()`, and
+ `dict(entry)`.
+ """
+
+ request: LMRequest
+ response: LMResponse
+ timestamp: str
+ uuid: str
+ model_type: str | None = None
+
+ model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
+
+ @model_validator(mode="before")
+ @classmethod
+ def drop_derived_fields(cls, data: Any) -> Any:
+ if isinstance(data, dict):
+ data = dict(data)
+ for key in _HISTORY_DERIVED_KEYS:
+ data.pop(key, None)
+ return data
+
+ @property
+ def outputs(self) -> list[Any]:
+ return self.response.to_outputs()
+
+ @property
+ def usage(self) -> dict[str, Any]:
+ return self.response.usage_as_dict()
+
+ @property
+ def cost(self) -> float | None:
+ return self.response.cost
+
+ @property
+ def model(self) -> str:
+ return self.request.model
+
+ @property
+ def prompt(self) -> str | None:
+ return _history_request_prompt(self.request)
+
+ @property
+ def messages(self) -> list[dict[str, Any]] | None:
+ return _history_request_messages_as_openai(self.request)
+
+ @property
+ def kwargs(self) -> dict[str, Any]:
+ return _history_request_kwargs(self.request)
+
+ @property
+ def response_model(self) -> str | None:
+ return self.response.model
+
+ def __getitem__(self, key: str) -> Any:
+ return self._mapping()[key]
+
+ def __iter__(self) -> Iterator[str]:
+ return iter(self._mapping())
+
+ def __len__(self) -> int:
+ return len(self._mapping())
+
+ def __repr__(self) -> str:
+ formatted = pformat(self._essential_mapping(), width=100, sort_dicts=False)
+ return f"LMHistoryEntry(\n{formatted}\n)"
+
+ def __str__(self) -> str:
+ return repr(self)
+
+ def to_dict(self, *, mode: str = "python", exclude_none: bool = False, **kwargs: Any) -> dict[str, Any]:
+ """Return this history entry as a plain dictionary."""
+ if kwargs:
+ return self.model_dump(mode=mode, exclude_none=exclude_none, **kwargs)
+ data = self._mapping()
+ if mode != "python":
+ data = json.loads(json.dumps(data, default=_json_default))
+ if exclude_none:
+ data = {key: value for key, value in data.items() if value is not None}
+ return data
+
+ def _essential_mapping(self) -> dict[str, Any]:
+ data = self.model_dump(mode="python", exclude_none=True)
+ data.update(self.model_extra or {})
+ return data
+
+ def _mapping(self) -> dict[str, Any]:
+ data = self._essential_mapping()
+ data.update({key: getattr(self, key) for key in _HISTORY_DERIVED_KEYS})
+ return {key: value for key, value in data.items() if value is not None}
+
+
+_HISTORY_DERIVED_KEYS = (
+ "outputs",
+ "usage",
+ "cost",
+ "model",
+ "prompt",
+ "messages",
+ "kwargs",
+ "response_model",
+)
+
+
+def _json_default(value: Any) -> Any:
+ if hasattr(value, "model_dump"):
+ return value.model_dump(mode="json", exclude_none=True)
+ return str(value)
+
+
+class LMDelta(BaseModel):
+ """Base class for streamed content deltas."""
+
+ type: str
+
+
+class LMTextDelta(LMDelta):
+ type: Literal["text_delta"] = "text_delta"
+ text: str
+
+
+class LMThinkingDelta(LMDelta):
+ type: Literal["thinking_delta"] = "thinking_delta"
+ text: str
+
+
+class LMToolCallDelta(LMDelta):
+ type: Literal["tool_call_delta"] = "tool_call_delta"
+ id: str | None = None
+ name: str | None = None
+ args_delta: str | None = None
+
+
+class LMCitationDelta(LMDelta):
+ type: Literal["citation_delta"] = "citation_delta"
+ citation: LMCitationPart
+
+
+class LMImageDelta(LMDelta):
+ type: Literal["image_delta"] = "image_delta"
+ image: LMImagePart
+
+
+class LMAudioDelta(LMDelta):
+ type: Literal["audio_delta"] = "audio_delta"
+ audio: LMAudioPart
+
+
+LMAnyDelta = Annotated[
+ LMTextDelta | LMThinkingDelta | LMToolCallDelta | LMCitationDelta | LMImageDelta | LMAudioDelta,
+ Field(discriminator="type"),
+]
+
+
+class LMStreamEvent(BaseModel):
+ """Base class for normalized LM stream events."""
+
+ type: str
+
+
+class LMStreamStartEvent(LMStreamEvent):
+ type: Literal["start"] = "start"
+ model: str | None = None
+
+
+class LMStreamDeltaEvent(LMStreamEvent):
+ type: Literal["delta"] = "delta"
+ output_index: int = Field(default=0, ge=0)
+ part_index: int = Field(ge=0)
+ delta: LMAnyDelta
+
+
+class LMStreamOutputEndEvent(LMStreamEvent):
+ type: Literal["output_end"] = "output_end"
+ output_index: int = Field(default=0, ge=0)
+ finish_reason: str | None = None
+ truncated: bool = False
+
+
+class LMStreamEndEvent(LMStreamEvent):
+ type: Literal["end"] = "end"
+ usage: LMUsage | dict[str, Any] | None = None
+ cost: float | None = None
+ response: LMResponse | None = None
+
+
+class LMStreamErrorEvent(LMStreamEvent):
+ type: Literal["error"] = "error"
+ error: Exception
+
+ model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class LMOutputBuilder:
+ """Assemble streamed LM events into a final `LMResponse`."""
+
+ def __init__(self):
+ self.model: str | None = None
+ self._parts: dict[int, list[LMPart | None]] = {}
+ self._finish_reasons: dict[int, str | None] = {}
+ self._truncated: dict[int, bool] = {}
+
+ def apply(self, event: LMStreamEvent) -> LMResponse | None:
+ if isinstance(event, LMStreamStartEvent):
+ self.model = event.model
+ return None
+ if isinstance(event, LMStreamDeltaEvent):
+ self._apply_delta(event)
+ return None
+ if isinstance(event, LMStreamOutputEndEvent):
+ self._finish_reasons[event.output_index] = event.finish_reason
+ self._truncated[event.output_index] = event.truncated
+ return None
+ if isinstance(event, LMStreamEndEvent):
+ if event.response is not None:
+ return event.response
+ return self.to_response(usage=event.usage, cost=event.cost)
+ if isinstance(event, LMStreamErrorEvent):
+ raise event.error
+ return None
+
+ def to_response(self, *, usage: LMUsage | dict[str, Any] | None = None, cost: float | None = None) -> LMResponse:
+ output_indices = set(self._parts) | set(self._finish_reasons) | set(self._truncated)
+ if not output_indices:
+ output_indices = {0}
+ max_index = max(output_indices)
+ expected_indices = set(range(max_index + 1))
+ if output_indices != expected_indices:
+ missing = sorted(expected_indices - output_indices)
+ raise ValueError(f"Stream output indices must be contiguous from 0; missing indices: {missing}.")
+
+ outputs = []
+ for output_index in range(max_index + 1):
+ part_buffer = self._parts.get(output_index, [])
+ missing_part_indices = [index for index, part in enumerate(part_buffer) if part is None]
+ if missing_part_indices:
+ raise ValueError(
+ f"Stream part indices for output {output_index} must be contiguous; "
+ f"missing indices: {missing_part_indices}."
+ )
+ parts = [_finalize_stream_part(part) for part in part_buffer]
+ outputs.append(
+ LMOutput(
+ parts=parts,
+ finish_reason=self._finish_reasons.get(output_index),
+ truncated=self._truncated.get(output_index, False),
+ )
+ )
+ return LMResponse(model=self.model, outputs=outputs, usage=usage, cost=cost)
+
+ def _apply_delta(self, event: LMStreamDeltaEvent) -> None:
+ parts = self._parts.setdefault(event.output_index, [])
+ while len(parts) <= event.part_index:
+ parts.append(None)
+
+ current = parts[event.part_index]
+ delta = event.delta
+ if isinstance(delta, LMThinkingDelta):
+ if current is not None and not isinstance(current, LMThinkingPart):
+ raise ValueError("Cannot apply thinking delta to a non-thinking stream part.")
+ text = (current.text if isinstance(current, LMThinkingPart) else "") + delta.text
+ parts[event.part_index] = LMThinkingPart(text=text)
+ elif isinstance(delta, LMTextDelta):
+ if current is not None and not isinstance(current, LMTextPart):
+ raise ValueError("Cannot apply text delta to a non-text stream part.")
+ text = (current.text if isinstance(current, LMTextPart) else "") + delta.text
+ parts[event.part_index] = LMTextPart(text=text)
+ elif isinstance(delta, LMToolCallDelta):
+ if current is not None and not isinstance(current, LMToolCallPart):
+ raise ValueError("Cannot apply tool-call delta to a non-tool-call stream part.")
+ buffer = ""
+ if isinstance(current, LMToolCallPart):
+ buffer = current.provider_data.get("args_buffer", "")
+ buffer += delta.args_delta or ""
+ args = _parse_json_object(buffer)
+ parts[event.part_index] = LMToolCallPart(
+ id=delta.id if delta.id is not None else getattr(current, "id", None),
+ name=delta.name if delta.name is not None else getattr(current, "name", ""),
+ args=args,
+ provider_data={"args_buffer": buffer},
+ )
+ elif isinstance(delta, LMCitationDelta):
+ if current is not None and not isinstance(current, LMCitationPart):
+ raise ValueError("Cannot apply citation delta to a different stream part type.")
+ parts[event.part_index] = delta.citation
+ elif isinstance(delta, LMImageDelta):
+ if current is not None and not isinstance(current, LMImagePart):
+ raise ValueError("Cannot apply image delta to a different stream part type.")
+ parts[event.part_index] = delta.image
+ elif isinstance(delta, LMAudioDelta):
+ if current is not None and not isinstance(current, LMAudioPart):
+ raise ValueError("Cannot apply audio delta to a different stream part type.")
+ parts[event.part_index] = delta.audio
+
+
+class LMStream:
+ """Synchronous LM stream with a final `LMResponse` result."""
+
+ def __init__(
+ self,
+ *,
+ request: LMRequest,
+ events: Iterator[LMStreamEvent],
+ finalize: Callable[[LMRequest, LMResponse], LMResponse],
+ ):
+ self.request = request
+ self._events = events
+ self._finalize = finalize
+ self._builder = LMOutputBuilder()
+ self._result: LMResponse | None = None
+
+ def __iter__(self) -> Iterator[LMStreamEvent]:
+ for event in self._events:
+ response = self._builder.apply(event)
+ if response is not None:
+ self._result = self._finalize(self.request, response)
+ yield event
+
+ def result(self) -> LMResponse:
+ if self._result is None:
+ raise RuntimeError("Stream has not completed yet.")
+ return self._result
+
+
+class AsyncLMStream:
+ """Asynchronous LM stream with a final `LMResponse` result."""
+
+ def __init__(
+ self,
+ *,
+ request: LMRequest,
+ events: AsyncIterator[LMStreamEvent],
+ finalize: Callable[[LMRequest, LMResponse], LMResponse],
+ ):
+ self.request = request
+ self._events = events
+ self._finalize = finalize
+ self._builder = LMOutputBuilder()
+ self._result: LMResponse | None = None
+
+ async def __aiter__(self) -> AsyncIterator[LMStreamEvent]:
+ async for event in self._events:
+ response = self._builder.apply(event)
+ if response is not None:
+ self._result = self._finalize(self.request, response)
+ yield event
+
+ def result(self) -> LMResponse:
+ if self._result is None:
+ raise RuntimeError("Stream has not completed yet.")
+ return self._result
+
+
+def System(*parts: Any, name: str | None = None, metadata: dict[str, Any] | None = None) -> LMMessage: # noqa: N802
+ """Create a system message for a direct LM call.
+
+ A system message gives model-level instructions, such as tone, scope, or
+ formatting rules. Pass text, media parts, or normalized `LMPart` objects;
+ DSPy stores them as one `LMMessage` with role `"system"`.
+
+ Args:
+ *parts: Text, DSPy media objects, or normalized LM parts to include in
+ the message.
+ name: Optional sender name for providers that support named messages.
+ metadata: Extra information to keep with the message.
+
+ Returns:
+ An `LMMessage` that can be passed to `dspy.LanguageModel`, `dspy.LM`, or
+ `dspy.LMRequest`.
+
+ Examples:
+ System instruction with a user turn:
+
+ ```python
+ import dspy
+
+ lm = dspy.LanguageModel(model="test/model")
+ request = lm.normalize_request(
+ dspy.System("You are concise."),
+ dspy.User("What is DSPy?"),
+ )
+ ```
+
+ See Also:
+ [`dspy.User`][dspy.User]
+ [`dspy.Assistant`][dspy.Assistant]
+ [`dspy.LMRequest`][dspy.LMRequest]
+ """
+ return LMMessage(role="system", parts=[_coerce_part(part) for part in parts], name=name, metadata=metadata or {})
+
+
+def Developer(*parts: Any, name: str | None = None, metadata: dict[str, Any] | None = None) -> LMMessage: # noqa: N802
+ """Create a developer message for a direct LM call.
+
+ A developer message carries instructions that sit between system guidance
+ and user content. Use it when a provider supports a `"developer"` role and
+ you want to keep implementation guidance separate from the user's request.
+
+ Args:
+ *parts: Text, DSPy media objects, or normalized LM parts to include in
+ the message.
+ name: Optional sender name for providers that support named messages.
+ metadata: Extra information to keep with the message.
+
+ Returns:
+ An `LMMessage` with role `"developer"`.
+
+ Examples:
+ Add house-style instructions:
+
+ ```python
+ import dspy
+
+ request = dspy.LMRequest.from_call(
+ model="openai/gpt-4o-mini",
+ items=(
+ dspy.System("You are a technical editor."),
+ dspy.Developer("Prefer short examples."),
+ dspy.User("Explain callbacks."),
+ ),
+ )
+ ```
+
+ See Also:
+ [`dspy.System`][dspy.System]
+ [`dspy.User`][dspy.User]
+ """
+ return LMMessage(role="developer", parts=[_coerce_part(part) for part in parts], name=name, metadata=metadata or {})
+
+
+def User(*parts: Any, name: str | None = None, metadata: dict[str, Any] | None = None) -> LMMessage: # noqa: N802
+ """Create a user message for a direct LM call.
+
+ A user message contains the request or data you want the model to answer.
+ Pass plain text for simple prompts, or mix text with images, audio, documents,
+ binary attachments, and normalized LM parts for multimodal calls.
+
+ Args:
+ *parts: Text, DSPy media objects, or normalized LM parts to include in
+ the message.
+ name: Optional sender name for providers that support named messages.
+ metadata: Extra information to keep with the message.
+
+ Returns:
+ An `LMMessage` with role `"user"`.
+
+ Examples:
+ Multi-turn LM call:
+
+ ```python
+ import dspy
+
+ lm = dspy.LM("openai/gpt-4o-mini")
+ response = lm(
+ dspy.User("What is DSPy?"),
+ dspy.Assistant("DSPy is a framework for programming LM pipelines."),
+ dspy.User("Say that in five words."),
+ )
+ ```
+
+ Multi-turn call with media:
+
+ ```python
+ import dspy
+
+ lm = dspy.LM("openai/gpt-4o-mini")
+ response = lm(
+ dspy.System("Answer in one sentence."),
+ dspy.User(
+ "Describe this image.",
+ dspy.Image("https://example.com/dog.png"),
+ ),
+ )
+ ```
+
+ For a single user turn, pass the parts directly to `lm(...)` instead:
+
+ ```python
+ response = lm("Describe this image.", dspy.Image("https://example.com/dog.png"))
+ ```
+
+ Explicit `LMRequest` for custom LM authors and advanced users:
+
+ ```python
+ import dspy
+
+ lm = dspy.LM("openai/gpt-4o-mini")
+ request = dspy.LMRequest(
+ model="openai/gpt-4o-mini",
+ messages=[
+ dspy.System("You are concise."),
+ dspy.User(
+ "Describe this image.",
+ dspy.Image("https://example.com/dog.png"),
+ ),
+ ],
+ config=dspy.LMConfig(temperature=0.2, max_tokens=200),
+ )
+
+ response = lm(request)
+ ```
+
+ See Also:
+ [`dspy.System`][dspy.System]
+ [`dspy.Assistant`][dspy.Assistant]
+ [`dspy.ToolResult`][dspy.ToolResult]
+ """
+ return LMMessage(role="user", parts=[_coerce_part(part) for part in parts], name=name, metadata=metadata or {})
+
+
+def Assistant(*parts: Any, name: str | None = None, metadata: dict[str, Any] | None = None) -> LMMessage: # noqa: N802
+ """Create an assistant message for a direct LM call.
+
+ An assistant message represents a previous model response. Use it when you
+ build a multi-turn request by hand, or when you send tool calls back to the
+ model before adding tool results.
+
+ Args:
+ *parts: Text, tool calls, citations, media parts, or other normalized LM
+ parts from an assistant turn.
+ name: Optional sender name for providers that support named messages.
+ metadata: Extra information to keep with the message.
+
+ Returns:
+ An `LMMessage` with role `"assistant"`.
+
+ Examples:
+ Continue a conversation:
+
+ ```python
+ import dspy
+
+ request = dspy.LMRequest.from_call(
+ model="openai/gpt-4o-mini",
+ items=(
+ dspy.User("What is DSPy?"),
+ dspy.Assistant("DSPy is a framework for programming LM pipelines."),
+ dspy.User("Say that in five words."),
+ ),
+ )
+ ```
+
+ See Also:
+ [`dspy.User`][dspy.User]
+ [`dspy.ToolCall`][dspy.ToolCall]
+ [`dspy.ToolResult`][dspy.ToolResult]
+ """
+ return LMMessage(role="assistant", parts=[_coerce_part(part) for part in parts], name=name, metadata=metadata or {})
+
+
+ToolCall = LMToolCallPart
+"""Create a tool-call part for an assistant message.
+
+`ToolCall` is an alias for `LMToolCallPart`. Use it inside `dspy.Assistant(...)`
+when you want to include a model-requested tool call in a normalized
+conversation.
+"""
+
+
+def ToolResult( # noqa: N802
+ *parts: Any,
+ call_id: str | None = None,
+ name: str | None = None,
+ content: Any | None = None,
+ is_error: bool = False,
+) -> LMMessage:
+ """Create a tool-result message for a direct LM call.
+
+ A tool-result message sends the output of a tool back to the model. Pass the
+ returned text or media as `*parts` or with `content=...`, and include the
+ `call_id` from the matching assistant tool call when the provider uses call
+ IDs.
+
+ Args:
+ *parts: Text, DSPy media objects, or normalized LM parts returned by the
+ tool. If you pass one `LMToolResultPart`, DSPy uses it directly.
+ call_id: Identifier of the assistant tool call this result answers.
+ name: Tool name associated with the result.
+ content: Optional tool output passed by keyword. Use this when adapting
+ OpenAI-style code that stores the result under `content`.
+ is_error: Whether this result represents a failed tool execution.
+
+ Returns:
+ An `LMMessage` with role `"tool"` and one `LMToolResultPart`.
+
+ Examples:
+ Send a weather result back to the model:
+
+ ```python
+ import dspy
+
+ messages = [
+ dspy.User("What is the weather in Paris?"),
+ dspy.Assistant(
+ dspy.ToolCall(
+ id="call_1",
+ name="get_weather",
+ args={"location": "Paris"},
+ )
+ ),
+ dspy.ToolResult(
+ '{"temperature": "22", "unit": "celsius"}',
+ call_id="call_1",
+ name="get_weather",
+ ),
+ dspy.User("Summarize the result."),
+ ]
+ ```
+
+ See Also:
+ [`dspy.ToolCall`][dspy.ToolCall]
+ [`dspy.Assistant`][dspy.Assistant]
+ [`dspy.Tool`][dspy.Tool]
+ """
+ if content is not None:
+ if parts:
+ raise TypeError("Pass tool output either as positional parts or as `content=...`, not both.")
+ parts = tuple(content if isinstance(content, list) else [content])
+
+ if len(parts) == 1 and isinstance(parts[0], LMToolResultPart):
+ result = parts[0]
+ else:
+ result = LMToolResultPart(
+ call_id=call_id,
+ name=name,
+ content=[_coerce_part(part) for part in parts],
+ is_error=is_error,
+ )
+ return LMMessage(role="tool", parts=[result])
+
+
+def _history_request_prompt(request: LMRequest) -> str | None:
+ if len(request.messages) != 1:
+ return None
+ message = request.messages[0]
+ if message.role != "user" or len(message.parts) != 1:
+ return None
+ part = message.parts[0]
+ return part.text if isinstance(part, LMTextPart) else None
+
+
+def _history_request_messages_as_openai(request: LMRequest) -> list[dict[str, Any]]:
+ messages = []
+ for message in request.messages:
+ if message.role == "assistant":
+ tool_calls = [part for part in message.parts if isinstance(part, LMToolCallPart)]
+ content_parts = [part for part in message.parts if not isinstance(part, LMToolCallPart)]
+ item: dict[str, Any] = {
+ "role": "assistant",
+ "content": _history_message_parts_as_openai_content(content_parts) if content_parts else None,
+ }
+ if tool_calls:
+ item["tool_calls"] = [_history_tool_call_as_openai(call) for call in tool_calls]
+ elif message.role == "tool" and len(message.parts) == 1 and isinstance(message.parts[0], LMToolResultPart):
+ result = message.parts[0]
+ item = {"role": "tool", "content": _history_tool_result_content(result)}
+ if result.call_id is not None:
+ item["tool_call_id"] = result.call_id
+ if result.name is not None:
+ item["name"] = result.name
+ else:
+ item = {
+ "role": message.role,
+ "content": _history_message_parts_as_openai_content(message.parts),
+ }
+ if message.name is not None and "name" not in item:
+ item["name"] = message.name
+ messages.append(item)
+ return messages
+
+
+def _history_tool_call_as_openai(call: LMToolCallPart) -> dict[str, Any]:
+ data: dict[str, Any] = {
+ "type": "function",
+ "function": {
+ "name": call.name,
+ "arguments": json.dumps(call.args),
+ },
+ }
+ if call.id is not None:
+ data["id"] = call.id
+ return data
+
+
+def _history_tool_result_content(result: LMToolResultPart) -> str:
+ chunks = []
+ for part in result.content:
+ if isinstance(part, LMTextPart):
+ chunks.append(part.text)
+ else:
+ chunks.append(json.dumps(part.model_dump(mode="json", exclude_none=True), ensure_ascii=False))
+ return "".join(chunks)
+
+
+def _history_message_parts_as_openai_content(parts: list[LMPart]) -> str | list[dict[str, Any]]:
+ if len(parts) == 1 and isinstance(parts[0], LMTextPart):
+ return parts[0].text
+ return [_history_part_as_openai_content(part) for part in parts]
+
+
+def _history_part_as_openai_content(part: LMPart) -> dict[str, Any]:
+ if isinstance(part, LMTextPart):
+ return {"type": "text", "text": part.text}
+ if isinstance(part, LMImagePart):
+ return {"type": "image_url", "image_url": {"url": _history_part_source(part)}}
+ if isinstance(part, LMAudioPart):
+ input_audio = {"format": _history_media_format(part.media_type)}
+ if part.data is not None:
+ if part.data.startswith("data:"):
+ media_type, data = _split_data_uri(part.data)
+ input_audio["format"] = _history_media_format(media_type)
+ input_audio["data"] = data
+ else:
+ input_audio["data"] = part.data
+ elif part.url is not None:
+ input_audio["url"] = part.url
+ elif part.file_id is not None:
+ input_audio["file_id"] = part.file_id
+ elif part.path is not None:
+ input_audio["path"] = part.path
+ return {
+ "type": "input_audio",
+ "input_audio": input_audio,
+ }
+ if isinstance(part, LMVideoPart):
+ video = {"media_type": part.media_type}
+ if part.data is not None:
+ video["data"] = _history_part_source(part)
+ elif part.url is not None:
+ video["url"] = part.url
+ elif part.file_id is not None:
+ video["file_id"] = part.file_id
+ elif part.path is not None:
+ video["path"] = part.path
+ return {"type": "video", "video": video}
+ if isinstance(part, LMDocumentPart):
+ data = {"type": "document"}
+ if part.source is not None:
+ data["source"] = part.source
+ else:
+ data["source"] = _history_part_source(part)
+ data["media_type"] = part.media_type
+ if part.citations:
+ data["citations"] = part.citations
+ if part.title is not None:
+ data["title"] = part.title
+ if part.context is not None:
+ data["context"] = part.context
+ return data
+ if isinstance(part, LMBinaryPart):
+ return {
+ "type": "binary",
+ "binary": {
+ key: value
+ for key, value in {
+ "data": _history_part_source(part),
+ "file_id": part.file_id,
+ "filename": part.filename,
+ "media_type": part.media_type,
+ }.items()
+ if value is not None
+ },
+ }
+ return part.model_dump(exclude_none=True)
+
+
+def _history_part_source(part: LMImagePart | LMAudioPart | LMVideoPart | LMDocumentPart | LMBinaryPart) -> str | None:
+ if part.data is not None:
+ return part.data if part.data.startswith("data:") else f"data:{part.media_type};base64,{part.data}"
+ return part.url or part.file_id or part.path
+
+
+def _history_media_format(media_type: str) -> str:
+ return media_type.split("/", 1)[1] if "/" in media_type else media_type
+
+
+def _history_request_kwargs(request: LMRequest) -> dict[str, Any]:
+ data = request.config.model_dump(exclude_none=True)
+ extensions = data.pop("extensions", {}) or {}
+ return {**extensions, **data}
+
+
+def _validate_one_source(part: Any) -> None:
+ sources = {name: getattr(part, name) for name in ("data", "url", "file_id", "path") if getattr(part, name) is not None}
+ class_name = type(part).__name__
+ if len(sources) != 1:
+ raise ValueError(f"{class_name} requires exactly one of data, url, file_id, or path.")
+ name, value = next(iter(sources.items()))
+ if isinstance(value, str) and not value:
+ raise ValueError(f"{class_name}.{name} must be non-empty.")
+
+
+def _coerce_message(value: dict[str, Any] | LMMessage) -> LMMessage:
+ if isinstance(value, LMMessage):
+ return value
+ return LMMessage(**value)
+
+
+def _messages_from_items(items: tuple[Any, ...], *, prompt: str | None = None) -> tuple[list[LMMessage], list[Any]]:
+ # TODO: Normalize DSPy-specific LM(...) objects in the LM call layer before building LMRequest.
+ if prompt is not None:
+ items = (prompt, *items)
+ if not items:
+ items = ("",)
+
+ if len(items) == 1 and _is_message_sequence(items[0]):
+ items = tuple(items[0])
+
+ if all(isinstance(item, LMMessage) or isinstance(item, LMResponse) for item in items):
+ messages: list[LMMessage] = []
+ for item in items:
+ if isinstance(item, LMMessage):
+ messages.append(item)
+ else:
+ messages.extend(_messages_from_response(item))
+ return messages, []
+
+ parts = [_coerce_part(item) for item in items]
+ return [LMMessage(role="user", parts=parts)], []
+
+
+def _messages_from_response(response: LMResponse) -> list[LMMessage]:
+ return [LMMessage(role="assistant", parts=output.parts) for output in response.outputs]
+
+
+def _is_message_sequence(value: Any) -> bool:
+ return isinstance(value, (list, tuple)) and all(
+ isinstance(item, LMMessage) or isinstance(item, LMResponse) for item in value
+ )
+
+
+def _coerce_part(value: Any) -> LMPart:
+ if isinstance(
+ value,
+ (
+ LMTextPart,
+ LMImagePart,
+ LMAudioPart,
+ LMVideoPart,
+ LMDocumentPart,
+ LMBinaryPart,
+ LMToolCallPart,
+ LMToolResultPart,
+ LMThinkingPart,
+ LMCitationPart,
+ LMRefusalPart,
+ ),
+ ):
+ return value
+ if isinstance(value, str):
+ return LMTextPart(text=value)
+ if isinstance(value, dict) and "type" in value:
+ return pydantic.TypeAdapter(LMPart).validate_python(value)
+ raise TypeError(f"Cannot convert {type(value)!r} to an LMPart.")
+
+
+def _parts_from_openai_content(content: Any) -> list[LMPart]:
+ if content is None:
+ return []
+ if isinstance(content, str):
+ return [LMTextPart(text=content)]
+ if not isinstance(content, list):
+ return [_coerce_part(content)]
+
+ parts = []
+ for item in content:
+ item_type = item.get("type") if isinstance(item, dict) else None
+ if item_type == "text":
+ parts.append(LMTextPart(text=item.get("text", "")))
+ elif item_type == "image_url":
+ image = item.get("image_url", {})
+ if not isinstance(image, dict):
+ raise TypeError("Image content block must be a mapping.")
+ url = image.get("url")
+ if url is None:
+ raise ValueError("Image content block requires url.")
+ parts.append(_image_source_to_part(url))
+ elif item_type == "input_audio":
+ audio = item.get("input_audio", {})
+ parts.append(_audio_dict_to_part(audio))
+ elif item_type == "file":
+ parts.append(_binary_dict_to_part(item.get("file", {})))
+ elif item_type == "document":
+ parts.append(_document_dict_to_part(item))
+ elif item_type == "video":
+ video = item.get("video", {})
+ parts.append(_media_dict_to_video_part(video))
+ else:
+ parts.append(_coerce_part(item))
+ return parts
+
+
+def _tool_calls_from_openai(tool_calls: list[Any]) -> list[LMToolCallPart]:
+ return [_tool_call_from_openai(tool_call) for tool_call in tool_calls]
+
+
+def _tool_call_from_openai(tool_call: Any) -> LMToolCallPart:
+ if not isinstance(tool_call, Mapping):
+ part = _coerce_part(tool_call)
+ if isinstance(part, LMToolCallPart):
+ return part
+ raise TypeError(f"Cannot convert {type(tool_call)!r} to an LMToolCallPart.")
+
+ function = tool_call.get("function", {})
+ if not isinstance(function, Mapping):
+ function = {}
+
+ args = function.get("arguments", {})
+ if isinstance(args, str):
+ args = _parse_json_object(args)
+ elif isinstance(args, Mapping):
+ args = dict(args)
+ else:
+ args = {}
+
+ return LMToolCallPart(
+ id=tool_call.get("id"),
+ name=function.get("name") or tool_call.get("name") or "",
+ args=args,
+ )
+
+
+def _image_source_to_part(source: str) -> LMImagePart:
+ if not isinstance(source, str):
+ raise TypeError("Image URL must be a string.")
+ if source.startswith("data:"):
+ media_type, data = _split_data_uri(source)
+ return LMImagePart(data=data, media_type=media_type)
+ media_type = mimetypes.guess_type(urlparse(source).path)[0] or "image/png"
+ return LMImagePart(url=source, media_type=media_type)
+
+
+def _audio_dict_to_part(audio: dict[str, Any]) -> LMAudioPart:
+ if not isinstance(audio, dict):
+ raise TypeError("Audio content block must be a mapping.")
+
+ audio_format = audio.get("format") or "wav"
+ if not isinstance(audio_format, str):
+ raise TypeError("Audio format must be a string.")
+ media_type = audio_format if "/" in audio_format else f"audio/{audio_format}"
+
+ if audio.get("data") is not None:
+ data = audio["data"]
+ if isinstance(data, str) and data.startswith("data:"):
+ media_type, data = _split_data_uri(data)
+ return LMAudioPart(data=data, media_type=media_type)
+ if audio.get("url") is not None:
+ return LMAudioPart(url=audio["url"], media_type=media_type)
+ if audio.get("file_id") is not None:
+ return LMAudioPart(file_id=audio["file_id"], media_type=media_type)
+ if audio.get("path") is not None:
+ return LMAudioPart(path=audio["path"], media_type=media_type)
+ raise ValueError("Audio content block requires data, url, file_id, or path.")
+
+
+def _binary_dict_to_part(file: dict[str, Any]) -> LMBinaryPart:
+ if file.get("file_data") is not None:
+ media_type, data = _split_data_uri(file["file_data"])
+ return LMBinaryPart(data=data, media_type=media_type, filename=file.get("filename"))
+ if file.get("data") is not None:
+ media_type, data = _split_data_uri(file["data"])
+ return LMBinaryPart(data=data, media_type=media_type, filename=file.get("filename"))
+ if file.get("file_id") is not None:
+ return LMBinaryPart(file_id=file["file_id"], filename=file.get("filename"))
+ raise ValueError("Binary content block requires data, file_data, or file_id.")
+
+
+def _document_dict_to_part(item: dict[str, Any]) -> LMDocumentPart:
+ common = {"title": item.get("title"), "context": item.get("context")}
+ media_type = item.get("media_type") or "application/pdf"
+ for source_key in ("data", "url", "file_id", "path"):
+ if item.get(source_key) is not None:
+ return LMDocumentPart(**{source_key: item[source_key]}, media_type=media_type, **common)
+
+ source = item.get("source")
+ if isinstance(source, dict):
+ return LMDocumentPart(
+ source=source,
+ citations=item.get("citations") or {},
+ **common,
+ )
+ if isinstance(source, str):
+ kwargs = _media_source_kwargs(source, default_media_type=media_type)
+ return LMDocumentPart(**kwargs, **common)
+ raise ValueError("Document content block requires source.")
+
+
+def _media_dict_to_video_part(video: dict[str, Any]) -> LMVideoPart:
+ if video.get("data") is not None:
+ data = video["data"]
+ if isinstance(data, str) and data.startswith("data:"):
+ media_type, data = _split_data_uri(data)
+ else:
+ media_type = video.get("media_type") or "video/mp4"
+ return LMVideoPart(data=data, media_type=media_type)
+ if video.get("url") is not None:
+ return LMVideoPart(url=video["url"], media_type=video.get("media_type") or "video/mp4")
+ if video.get("file_id") is not None:
+ return LMVideoPart(file_id=video["file_id"], media_type=video.get("media_type") or "video/mp4")
+ if video.get("path") is not None:
+ return LMVideoPart(path=video["path"], media_type=video.get("media_type") or "video/mp4")
+ raise ValueError("Video content block requires data, url, file_id, or path.")
+
+
+def _split_data_uri(value: str) -> tuple[str, str]:
+ if not value.startswith("data:") or "," not in value:
+ return "application/octet-stream", value
+ header, data = value.split(",", 1)
+ media_type = header.removeprefix("data:").split(";", 1)[0]
+ return media_type, data
+
+
+def _media_source_kwargs(source: str, *, default_media_type: str) -> dict[str, str]:
+ if source.startswith("data:"):
+ media_type, data = _split_data_uri(source)
+ return {"data": data, "media_type": media_type}
+
+ parsed = urlparse(source)
+ if parsed.scheme in {"http", "https"}:
+ media_type = mimetypes.guess_type(parsed.path)[0] or default_media_type
+ return {"url": source, "media_type": media_type}
+
+ return {"file_id": source, "media_type": default_media_type}
+
+
+def _coerce_tool_spec(tool: Any) -> LMToolSpec:
+ if isinstance(tool, LMToolSpec):
+ return tool
+ if hasattr(tool, "to_lm_tool_spec"):
+ return tool.to_lm_tool_spec()
+ if isinstance(tool, dict):
+ if "function" in tool:
+ function = tool["function"]
+ return LMToolSpec(
+ name=function.get("name"),
+ description=function.get("description"),
+ parameters=function.get("parameters", {}),
+ )
+ return LMToolSpec(**tool)
+ raise TypeError(f"Cannot convert {type(tool)!r} to LMToolSpec.")
+
+
+def _requires_output_dict(output: LMOutput) -> bool:
+ return bool(
+ output.logprobs is not None or output.reasoning_content is not None or output.tool_calls or output.citations
+ )
+
+
+def _part_to_value(part: LMPart) -> Any:
+ if isinstance(part, LMTextPart):
+ return part.text
+ if isinstance(part, LMThinkingPart):
+ return part
+ if isinstance(part, LMToolCallPart):
+ return part
+ if isinstance(part, LMRefusalPart):
+ return part.text
+ return part
+
+
+def _finalize_stream_part(part: LMPart) -> LMPart:
+ if isinstance(part, LMToolCallPart) and "args_buffer" in part.provider_data:
+ return part.model_copy(update={"args": _parse_json_object_strict(part.provider_data["args_buffer"])})
+ return part
+
+
+def _tool_call_to_provider_dict(call: LMToolCallPart) -> dict[str, Any]:
+ data = {
+ "type": "function",
+ "function": {
+ "name": call.name,
+ "arguments": json.dumps(call.args),
+ },
+ }
+ if call.id is not None:
+ data["id"] = call.id
+ return data
+
+
+def _parse_json_object(value: str) -> dict[str, Any]:
+ if not value:
+ return {}
+ try:
+ parsed = json.loads(value)
+ except json.JSONDecodeError:
+ return {}
+ return parsed if isinstance(parsed, dict) else {}
+
+
+def _parse_json_object_strict(value: str) -> dict[str, Any]:
+ if not value:
+ return {}
+ try:
+ parsed = json.loads(value)
+ except json.JSONDecodeError as exc:
+ raise ValueError("Streamed tool-call arguments must be a JSON object.") from exc
+ if not isinstance(parsed, dict):
+ raise ValueError("Streamed tool-call arguments must be a JSON object.")
+ return parsed
diff --git a/tests/core/test_types.py b/tests/core/test_types.py
new file mode 100644
index 000000000..73a5ca366
--- /dev/null
+++ b/tests/core/test_types.py
@@ -0,0 +1,316 @@
+import pydantic
+import pytest
+
+from dspy.core.types import (
+ LMAudioPart,
+ LMConfig,
+ LMDocumentPart,
+ LMHistoryEntry,
+ LMMessage,
+ LMOutput,
+ LMOutputBuilder,
+ LMPromptCacheConfig,
+ LMReasoningConfig,
+ LMRequest,
+ LMRequestPatch,
+ LMResponse,
+ LMStreamDeltaEvent,
+ LMTextDelta,
+ LMThinkingDelta,
+ LMThinkingPart,
+ LMToolCallDelta,
+ LMToolCallPart,
+ LMToolChoice,
+ LMToolResultPart,
+ LMUsage,
+ LMVideoPart,
+ User,
+)
+
+
+def _history_entry(message: LMMessage) -> LMHistoryEntry:
+ return LMHistoryEntry(
+ request=LMRequest(model="model", messages=[message]),
+ response=LMResponse.from_text("ok"),
+ timestamp="timestamp",
+ uuid="uuid",
+ )
+
+
+def test_message_content_and_tool_calls_normalize_for_dspy_history_surface():
+ message = LMMessage(
+ role="assistant",
+ content="Use search.",
+ tool_calls=[
+ {
+ "id": "call_1",
+ "function": {"name": "search", "arguments": '{"query": "dspy"}'},
+ }
+ ],
+ )
+
+ assert message.text == "Use search."
+ assert [part for part in message.parts if isinstance(part, LMToolCallPart)] == [
+ LMToolCallPart(id="call_1", name="search", args={"query": "dspy"})
+ ]
+ assert _history_entry(message).messages == [
+ {
+ "role": "assistant",
+ "content": "Use search.",
+ "tool_calls": [
+ {
+ "type": "function",
+ "function": {"name": "search", "arguments": '{"query": "dspy"}'},
+ "id": "call_1",
+ }
+ ],
+ }
+ ]
+
+
+def test_tool_result_content_none_normalizes_to_empty_parts():
+ assert LMToolResultPart(content=None).content == []
+
+ message = LMMessage(role="tool", content=None, tool_call_id="call_1", name="search")
+ result = message.parts[0]
+
+ assert isinstance(result, LMToolResultPart)
+ assert result.call_id == "call_1"
+ assert result.name == "search"
+ assert result.content == []
+ assert _history_entry(message).messages == [
+ {"role": "tool", "content": "", "tool_call_id": "call_1", "name": "search"}
+ ]
+
+
+def test_audio_content_accepts_url_and_history_preserves_url():
+ message = LMMessage(
+ role="user",
+ content=[
+ {
+ "type": "input_audio",
+ "input_audio": {"url": "https://example.com/audio.wav", "format": "wav"},
+ }
+ ],
+ )
+
+ audio = message.parts[0]
+ assert isinstance(audio, LMAudioPart)
+ assert audio.url == "https://example.com/audio.wav"
+ assert _history_entry(message).messages[0]["content"][0]["input_audio"] == {
+ "format": "wav",
+ "url": "https://example.com/audio.wav",
+ }
+
+
+def test_audio_content_defaults_null_format_to_wav():
+ message = LMMessage(
+ role="user",
+ content=[
+ {
+ "type": "input_audio",
+ "input_audio": {"url": "https://example.com/audio.wav", "format": None},
+ }
+ ],
+ )
+
+ audio = message.parts[0]
+
+ assert isinstance(audio, LMAudioPart)
+ assert audio.media_type == "audio/wav"
+
+
+def test_image_content_requires_mapping_with_url():
+ with pytest.raises(TypeError, match="Image content block"):
+ LMMessage(role="user", content=[{"type": "image_url", "image_url": "https://example.com/image.png"}])
+
+ with pytest.raises(ValueError, match="requires url"):
+ LMMessage(role="user", content=[{"type": "image_url", "image_url": {}}])
+
+
+def test_video_data_round_trips_through_history_messages():
+ message = User(LMVideoPart(data="YWJj", media_type="video/mp4"))
+ content = _history_entry(message).messages[0]["content"][0]
+ round_tripped = LMMessage(role="user", content=[content]).parts[0]
+
+ assert content == {
+ "type": "video",
+ "video": {"media_type": "video/mp4", "data": "data:video/mp4;base64,YWJj"},
+ }
+ assert isinstance(round_tripped, LMVideoPart)
+ assert round_tripped.data == "YWJj"
+ assert round_tripped.media_type == "video/mp4"
+
+
+def test_document_source_url_stays_url_and_round_trips_through_history_messages():
+ message = LMMessage(
+ role="user",
+ content=[
+ {
+ "type": "document",
+ "source": "https://example.com/report.pdf",
+ "title": "Report",
+ }
+ ],
+ )
+ document = message.parts[0]
+ content = _history_entry(message).messages[0]["content"][0]
+ round_tripped = LMMessage(role="user", content=[content]).parts[0]
+
+ assert isinstance(document, LMDocumentPart)
+ assert document.url == "https://example.com/report.pdf"
+ assert document.data is None
+ assert isinstance(round_tripped, LMDocumentPart)
+ assert round_tripped.url == "https://example.com/report.pdf"
+ assert round_tripped.data is None
+
+
+def test_config_extensions_flatten_when_converted_to_legacy_kwargs():
+ config = LMConfig.from_kwargs(temperature=0.2, provider_flag=True)
+ patch = LMRequestPatch(config=config)
+ request = LMRequest.from_call(model="model", prompt="hi", temperature=0.2, provider_flag=True)
+ entry = LMHistoryEntry(
+ request=request,
+ response=LMResponse.from_text("ok"),
+ timestamp="timestamp",
+ uuid="uuid",
+ )
+
+ assert patch.as_lm_kwargs() == {"provider_flag": True, "temperature": 0.2}
+ assert entry.kwargs == {"provider_flag": True, "temperature": 0.2}
+
+
+def test_lm_kwargs_aliases_normalize_for_existing_dspy_lm_callers():
+ config = LMConfig.from_kwargs(
+ reasoning={"effort": "low", "summary": "auto"},
+ reasoning_effort="high",
+ tool_choice={"mode": "auto"},
+ parallel_tool_calls=False,
+ cache=True,
+ rollout_id=7,
+ prompt_cache=True,
+ prompt_cache_key="prompt-cache",
+ provider_flag=True,
+ )
+
+ assert config.reasoning.effort == "high"
+ assert config.reasoning.summary == "auto"
+ assert config.tool_choice.mode == "auto"
+ assert config.tool_choice.parallel is False
+ assert config.cache.enabled is True
+ assert config.cache.rollout_id == 7
+ assert config.prompt_cache.enabled is True
+ assert config.prompt_cache.key == "prompt-cache"
+ assert config.extensions == {"provider_flag": True}
+
+
+def test_nested_config_aliases_remain_supported_for_existing_interfaces():
+ reasoning = LMReasoningConfig.from_value({"reasoning_effort": "high"})
+ tool_choice = LMToolChoice.from_value({"parallel_tool_calls": False})
+ prompt_cache = LMPromptCacheConfig.from_value({"prompt_cache_key": "prompt-cache"})
+
+ assert reasoning.effort == "high"
+ assert tool_choice.mode == "auto"
+ assert tool_choice.parallel is False
+ assert prompt_cache.key == "prompt-cache"
+
+
+def test_usage_normalizes_existing_user_visible_token_aliases():
+ provider_usage = LMUsage(prompt_tokens=1, completion_tokens=2)
+ canonical_usage = LMUsage(input_tokens=1, output_tokens=2)
+
+ assert provider_usage.input_tokens == 1
+ assert provider_usage.output_tokens == 2
+ assert provider_usage.total_tokens == 3
+ assert canonical_usage.prompt_tokens == 1
+ assert canonical_usage.completion_tokens == 2
+ assert canonical_usage.total_tokens == 3
+
+
+def test_default_config_does_not_serialize_empty_stop_sequences():
+ request = LMRequest.from_call(model="model", prompt="hi")
+ entry = LMHistoryEntry(
+ request=request,
+ response=LMResponse.from_text("ok"),
+ timestamp="timestamp",
+ uuid="uuid",
+ )
+
+ assert request.config.stop is None
+ assert entry.kwargs == {}
+
+
+def test_history_entry_exposes_existing_dict_style_properties():
+ message = User("hi")
+ request = LMRequest.from_call(model="model", messages=[message], temperature=0.2)
+ response = LMResponse.from_text("ok", model="response-model", usage={"input_tokens": 1}, cost=0.5)
+ entry = LMHistoryEntry(request=request, response=response, timestamp="timestamp", uuid="uuid")
+
+ assert entry.model == "model"
+ assert entry.prompt == "hi"
+ assert entry.messages == [{"role": "user", "content": "hi"}]
+ assert entry.outputs == ["ok"]
+ assert entry.usage["input_tokens"] == 1
+ assert entry.cost == 0.5
+ assert entry.kwargs == {"temperature": 0.2}
+ assert entry.response_model == "response-model"
+ assert entry["messages"] == [{"role": "user", "content": "hi"}]
+ assert entry["kwargs"] == {"temperature": 0.2}
+
+
+def test_response_rejects_empty_outputs():
+ with pytest.raises(pydantic.ValidationError):
+ LMResponse(model="model", outputs=[])
+
+
+def test_output_to_value_preserves_redacted_thinking_part():
+ thinking = LMThinkingPart(text="hidden", redacted=True)
+ output = LMOutput(parts=[thinking])
+
+ assert output.to_value() == [thinking]
+
+
+def test_stream_event_indices_must_be_non_negative():
+ with pytest.raises(pydantic.ValidationError):
+ LMStreamDeltaEvent(output_index=-1, part_index=0, delta=LMTextDelta(text="x"))
+
+ with pytest.raises(pydantic.ValidationError):
+ LMStreamDeltaEvent(output_index=0, part_index=-1, delta=LMTextDelta(text="x"))
+
+
+def test_stream_builder_rejects_sparse_output_indices():
+ builder = LMOutputBuilder()
+ builder.apply(LMStreamDeltaEvent(output_index=2, part_index=0, delta=LMTextDelta(text="third")))
+
+ with pytest.raises(ValueError, match="output indices"):
+ builder.to_response()
+
+
+def test_stream_builder_rejects_sparse_part_indices():
+ builder = LMOutputBuilder()
+ builder.apply(LMStreamDeltaEvent(output_index=0, part_index=1, delta=LMTextDelta(text="second")))
+
+ with pytest.raises(ValueError, match="part indices"):
+ builder.to_response()
+
+
+def test_stream_builder_rejects_delta_type_changes():
+ builder = LMOutputBuilder()
+ builder.apply(LMStreamDeltaEvent(output_index=0, part_index=0, delta=LMTextDelta(text="text")))
+
+ with pytest.raises(ValueError, match="thinking delta"):
+ builder.apply(LMStreamDeltaEvent(output_index=0, part_index=0, delta=LMThinkingDelta(text="thought")))
+
+
+def test_stream_builder_rejects_incomplete_tool_call_arguments():
+ builder = LMOutputBuilder()
+ builder.apply(
+ LMStreamDeltaEvent(
+ output_index=0,
+ part_index=0,
+ delta=LMToolCallDelta(id="call_1", name="search", args_delta='{"query": '),
+ )
+ )
+
+ with pytest.raises(ValueError, match="tool-call arguments"):
+ builder.to_response()