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.pynew file mode 100644index 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 parseddiff --git a/tests/core/test_types.py b/tests/core/test_types.pynew file mode 100644index 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()