DSPy: The framework for programming—not prompting—language models
Python
Enhance type hints of adapters (#7896)
TomuHirataab23dc0ea429
diff --git a/dspy/adapters/base.py b/dspy/adapters/base.pyindex 7964dac1c..017b8db34 100644--- a/dspy/adapters/base.py+++ b/dspy/adapters/base.py@@ -1,13 +1,14 @@from abc import ABC, abstractmethod--from litellm import ContextWindowExceededError+from typing import Type, Any, Optional, TYPE_CHECKINGfrom dspy.adapters.types import History-from dspy.utils.callback import with_callbacks-+from dspy.utils.callback import BaseCallback, with_callbacks+from dspy.signatures.signature import Signature+if TYPE_CHECKING:+ from dspy.clients.lm import LMclass Adapter(ABC):- def __init__(self, callbacks=None):+ def __init__(self, callbacks: Optional[list[BaseCallback]] = None):self.callbacks = callbacks or []def __init_subclass__(cls, **kwargs) -> None:@@ -17,60 +18,53 @@ class Adapter(ABC):cls.format = with_callbacks(cls.format)cls.parse = with_callbacks(cls.parse)- def __call__(self, lm, lm_kwargs, signature, demos, inputs):+ def __call__(self, lm: "LM", lm_kwargs: dict[str, Any], signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]:inputs_ = self.format(signature, demos, inputs)inputs_ = dict(prompt=inputs_) if isinstance(inputs_, str) else dict(messages=inputs_)outputs = lm(**inputs_, **lm_kwargs)values = []- try:- for output in outputs:- output_logprobs = None-- if isinstance(output, dict):- output, output_logprobs = output["text"], output["logprobs"]+ for output in outputs:+ output_logprobs = None- value = self.parse(signature, output)+ if isinstance(output, dict):+ output, output_logprobs = output["text"], output["logprobs"]- if set(value.keys()) != set(signature.output_fields.keys()):- raise ValueError(- "Parsed output fields do not match signature output fields. "- f"Expected: {set(signature.output_fields.keys())}, Got: {set(value.keys())}"- )+ value = self.parse(signature, output)- if output_logprobs is not None:- value["logprobs"] = output_logprobs+ if set(value.keys()) != set(signature.output_fields.keys()):+ raise ValueError(+ "Parsed output fields do not match signature output fields. "+ f"Expected: {set(signature.output_fields.keys())}, Got: {set(value.keys())}"+ )- values.append(value)+ if output_logprobs is not None:+ value["logprobs"] = output_logprobs- return values+ values.append(value)- except Exception as e:- if isinstance(e, ContextWindowExceededError):- # On context window exceeded error, we don't want to retry with a different adapter.- raise e- from dspy.adapters.json_adapter import JSONAdapter+ return values- if not isinstance(self, JSONAdapter):- return JSONAdapter()(lm, lm_kwargs, signature, demos, inputs)- raise e@abstractmethod- def format(self, signature, demos, inputs):+ def format(self, signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]:raise NotImplementedError@abstractmethod- def parse(self, signature, completion):+ def parse(self, signature: Type[Signature], completion: str) -> dict[str, Any]:raise NotImplementedError-- def format_finetune_data(self, signature, demos, inputs, outputs):++ def format_fields(self, signature: Type[Signature], values: dict[str, Any], role: str) -> str:+ raise NotImplementedError++ def format_finetune_data(self, signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any], outputs: dict[str, Any]) -> dict[str, list[Any]]:raise NotImplementedError- def format_turn(self, signature, values, role, incomplete=False, is_conversation_history=False):- pass+ def format_turn(self, signature: Type[Signature], values, role: str, incomplete: bool = False, is_conversation_history: bool = False) -> dict[str, Any]:+ raise NotImplementedError- def format_conversation_history(self, signature, inputs):+ def format_conversation_history(self, signature: Type[Signature], inputs: dict[str, Any]) -> list[dict[str, Any]]:history_field_name = Nonefor name, field in signature.input_fields.items():if field.annotation == History:diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.pyindex 1c10fc4e2..885270813 100644--- a/dspy/adapters/chat_adapter.py+++ b/dspy/adapters/chat_adapter.py@@ -4,11 +4,11 @@ import jsonimport reimport textwrapfrom collections.abc import Mapping-from itertools import chain-from typing import Any, Dict, Literal, NamedTuple+from typing import Any, Dict, Literal, NamedTuple, Optional, Typeimport pydanticfrom pydantic.fields import FieldInfo+from litellm import ContextWindowExceededErrorfrom dspy.adapters.base import Adapterfrom dspy.adapters.types.image import try_expand_image_tags@@ -17,6 +17,9 @@ from dspy.adapters.utils import format_field_value, get_annotation_name, parse_vfrom dspy.signatures.field import OutputFieldfrom dspy.signatures.signature import Signature, SignatureMetafrom dspy.signatures.utils import get_dspy_field_type+from dspy.adapters.json_adapter import JSONAdapter+from dspy.clients.lm import LM+from dspy.utils.callback import BaseCallbackfield_header_pattern = re.compile(r"\[\[ ## (\w+) ## \]\]")@@ -31,7 +34,20 @@ BuiltInCompletedOutputFieldInfo = FieldInfoWithName(name="completed", info=Outpuclass ChatAdapter(Adapter):- def format(self, signature: Signature, demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]:+ def __init__(self, callbacks: Optional[list[BaseCallback]] = None):+ super().__init__(callbacks)++ def __call__(self, lm: LM, lm_kwargs: dict[str, Any], signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]:+ try:+ return super().__call__(lm, lm_kwargs, signature, demos, inputs)+ except Exception as e:+ if isinstance(e, ContextWindowExceededError):+ # On context window exceeded error, we don't want to retry with a different adapter.+ raise e+ # fallback to JSONAdapter+ return JSONAdapter()(lm, lm_kwargs, signature, demos, inputs)++ def format(self, signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]:messages: list[dict[str, Any]] = []# Extract demos where some of the output_fields are not filled in.@@ -64,7 +80,7 @@ class ChatAdapter(Adapter):messages = try_expand_image_tags(messages)return messages- def parse(self, signature, completion):+ def parse(self, signature: Type[Signature], completion: str) -> dict[str, Any]:sections = [(None, [])]for line in completion.splitlines():@@ -92,7 +108,7 @@ class ChatAdapter(Adapter):return fields# TODO(PR): Looks ok?- def format_finetune_data(self, signature, demos, inputs, outputs):+ def format_finetune_data(self, signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any], outputs: dict[str, Any]) -> dict[str, list[Any]]:# Get system + user messagesmessages = self.format(signature, demos, inputs)@@ -105,7 +121,7 @@ class ChatAdapter(Adapter):# Wrap the messages in a dictionary with a "messages" keyreturn dict(messages=messages)- def format_fields(self, signature, values, role):+ def format_fields(self, signature: Type[Signature], values: dict[str, Any], role: str) -> str:fields_with_values = {FieldInfoWithName(name=field_name, info=field_info): values.get(field_name, "Not supplied for this particular example."@@ -115,7 +131,7 @@ class ChatAdapter(Adapter):}return format_fields(fields_with_values)- def format_turn(self, signature, values, role, incomplete=False, is_conversation_history=False):+ def format_turn(self, signature: Type[Signature], values: dict[str, Any], role: str, incomplete: bool = False, is_conversation_history: bool = False) -> dict[str, Any]:return format_turn(signature, values, role, incomplete, is_conversation_history)@@ -139,7 +155,7 @@ def format_fields(fields_with_values: Dict[FieldInfoWithName, Any]) -> str:return "\n\n".join(output).strip()-def format_turn(signature, values, role, incomplete=False, is_conversation_history=False):+def format_turn(signature: Type[Signature], values: dict[str, Any], role: str, incomplete=False, is_conversation_history=False):"""Constructs a new message ("turn") to append to a chat thread. The message is carefully formattedso that it can instruct an LLM to generate responses conforming to the specified DSPy signature.@@ -212,11 +228,6 @@ def format_turn(signature, values, role, incomplete=False, is_conversation_historeturn {"role": role, "content": joined_messages}-def flatten_messages(messages):- """Flatten nested message lists."""- return list(chain.from_iterable(item if isinstance(item, list) else [item] for item in messages))--def enumerate_fields(fields: dict) -> str:parts = []for idx, (k, v) in enumerate(fields.items()):diff --git a/dspy/adapters/json_adapter.py b/dspy/adapters/json_adapter.pyindex 827f9e603..7567e7876 100644--- a/dspy/adapters/json_adapter.py+++ b/dspy/adapters/json_adapter.py@@ -4,7 +4,7 @@ import jsonimport loggingimport textwrapfrom copy import deepcopy-from typing import Any, Dict, KeysView, Literal, NamedTuple+from typing import Any, Dict, KeysView, Literal, NamedTuple, Typeimport json_repairimport litellm@@ -16,7 +16,8 @@ from dspy.adapters.base import Adapterfrom dspy.adapters.types.image import Imagefrom dspy.adapters.types.history import Historyfrom dspy.adapters.utils import format_field_value, get_annotation_name, parse_value, serialize_for_json-from dspy.signatures.signature import SignatureMeta+from dspy.clients.lm import LM+from dspy.signatures.signature import SignatureMeta, Signaturefrom dspy.signatures.utils import get_dspy_field_typelogger = logging.getLogger(__name__)@@ -26,12 +27,11 @@ class FieldInfoWithName(NamedTuple):name: strinfo: FieldInfo-class JSONAdapter(Adapter):def __init__(self):pass- def __call__(self, lm, lm_kwargs, signature, demos, inputs):+ def __call__(self, lm: LM, lm_kwargs: dict[str, Any], signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]:inputs = self.format(signature, demos, inputs)inputs = dict(prompt=inputs) if isinstance(inputs, str) else dict(messages=inputs)@@ -66,7 +66,7 @@ class JSONAdapter(Adapter):return values- def format(self, signature, demos, inputs):+ def format(self, signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any]) -> list[dict[str, Any]]:messages = []# Extract demos where some of the output_fields are not filled in.@@ -94,7 +94,7 @@ class JSONAdapter(Adapter):return messages- def parse(self, signature, completion):+ def parse(self, signature: Type[Signature], completion: str) -> dict[str, Any]:fields = json_repair.loads(completion)fields = {k: v for k, v in fields.items() if k in signature.output_fields}@@ -108,10 +108,7 @@ class JSONAdapter(Adapter):return fields- def format_turn(self, signature, values, role, incomplete=False, is_conversation_history=False):- return format_turn(signature, values, role, incomplete, is_conversation_history)-- def format_fields(self, signature, values, role):+ def format_fields(self, signature: Type[Signature], values: dict[str, Any], role: str) -> str:fields_with_values = {FieldInfoWithName(name=field_name, info=field_info): values.get(field_name, "Not supplied for this particular example."@@ -121,6 +118,13 @@ class JSONAdapter(Adapter):}return format_fields(role=role, fields_with_values=fields_with_values)++ def format_turn(self, signature: Type[Signature], values, role: str, incomplete: bool = False, is_conversation_history: bool = False) -> dict[str, Any]:+ return format_turn(signature, values, role, incomplete, is_conversation_history)++ def format_finetune_data(self, signature: Type[Signature], demos: list[dict[str, Any]], inputs: dict[str, Any], outputs: dict[str, Any]) -> dict[str, list[Any]]:+ # TODO: implement format_finetune_data method in JSONAdapter+ raise NotImplementedErrordef _format_field_value(field_info: FieldInfo, value: Any) -> str:diff --git a/dspy/clients/lm.py b/dspy/clients/lm.pyindex 47e69f95f..c94bd5f9d 100644--- a/dspy/clients/lm.py+++ b/dspy/clients/lm.py@@ -6,7 +6,7 @@ import threadingimport uuidfrom datetime import datetimefrom hashlib import sha256-from typing import Any, Dict, List, Literal, Optional, cast+from typing import Any, Dict, List, Literal, Optional, cast, TYPE_CHECKINGimport litellmimport pydantic@@ -17,11 +17,12 @@ from cachetools import LRUCache, cachedfrom litellm import RetryPolicyimport dspy-from dspy.adapters.base import Adapterfrom dspy.clients.openai import OpenAIProviderfrom dspy.clients.provider import Provider, TrainingJobfrom dspy.clients.utils_finetune import TrainDataFormatfrom dspy.utils.callback import BaseCallback, with_callbacks+if TYPE_CHECKING:+ from dspy.adapters.base import Adapterfrom .base_lm import BaseLM@@ -219,7 +220,7 @@ class LM(BaseLM):# providers in this file. Is this okay?return Provider()- def infer_adapter(self) -> Adapter:+ def infer_adapter(self) -> "Adapter":import dspyif dspy.settings.adapter:diff --git a/dspy/predict/predict.py b/dspy/predict/predict.pyindex 301b68595..79276dbe3 100644--- a/dspy/predict/predict.py+++ b/dspy/predict/predict.py@@ -9,6 +9,8 @@ from dspy.primitives.prediction import Predictionfrom dspy.primitives.program import Modulefrom dspy.signatures.signature import ensure_signaturefrom dspy.utils.callback import with_callbacks+from dspy.dsp.utils import settings+from dspy.adapters.chat_adapter import ChatAdapterclass Predict(Module, Parameter):@@ -71,8 +73,6 @@ class Predict(Module, Parameter):return self.forward(**kwargs)def forward(self, **kwargs):- import dspy-# Extract the three privileged keyword arguments.assert "new_signature" not in kwargs, "new_signature is no longer a valid keyword argument."signature = ensure_signature(kwargs.pop("signature", self.signature))@@ -80,7 +80,7 @@ class Predict(Module, Parameter):config = dict(**self.config, **kwargs.pop("config", {}))# Get the right LM to use.- lm = kwargs.pop("lm", self.lm) or dspy.settings.lm+ lm = kwargs.pop("lm", self.lm) or settings.lmassert isinstance(lm, BaseLM), "No LM is loaded."# If temperature is 0.0 but its n > 1, set temperature to 0.7.@@ -96,9 +96,7 @@ class Predict(Module, Parameter):missing = [k for k in signature.input_fields if k not in kwargs]print(f"WARNING: Not all input fields were provided to module. Present: {present}. Missing: {missing}.")- import dspy-- adapter = dspy.settings.adapter or dspy.ChatAdapter()+ adapter = settings.adapter or ChatAdapter()completions = adapter(lm,lm_kwargs=config,@@ -109,8 +107,8 @@ class Predict(Module, Parameter):pred = Prediction.from_completions(completions, signature=signature)- if kwargs.pop("_trace", True) and dspy.settings.trace is not None:- trace = dspy.settings.trace+ if kwargs.pop("_trace", True) and settings.trace is not None:+ trace = settings.tracetrace.append((self, {**kwargs}, pred))return pred