Make LiteLLM imports lazy

dspy/clients/__init__.py

@@ -3,8 +3,7 @@
 from pathlib import Path
 from typing import Any
 
-import litellm
-
+from dspy.clients._litellm import get_litellm
 from dspy.clients.base_lm import BaseLM, inspect_history
 from dspy.clients.cache import Cache
 from dspy.clients.embedding import Embedder
@@ -56,9 +55,6 @@ def configure_cache(
     dspy.cache = DSPY_CACHE
 
 
-litellm.telemetry = False
-litellm.cache = None  # By default we disable LiteLLM cache and use DSPy on-disk cache.
-
 
 def _get_dspy_cache():
     disk_cache_dir = os.environ.get("DSPY_CACHEDIR") or os.path.join(Path.home(), ".dspy_cache")
@@ -91,7 +87,8 @@ def _get_dspy_cache():
 def configure_litellm_logging(level: str = "ERROR"):
     """Configure LiteLLM logging to the specified level."""
     # Litellm uses a global logger called `verbose_logger` to control all loggings.
-    from litellm._logging import verbose_logger
+    litellm = get_litellm(feature="LiteLLM logging")
+    verbose_logger = litellm._logging.verbose_logger
 
     numeric_logging_level = getattr(logging, level)
 
@@ -101,18 +98,18 @@ def configure_litellm_logging(level: str = "ERROR"):
 
 
 def enable_litellm_logging():
+    litellm = get_litellm(feature="LiteLLM logging")
     litellm.suppress_debug_info = False
+    litellm._dspy_logging_configured = True
     configure_litellm_logging("DEBUG")
 
 
 def disable_litellm_logging():
+    litellm = get_litellm(feature="LiteLLM logging")
     litellm.suppress_debug_info = True
+    litellm._dspy_logging_configured = True
     configure_litellm_logging("ERROR")
 
-
-# By default, we disable LiteLLM logging for clean logging
-disable_litellm_logging()
-
 __all__ = [
     "BaseLM",
     "LM",

dspy/clients/_litellm.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import functools
+import sys
+import types
+from typing import Any
+
+from dspy.utils.lazy_import import require
+
+
+@functools.cache
+def _configure_litellm_defaults(litellm: types.ModuleType) -> None:
+    """Apply DSPy's global LiteLLM defaults once when LiteLLM is first imported."""
+    litellm.telemetry = False
+    litellm.cache = None  # By default we disable LiteLLM cache and use DSPy on-disk cache.
+    if not getattr(litellm, "_dspy_logging_configured", False):
+        litellm.suppress_debug_info = True
+        litellm._dspy_logging_configured = True
+
+
+def _materialize_litellm(litellm: types.ModuleType) -> None:
+    """Force LiteLLM's lazy module to execute, or raise the missing dependency error."""
+    # `require()` returns either an importlib LazyLoader-backed module or a _MissingModule.
+    # Accessing a real LiteLLM attribute forces LazyLoader execution; on _MissingModule it raises
+    # the helpful install-hint ImportError immediately at the DSPy call site.
+    _completion = litellm.completion
+
+
+@functools.cache
+def get_litellm(*, feature: str) -> Any:
+    """Import LiteLLM, apply DSPy's defaults once, and return the module."""
+    litellm = require("litellm", extra="litellm", feature=feature)
+    _materialize_litellm(litellm)
+    _configure_litellm_defaults(litellm)
+    return litellm
+
+
+def is_litellm_context_window_error(error: Exception) -> bool:
+    """Return whether an exception is LiteLLM's context-window error, if LiteLLM is loaded."""
+    litellm_module = sys.modules.get("litellm")
+    context_window_error = getattr(litellm_module, "ContextWindowExceededError", None)
+    return context_window_error is not None and isinstance(error, context_window_error)

dspy/clients/embedding.py

@@ -2,13 +2,17 @@
 
 from typing import Any, Callable
 
-import litellm
-
+from dspy.clients._litellm import get_litellm
 from dspy.clients.cache import request_cache
 from dspy.utils.lazy_import import require
 
 np = require("numpy")
 
+
+def _get_litellm():
+    return get_litellm(feature="dspy.Embedder")
+
+
 class Embedder:
     """DSPy embedding class.
 
@@ -152,8 +156,8 @@ async def acall(self, inputs, batch_size=None, caching=None, **kwargs):
 
 def _compute_embeddings(model, batch_inputs, caching=False, **kwargs):
     if isinstance(model, str):
-        caching = caching and litellm.cache is not None
-        embedding_response = litellm.embedding(model=model, input=batch_inputs, caching=caching, **kwargs)
+        caching = caching and _get_litellm().cache is not None
+        embedding_response = _get_litellm().embedding(model=model, input=batch_inputs, caching=caching, **kwargs)
         return [data["embedding"] for data in embedding_response.data]
     elif callable(model):
         return model(batch_inputs, **kwargs)
@@ -168,8 +172,8 @@ def _cached_compute_embeddings(model, batch_inputs, caching=True, **kwargs):
 
 async def _acompute_embeddings(model, batch_inputs, caching=False, **kwargs):
     if isinstance(model, str):
-        caching = caching and litellm.cache is not None
-        embedding_response = await litellm.aembedding(model=model, input=batch_inputs, caching=caching, **kwargs)
+        caching = caching and _get_litellm().cache is not None
+        embedding_response = await _get_litellm().aembedding(model=model, input=batch_inputs, caching=caching, **kwargs)
         return [data["embedding"] for data in embedding_response.data]
     elif callable(model):
         return model(batch_inputs, **kwargs)

dspy/clients/lm.py

@@ -7,12 +7,11 @@
 from typing import Any, Literal, cast
 
 import anyio.from_thread
-import litellm
 import pydantic
 from anyio.streams.memory import MemoryObjectSendStream
-from litellm import ContextWindowExceededError as LitellmContextWindowExceededError
 
 import dspy
+from dspy.clients._litellm import get_litellm, is_litellm_context_window_error
 from dspy.clients.cache import request_cache
 from dspy.clients.openai import OpenAIProvider
 from dspy.clients.provider import Provider, ReinforceJob, TrainingJob
@@ -26,6 +25,10 @@
 logger = logging.getLogger(__name__)
 
 
+def _get_litellm():
+    return get_litellm(feature="dspy.LM")
+
+
 class LM(BaseLM):
     """
     A language model supporting chat or text completion requests for use with DSPy modules.
@@ -122,19 +125,19 @@ def _provider_name(self) -> str:
 
     @property
     def supports_function_calling(self) -> bool:
-        return litellm.supports_function_calling(model=self.model)
+        return _get_litellm().supports_function_calling(model=self.model)
 
     @property
     def supports_reasoning(self) -> bool:
-        return litellm.supports_reasoning(self.model)
+        return _get_litellm().supports_reasoning(self.model)
 
     @property
     def supports_response_schema(self) -> bool:
-        return litellm.supports_response_schema(model=self.model, custom_llm_provider=self._provider_name)
+        return _get_litellm().supports_response_schema(model=self.model, custom_llm_provider=self._provider_name)
 
     @property
     def supported_params(self) -> set[str]:
-        params = litellm.get_supported_openai_params(model=self.model, custom_llm_provider=self._provider_name)
+        params = _get_litellm().get_supported_openai_params(model=self.model, custom_llm_provider=self._provider_name)
         return set(params) if params else set()
 
     def _warn_zero_temp_rollout(self, temperature: float | None, rollout_id):
@@ -189,8 +192,10 @@ def forward(
                 num_retries=self.num_retries,
                 cache=litellm_cache_args,
             )
-        except LitellmContextWindowExceededError as e:
-            raise ContextWindowExceededError(model=self.model) from e
+        except Exception as e:
+            if is_litellm_context_window_error(e):
+                raise ContextWindowExceededError(model=self.model) from e
+            raise
 
         self._check_truncation(results)
 
@@ -230,8 +235,10 @@ async def aforward(
                 num_retries=self.num_retries,
                 cache=litellm_cache_args,
             )
-        except LitellmContextWindowExceededError as e:
-            raise ContextWindowExceededError(model=self.model) from e
+        except Exception as e:
+            if is_litellm_context_window_error(e):
+                raise ContextWindowExceededError(model=self.model) from e
+            raise
 
         self._check_truncation(results)
 
@@ -355,7 +362,7 @@ def _get_stream_completion_fn(
         request["stream_options"] = {"include_usage": True}
 
     async def stream_completion(request: dict[str, Any], cache_kwargs: dict[str, Any]):
-        response = await litellm.acompletion(
+        response = await _get_litellm().acompletion(
             cache=cache_kwargs,
             stream=True,
             headers=headers,
@@ -368,7 +375,7 @@ async def stream_completion(request: dict[str, Any], cache_kwargs: dict[str, Any
                 chunk.predict_id = caller_predict_id
             chunks.append(chunk)
             await stream.send(chunk)
-        return litellm.stream_chunk_builder(chunks)
+        return _get_litellm().stream_chunk_builder(chunks)
 
     def sync_stream_completion():
         return anyio.from_thread.run(functools.partial(stream_completion, request, cache_kwargs))
@@ -389,7 +396,7 @@ def litellm_completion(request: dict[str, Any], num_retries: int, cache: dict[st
     headers = _add_dspy_identifier_to_headers(request.pop("headers", None))
     stream_completion = _get_stream_completion_fn(request, cache, sync=True, headers=headers)
     if stream_completion is None:
-        return litellm.completion(
+        return _get_litellm().completion(
             cache=cache,
             num_retries=num_retries,
             retry_strategy="exponential_backoff_retry",
@@ -417,7 +424,7 @@ def litellm_text_completion(request: dict[str, Any], num_retries: int, cache: di
     # Build the prompt from the messages.
     prompt = "\n\n".join([x["content"] for x in request.pop("messages")] + ["BEGIN RESPONSE:"])
 
-    return litellm.text_completion(
+    return _get_litellm().text_completion(
         cache=cache,
         model=f"text-completion-openai/{model}",
         api_key=api_key,
@@ -437,7 +444,7 @@ async def alitellm_completion(request: dict[str, Any], num_retries: int, cache:
     headers = _add_dspy_identifier_to_headers(request.pop("headers", None))
     stream_completion = _get_stream_completion_fn(request, cache, sync=False, headers=headers)
     if stream_completion is None:
-        return await litellm.acompletion(
+        return await _get_litellm().acompletion(
             cache=cache,
             num_retries=num_retries,
             retry_strategy="exponential_backoff_retry",
@@ -463,7 +470,7 @@ async def alitellm_text_completion(request: dict[str, Any], num_retries: int, ca
     # Build the prompt from the messages.
     prompt = "\n\n".join([x["content"] for x in request.pop("messages")] + ["BEGIN RESPONSE:"])
 
-    return await litellm.atext_completion(
+    return await _get_litellm().atext_completion(
         cache=cache,
         model=f"text-completion-openai/{model}",
         api_key=api_key,
@@ -483,7 +490,7 @@ def litellm_responses_completion(request: dict[str, Any], num_retries: int, cach
     headers = request.pop("headers", None)
     request = _convert_chat_request_to_responses_request(request)
 
-    return litellm.responses(
+    return _get_litellm().responses(
         cache=cache,
         num_retries=num_retries,
         retry_strategy="exponential_backoff_retry",
@@ -499,7 +506,7 @@ async def alitellm_responses_completion(request: dict[str, Any], num_retries: in
     headers = request.pop("headers", None)
     request = _convert_chat_request_to_responses_request(request)
 
-    return await litellm.aresponses(
+    return await _get_litellm().aresponses(
         cache=cache,
         num_retries=num_retries,
         retry_strategy="exponential_backoff_retry",

dspy/streaming/streamify.py

@@ -6,11 +6,9 @@
 from queue import Queue
 from typing import TYPE_CHECKING, Any, AsyncGenerator, Awaitable, Callable, Generator
 
-import litellm
 import orjson
 from anyio import create_memory_object_stream, create_task_group
 from anyio.streams.memory import MemoryObjectSendStream
-from litellm import ModelResponseStream
 
 from dspy.dsp.utils.settings import settings
 from dspy.primitives.prediction import Prediction
@@ -20,6 +18,12 @@
 
 logger = logging.getLogger(__name__)
 
+
+def _is_litellm_model_response_stream(value: Any) -> bool:
+    cls = type(value)
+    return cls.__name__ == "ModelResponseStream" and cls.__module__.startswith("litellm")
+
+
 if TYPE_CHECKING:
     from dspy.primitives.module import Module
 
@@ -178,7 +182,7 @@ async def async_streamer(*args, **kwargs):
             tg.start_soon(generator, args, kwargs, send_stream)
 
             async for value in receive_stream:
-                if isinstance(value, ModelResponseStream):
+                if _is_litellm_model_response_stream(value):
                     if len(predict_id_to_listener) == 0:
                         # No listeners are configured, yield the chunk directly for backwards compatibility.
                         yield value
@@ -271,7 +275,7 @@ async def streaming_response(streamer: AsyncGenerator) -> AsyncGenerator:
         if isinstance(value, Prediction):
             data = {"prediction": dict(value.items(include_dspy=False))}
             yield f"data: {orjson.dumps(data).decode()}\n\n"
-        elif isinstance(value, litellm.ModelResponseStream):
+        elif _is_litellm_model_response_stream(value):
             data = {"chunk": value.json()}
             yield f"data: {orjson.dumps(data).decode()}\n\n"
         elif isinstance(value, str) and value.startswith("data:"):

dspy/streaming/streaming_listener.py

@@ -1,11 +1,12 @@
+from __future__ import annotations
+
 import inspect
 import re
 from collections import defaultdict
 from queue import Queue
 from typing import TYPE_CHECKING, Any
 
 import jiter
-from litellm import ModelResponseStream
 
 from dspy.adapters.chat_adapter import ChatAdapter
 from dspy.adapters.json_adapter import JSONAdapter
@@ -15,6 +16,8 @@
 from dspy.streaming.messages import StreamResponse
 
 if TYPE_CHECKING:
+    from litellm import ModelResponseStream
+
     from dspy.primitives.module import Module
 
 ADAPTER_SUPPORT_STREAMING = [ChatAdapter, XMLAdapter, JSONAdapter]
@@ -368,7 +371,7 @@ def _output_type(self) -> type | None:
 
 
 def find_predictor_for_stream_listeners(
-    program: "Module", stream_listeners: list[StreamListener]
+    program: Module, stream_listeners: list[StreamListener]
 ) -> dict[int, list[StreamListener]]:
     """Find the predictor for each stream listener.
 
@@ -385,7 +388,7 @@ def find_predictor_for_stream_listeners(
         field_name_to_named_predictor[listener.signature_field_name] = None
 
     for name, predictor in predictors:
-        for field_name, field_info in predictor.signature.output_fields.items():
+        for field_name in predictor.signature.output_fields:
             if field_name not in field_name_to_named_predictor:
                 continue
 

dspy/utils/lazy_import.py

@@ -42,6 +42,7 @@ def _detect_dspy_dist() -> str:
     "weaviate": "weaviate",
     "anthropic": "anthropic",
     "numpy": "numpy",
+    "litellm": "litellm",
 }
 
 

pyproject.toml

@@ -44,6 +44,7 @@ mcp = ["mcp; python_version >= '3.10'"]
 langchain = ["langchain_core"]
 optuna = ["optuna>=3.4.0"]
 numpy = ["numpy>=1.26.0"]
+litellm = ["litellm>=1.64.0"]
 dev = [
     "pytest>=6.2.5",
     "pytest-mock>=3.12.0",