[perf][imports][defer litellm and mcp so import swarms does no provider work]

import swarms eagerly imported litellm (~1.1s, and litellm's own __init__
fetches its model-cost map from raw.githubusercontent.com) and mcp, neither
of which is needed until the first LLM call or the first MCP use. Import
drops from ~2.2s to ~0.6s and no longer touches the network — verified by
importing with socket.connect monkeypatched to raise.

litellm deferral, per module:

- litellm_wrapper binds litellm/completion/supports_vision into module
  globals on first LiteLLM construction. Module attributes rather than
  function-local imports so existing tests that patch
  litellm_wrapper.completion keep working; each name binds only while
  None, so an active patch is never overwritten. context_compressor gets
  the same treatment for its patched completion.
- agent.py's reasoning_effort annotation called get_reasoning_efforts() in
  the class body, which introspects litellm.completion — forcing the
  import at class-definition time. The Literal on a plain class is never
  enforced at runtime, so it now uses the static REASONING_EFFORTS set the
  same module already maintains for exactly this fallback.
- litellm_tokenizer, agent_loader, agent_router, tree_swarm, llm_manager
  and agent.py move their litellm imports into the functions that use
  them (count_tokens, model validation, embedding calls, capability
  checks, reliability_check).
- The litellm exception names vanish from except tuples that already
  contained Exception, which subsumed them; behaviour is identical and the
  exceptions still propagate to callers.

mcp deferral: mcp_manager and aop gain `from __future__ import
annotations` so mcp types in signatures stop needing the real classes at
def time, TYPE_CHECKING imports keep the annotations meaningful, and the
two runtime uses (ClientSession construction, the MCPTool isinstance
check, FastMCP construction) import locally.

Two subprocess regression tests in tests/test___init__.py pin the
contract: import swarms leaves litellm/mcp/openai unloaded, and the first
LiteLLM construction still binds litellm.

Addresses kyegomez#1754 and the import-time side effects behind kyegomez#1739 and kyegomez#1738.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ayaangazali

swarms/agents/context_compressor.py

@@ -9,11 +9,13 @@
 
 from typing import Any, Optional
 
-from litellm import completion
 from loguru import logger
 
 from swarms.utils.litellm_tokenizer import count_tokens
 
+# Bound on first use; see summarize(). Patched directly by tests.
+completion = None
+
 
 COMPRESSION_SYSTEM_PROMPT = """
 You are a conversation compression expert. Your job is to produce a faithful, dense summary of an ongoing agent conversation so that the agent can continue its work without losing critical context.
@@ -98,6 +100,16 @@ def _summarize(self, agent: Any, history: str) -> str:
             raise ValueError(
                 "No summarizer_model configured and agent has no model_name"
             )
+        # Deferred: litellm must not load at `import swarms` time
+        # (#1754). Bound into the module global so tests can keep patching
+        # ``swarms.agents.context_compressor.completion``; an active patch
+        # is non-None and is never overwritten.
+        global completion
+        if completion is None:
+            from litellm import completion as _completion
+
+            completion = _completion
+
         response = completion(
             model=model,
             messages=[

swarms/agents/llm_manager.py

@@ -31,16 +31,6 @@
 import traceback
 from typing import Any, Callable, List, Optional, Union
 
-from litellm.exceptions import (
-    AuthenticationError,
-    BadRequestError,
-    InternalServerError,
-)
-from litellm.utils import (
-    supports_function_calling,
-    supports_parallel_function_calling,
-    supports_vision,
-)
 from loguru import logger
 
 from swarms.schemas.agent_errors import AgentLLMInitializationError
@@ -325,6 +315,13 @@ def check_model_supports_utilities(
         """
         agent = self.agent
 
+        # Deferred: litellm must not load at `import swarms` time (#1754).
+        from litellm.utils import (
+            supports_function_calling,
+            supports_parallel_function_calling,
+            supports_vision,
+        )
+
         # Only check vision support if an image is provided
         if img is not None:
             out = supports_vision(agent.model_name)
@@ -549,12 +546,7 @@ def call(
 
             return agent.llm.run(**run_args, **kwargs)
 
-        except (
-            BadRequestError,
-            InternalServerError,
-            AuthenticationError,
-            Exception,
-        ) as e:
+        except Exception as e:
             logger.error(
                 f"Error calling LLM with model '{self.get_current_model()}': {e}. "
                 f"Task: {task}, Args: {args}, Kwargs: {kwargs} Traceback: {traceback.format_exc()}"

swarms/structs/agent.py

@@ -19,17 +19,6 @@
 
 import toml
 import yaml
-from litellm import model_list
-from litellm.exceptions import (
-    AuthenticationError,
-    BadRequestError,
-    InternalServerError,
-)
-from litellm.utils import (
-    get_max_tokens,
-    get_model_info,
-    supports_function_calling,
-)
 from loguru import logger
 from pydantic import BaseModel
 
@@ -50,7 +39,7 @@
     AgentToolError,
     AgentToolExecutionError,
 )
-from swarms.utils.get_reasoning_efforts import get_reasoning_efforts
+from swarms.utils.get_reasoning_efforts import REASONING_EFFORTS
 from swarms.utils.workspace_utils import get_workspace_dir
 from swarms.artifacts.main_artifact import Artifact
 from swarms.prompts.agent_system_prompts import AGENT_SYSTEM_PROMPT_3
@@ -411,7 +400,7 @@ def __init__(
         reasoning_prompt_on: bool = True,
         dynamic_context_window: bool = True,
         show_tool_execution_output: bool = True,
-        reasoning_effort: Literal[get_reasoning_efforts()] = "medium",
+        reasoning_effort: Literal[REASONING_EFFORTS] = "medium",
         thinking_tokens: int = 1024,
         reasoning_enabled: bool = False,
         handoffs: Optional[Union[Sequence[Callable], Any]] = None,
@@ -1601,12 +1590,7 @@ def _run(
                                 loop_count=loop_count
                             )
 
-                    except (
-                        BadRequestError,
-                        InternalServerError,
-                        AuthenticationError,
-                        Exception,
-                    ) as e:
+                    except Exception as e:
 
                         # Track the LLM/generation error via telemetry — the
                         # retry loop swallows it, so capture_run never sees it.
@@ -3075,6 +3059,8 @@ def _default_context_length(self) -> int:
               which may not correspond to available context for input (e.g., 32768 for gpt-4.1 output, but
               over a million for certain input windows).
         """
+        from litellm.utils import get_model_info
+
         try:
             return (
                 get_model_info(self.model_name).get(
@@ -3096,6 +3082,8 @@ def _default_max_tokens(self) -> int:
         Returns:
             int: The maximum number of output tokens for the model. Returns 16000 if undetermined.
         """
+        from litellm.utils import get_model_info
+
         # get_model_info raises for an unmapped model id rather than
         # returning an empty mapping, so an unknown, custom or self-hosted
         # model would otherwise take down Agent.__init__. The sibling
@@ -3127,6 +3115,14 @@ def reliability_check(self):
                 "Max loops is not provided or is set to 0. Please set max loops to 1 or more."
             )
 
+        # Deferred: litellm costs >1s to import and fetches its model-cost
+        # map, so it must not load at `import swarms` time (#1754, #1739).
+        from litellm import model_list
+        from litellm.utils import (
+            get_max_tokens,
+            supports_function_calling,
+        )
+
         # Ensure max_tokens is set to a valid value based on the model, with a robust fallback.
         if self.max_tokens is None or self.max_tokens <= 0:
             suggested_tokens = get_max_tokens(self.model_name)
@@ -4106,9 +4102,6 @@ def run(
         except (
             AgentRunError,
             AgentLLMError,
-            BadRequestError,
-            InternalServerError,
-            AuthenticationError,
             Exception,
         ) as e:
 

swarms/structs/agent_loader.py

@@ -15,7 +15,6 @@
 )
 
 import yaml
-from litellm import model_list
 from tqdm import tqdm
 
 from swarms.agents.create_agents_from_yaml import (
@@ -110,7 +109,11 @@ def validate_config(
             if isinstance(config, AgentSpec):
                 config = config.model_dump()
 
-            # Validate model name using litellm model list
+            # Validate model name using litellm model list.
+            # Deferred import: litellm must not load at `import swarms`
+            # time (#1754).
+            from litellm import model_list
+
             model_name = str(config["model_name"])
             # model_list from litellm is a list of strings, not dicts
             if isinstance(model_list, list) and len(model_list) > 0:

swarms/structs/agent_router.py

@@ -1,7 +1,6 @@
 import math
 from typing import Any, Callable, List, Optional, Union
 
-from litellm import embedding
 from tenacity import retry, stop_after_attempt, wait_exponential
 
 from swarms.structs.ma_blocks import find_agent_by_name
@@ -57,6 +56,9 @@ def _generate_embedding(self, text: str) -> List[float]:
             List[float]: The embedding vector as a list of floats.
         """
         try:
+            # Deferred: litellm must not load at `import swarms` time (#1754).
+            from litellm import embedding
+
             # Prepare parameters for the embedding call
             params = {"model": self.embedding_model, "input": [text]}
 

swarms/structs/aop.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 from contextlib import AbstractAsyncContextManager
 import socket
@@ -12,10 +14,17 @@
 from uuid import uuid4
 
 from loguru import logger
-from mcp.server.auth.settings import AuthSettings
-from mcp.server.fastmcp import FastMCP
-from mcp.server.lowlevel.server import LifespanResultT
-from mcp.server.transport_security import TransportSecuritySettings
+from typing import TYPE_CHECKING
+
+if (
+    TYPE_CHECKING
+):  # Deferred: mcp must not load at `import swarms` (#1754)
+    from mcp.server.auth.settings import AuthSettings
+    from mcp.server.fastmcp import FastMCP
+    from mcp.server.lowlevel.server import LifespanResultT
+    from mcp.server.transport_security import (
+        TransportSecuritySettings,
+    )
 
 from swarms.structs.agent import Agent
 from swarms.structs.omni_agent_types import AgentType
@@ -679,6 +688,9 @@ def __init__(
         self.task_queues: Dict[str, TaskQueue] = {}
         self.transport = transport
 
+        # Deferred: mcp must not load at `import swarms` time (#1754).
+        from mcp.server.fastmcp import FastMCP
+
         self.mcp_server = FastMCP(
             name=server_name,
             port=port,

swarms/structs/tree_swarm.py

@@ -3,7 +3,6 @@
 from datetime import datetime, timezone
 from typing import Any, List, Optional
 
-from litellm import embedding
 from pydantic import BaseModel, Field
 
 from swarms.structs.agent import Agent
@@ -194,6 +193,9 @@ def _get_embedding(self, text: str) -> List[float]:
             List[float]: Embedding vector
         """
         try:
+            # Deferred: litellm must not load at `import swarms` time (#1754).
+            from litellm import embedding
+
             response = embedding(
                 model=self.embedding_model_name, input=[text]
             )

swarms/tools/mcp_manager.py

@@ -16,6 +16,7 @@
 ``MCPManager`` is the only object an ``Agent`` needs to hold.
 """
 
+from __future__ import annotations
 import asyncio
 import json
 import os
@@ -32,8 +33,13 @@
 from urllib.parse import parse_qs, urlparse
 
 from loguru import logger
-from mcp import ClientSession
-from mcp.types import Tool as MCPTool
+from typing import TYPE_CHECKING
+
+if (
+    TYPE_CHECKING
+):  # Deferred: mcp must not load at `import swarms` (#1754)
+    from mcp import ClientSession
+    from mcp.types import Tool as MCPTool
 
 from swarms.schemas.agent_mcp_errors import (
     AgentMCPConnectionError,
@@ -877,6 +883,8 @@ def _tool_name(tool: Any) -> Optional[str]:
         if isinstance(tool, dict):
             function = tool.get("function") or {}
             return function.get("name") or tool.get("name")
+        from mcp.types import Tool as MCPTool
+
         if isinstance(tool, MCPTool):
             return tool.name
         return getattr(tool, "name", None)
@@ -1493,6 +1501,8 @@ async def _session(self, connection: MCPConnection):
             )
 
         try:
+            from mcp import ClientSession
+
             async with client_cm as ctx:
                 read, write = ctx[0], ctx[1]
                 async with ClientSession(

swarms/utils/litellm_tokenizer.py

@@ -1,4 +1,3 @@
-from litellm import encode, model_list
 from loguru import logger
 from typing import Optional
 from functools import lru_cache
@@ -30,6 +29,9 @@ def count_tokens(
         logger.warning("Empty or whitespace-only text provided")
         return 0
 
+    # Deferred: litellm must not load at `import swarms` time (#1754).
+    from litellm import encode
+
     # Set fallback encoder
     fallback_model = default_encoder or DEFAULT_MODEL
 
@@ -74,6 +76,8 @@ def count_tokens(
 def get_supported_models() -> list:
     """Get list of supported models from litellm."""
     try:
+        from litellm import model_list
+
         return model_list
     except Exception as e:
         logger.warning(f"Could not retrieve model list: {e}")

swarms/utils/litellm_wrapper.py

@@ -24,9 +24,7 @@
 from pathlib import Path
 from typing import List, Optional
 
-import litellm
 import requests
-from litellm import completion, supports_vision
 from loguru import logger
 from pydantic import BaseModel
 
@@ -38,6 +36,37 @@
 )
 
 
+# Bound by _bind_litellm() on first LiteLLM construction.
+litellm = None
+completion = None
+supports_vision = None
+
+
+def _bind_litellm() -> None:
+    """Import litellm on first LiteLLM construction, not at module import.
+
+    Importing litellm costs >1s and fetches its model-cost map from the
+    network, so it must not run at `import swarms` time (#1754, #1739).
+    The callables are bound into this module's globals so every existing
+    call site — and every test that patches ``litellm_wrapper.completion``
+    as a module attribute — keeps working unchanged. Each name binds only
+    while None, so an active patch is never overwritten.
+    """
+    global litellm, completion, supports_vision
+    if litellm is None:
+        import litellm as _litellm
+
+        litellm = _litellm
+    if completion is None:
+        from litellm import completion as _completion
+
+        completion = _completion
+    if supports_vision is None:
+        from litellm import supports_vision as _supports_vision
+
+        supports_vision = _supports_vision
+
+
 class LiteLLMException(Exception):
     """
     Custom exception raised for LiteLLM-specific errors.
@@ -339,6 +368,10 @@ def __init__(
         self.modalities = []
         self.messages = []  # Initialize messages list
 
+        # First construction pays the litellm import; `import swarms` no
+        # longer does.
+        _bind_litellm()
+
         # Configure litellm settings
         litellm.set_verbose = (
             verbose  # Disable verbose mode for better performance