Merge pull request #14818 from akshoop/akshoop/fastuuid-dep-make-optional

Fix: make `fastuuid` an optional dependency for `proxy`, graceful fallback to stdlib `uuid`

Author: krrishdholakia

.circleci/config.yml

@@ -1521,6 +1521,7 @@ jobs:
       - run: python ./tests/code_coverage_tests/prevent_key_leaks_in_exceptions.py
       - run: python ./tests/code_coverage_tests/check_unsafe_enterprise_import.py
       - run: python ./tests/code_coverage_tests/ban_copy_deepcopy_kwargs.py
+      - run: python ./tests/code_coverage_tests/check_fastuuid_usage.py
       - run: helm lint ./deploy/charts/litellm-helm
 
   db_migration_disable_update_check:

litellm/_uuid.py

@@ -0,0 +1,23 @@
+"""
+Internal unified UUID helper.
+
+Tries to use fastuuid (performance) and falls back to stdlib uuid if unavailable.
+"""
+
+FASTUUID_AVAILABLE = False
+
+try:
+    import fastuuid as _uuid  # type: ignore
+
+    FASTUUID_AVAILABLE = True
+except Exception:  # pragma: no cover - fallback path
+    import uuid as _uuid  # type: ignore
+
+
+# Expose a module-like alias so callers can use: uuid.uuid4()
+uuid = _uuid
+
+
+def uuid4():
+    """Return a UUID4 using the selected backend."""
+    return uuid.uuid4()

litellm/litellm_core_utils/litellm_logging.py

@@ -26,7 +26,6 @@
     cast,
 )
 
-import fastuuid as uuid
 from httpx import Response
 from pydantic import BaseModel
 
@@ -38,6 +37,7 @@
     turn_off_message_logging,
 )
 from litellm._logging import _is_debugging_on, verbose_logger
+from litellm._uuid import uuid
 from litellm.batches.batch_utils import _handle_completed_batch
 from litellm.caching.caching import DualCache, InMemoryCache
 from litellm.caching.caching_handler import LLMCachingHandler

litellm/llms/bedrock/common_utils.py

@@ -774,7 +774,7 @@ def generate_unique_job_name(self, model: str, prefix: str = "litellm") -> str:
         Returns:
             Unique job name (≤ 63 characters for Bedrock compatibility)
         """
-        import fastuuid as uuid
+        from litellm._uuid import uuid
         unique_id = str(uuid.uuid4())[:8]
         # Format: {prefix}-batch-{model}-{uuid}
         # Example: litellm-batch-claude-266c398e

litellm/proxy/common_request_processing.py

@@ -14,14 +14,14 @@
     Union,
 )
 
-import fastuuid as uuid
 import httpx
 import orjson
 from fastapi import HTTPException, Request, status
 from fastapi.responses import Response, StreamingResponse
 
 import litellm
 from litellm._logging import verbose_proxy_logger
+from litellm._uuid import uuid
 from litellm.constants import (
     DD_TRACER_STREAMING_CHUNK_YIELD_RESOURCE,
     STREAM_SSE_DATA_PREFIX,

litellm/types/utils.py

@@ -13,7 +13,6 @@
     Union,
 )
 
-import fastuuid as uuid
 from aiohttp import FormData
 from openai._models import BaseModel as OpenAIObject
 from openai.types.audio.transcription_create_params import FileTypes  # type: ignore
@@ -33,6 +32,7 @@
 from typing_extensions import Callable, Dict, Required, TypedDict, override
 
 import litellm
+from litellm._uuid import uuid
 from litellm.types.llms.base import (
     BaseLiteLLMOpenAIResponseObject,
     LiteLLMPydanticObjectBase,

litellm/utils.py

@@ -40,7 +40,6 @@
 
 import aiohttp
 import dotenv
-import fastuuid as uuid
 import httpx
 import openai
 import tiktoken
@@ -59,6 +58,7 @@
 import litellm.litellm_core_utils.json_validation_rule
 import litellm.llms
 import litellm.llms.gemini
+from litellm._uuid import uuid
 from litellm.caching._internal_lru_cache import lru_cache_wrapper
 from litellm.caching.caching import DualCache
 from litellm.caching.caching_handler import CachingHandlerResponse, LLMCachingHandler

poetry.lock

@@ -20,7 +20,6 @@ Documentation = "https://docs.litellm.ai"
 
 [tool.poetry.dependencies]
 python = ">=3.8.1,<4.0, !=3.9.7"
-fastuuid = ">=0.12.0"
 httpx = ">=0.23.0"
 openai = ">=1.99.5"
 python-dotenv = ">=0.2.0"
@@ -34,6 +33,7 @@ pydantic = "^2.5.0"
 jsonschema = "^4.22.0"
 pondpond = "^1.4.1"
 numpydoc = {version = "*", optional = true} # used in utils.py
+fastuuid = {version = ">=0.12.0", optional = true}
 
 uvicorn = {version = "^0.29.0", optional = true}
 uvloop = {version = "^0.21.0", optional = true, markers="sys_platform != 'win32'"}
@@ -93,6 +93,7 @@ proxy = [
     "litellm-enterprise",
     "rich",
     "polars",
+    "fastuuid",
 ]
 
 extra_proxy = [
@@ -115,6 +116,7 @@ semantic-router = ["semantic-router"]
 
 mlflow = ["mlflow"]
 
+
 [tool.isort]
 profile = "black"
 

pyproject.toml

@@ -0,0 +1,87 @@
+import ast
+import os
+from typing import List, Dict, Any
+
+
+ALLOWED_FILE = os.path.normpath("litellm/_uuid.py")
+
+
+def _to_module_path(relative_path: str) -> str:
+    module = os.path.splitext(relative_path)[0].replace(os.sep, ".")
+    if module.endswith(".__init__"):
+        return module[: -len(".__init__")]
+    return module
+
+
+def _find_fastuuid_imports_in_file(
+    file_path: str, base_dir: str
+) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            source = f.read()
+        tree = ast.parse(source, filename=file_path)
+    except Exception:
+        return results
+
+    relative = os.path.normpath(os.path.relpath(file_path, base_dir))
+    if relative == ALLOWED_FILE:
+        return results
+
+    module = _to_module_path(relative)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "fastuuid":
+                    results.append(
+                        {
+                            "file": relative,
+                            "line": getattr(node, "lineno", 0),
+                            "import": f"import {alias.name}",
+                            "module": module,
+                        }
+                    )
+        elif isinstance(node, ast.ImportFrom) and node.module == "fastuuid":
+            names = ", ".join([a.name for a in node.names])
+            results.append(
+                {
+                    "file": relative,
+                    "line": getattr(node, "lineno", 0),
+                    "import": f"from fastuuid import {names}",
+                    "module": module,
+                }
+            )
+
+    return results
+
+
+def scan_directory_for_fastuuid(base_dir: str) -> List[Dict[str, Any]]:
+    violations: List[Dict[str, Any]] = []
+    scan_root = os.path.join(base_dir, "litellm")
+    for root, _, files in os.walk(scan_root):
+        for filename in files:
+            if filename.endswith(".py"):
+                file_path = os.path.join(root, filename)
+                violations.extend(_find_fastuuid_imports_in_file(file_path, base_dir))
+    return violations
+
+
+def main() -> None:
+    base_dir = "."  # tests run from repo root in CI
+    violations = scan_directory_for_fastuuid(base_dir)
+    if violations:
+        print(
+            "\n🚨 fastuuid must only be imported inside litellm/_uuid.py. Found violations:"
+        )
+        for v in violations:
+            print(f"* {v['module']} ({v['file']}:{v['line']}) -> {v['import']}")
+        print("\n")
+        raise Exception(
+            "Found fastuuid imports outside litellm/_uuid.py. Use litellm._uuid.uuid or litellm._uuid.uuid4 instead."
+        )
+    else:
+        print("✅ No invalid fastuuid imports found.")
+
+
+if __name__ == "__main__":
+    main()