Implementation:BerriAI Litellm Managed Files

Attribute	Value
Sources	enterprise/litellm_enterprise/proxy/hooks/managed_files.py
Domains	File Management, Proxy Hooks, Batches, Fine-Tuning, Enterprise
Last Updated	2026-02-15 16:00 GMT

Overview

_PROXY_LiteLLMManagedFiles is a proxy hook that provides unified file ID management across multiple LLM providers, enabling transparent file operations (create, retrieve, list, delete, content) with cross-model file mappings stored in both cache and database.

Description

This class extends both CustomLogger and BaseFileEndpoints to intercept file-related operations in the LiteLLM proxy. It manages a unified file ID system where a single base64-encoded file ID maps to provider-specific file IDs across multiple models.

Core Capabilities:

• Unified File IDs -- Creates base64-encoded IDs that encode content type, UUID, target model names, provider file ID, and model ID.
• Cross-Model File Creation -- Creates the same file across multiple target models and stores the mapping.
• Access Control -- Enforces per-user file access based on the created_by field.
• Pre-Call Hook -- Intercepts completion, responses, batch, fine-tuning, and file operations to resolve unified IDs to provider-specific IDs.
• Post-Call Hook -- Transforms batch and fine-tuning responses to use unified IDs and stores object mappings.
• Deployment Filtering -- Filters healthy deployments to only those that have the relevant file available.
• Storage Backend Integration -- Supports converting files stored in external storage backends to base64 for providers that require it (e.g., Vertex AI/Gemini).

Supported Call Types:

• completion / acompletion -- Resolves file IDs in message content
• aresponses / responses -- Resolves file IDs in responses API input and tools
• afile_content / afile_delete / afile_retrieve -- File CRUD operations
• acreate_batch / aretrieve_batch / acancel_batch -- Batch operations
• acreate_fine_tuning_job / aretrieve_fine_tuning_job / acancel_fine_tuning_job -- Fine-tuning operations

Usage

This hook is instantiated by the proxy server and registered in the proxy logging pipeline. It requires an InternalUsageCache and a PrismaClient for cache and database operations.

Code Reference

Source Location

enterprise/litellm_enterprise/proxy/hooks/managed_files.py

Signature

class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
    def __init__(self, internal_usage_cache: InternalUsageCache, prisma_client: PrismaClient): ...

    async def store_unified_file_id(self, file_id, file_object, litellm_parent_otel_span, model_mappings, user_api_key_dict): ...
    async def get_unified_file_id(self, file_id, litellm_parent_otel_span) -> Optional[LiteLLM_ManagedFileTable]: ...
    async def delete_unified_file_id(self, file_id, litellm_parent_otel_span) -> OpenAIFileObject: ...
    async def acreate_file(self, create_file_request, llm_router, target_model_names_list, litellm_parent_otel_span, user_api_key_dict) -> OpenAIFileObject: ...
    async def afile_retrieve(self, file_id, litellm_parent_otel_span, llm_router=None) -> OpenAIFileObject: ...
    async def afile_delete(self, file_id, litellm_parent_otel_span, llm_router, **data) -> OpenAIFileObject: ...
    async def afile_content(self, file_id, litellm_parent_otel_span, llm_router, **data) -> HttpxBinaryResponseContent: ...
    async def async_pre_call_hook(self, user_api_key_dict, cache, data, call_type) -> Union[Exception, str, Dict, None]: ...
    async def async_post_call_success_hook(self, data, user_api_key_dict, response) -> Any: ...
    async def async_filter_deployments(self, model, healthy_deployments, messages, request_kwargs, parent_otel_span) -> List[Dict]: ...

Import

from litellm_enterprise.proxy.hooks.managed_files import _PROXY_LiteLLMManagedFiles

I/O Contract

Inputs

Parameter	Type	Description
internal_usage_cache	InternalUsageCache	Cache for storing file ID mappings.
prisma_client	PrismaClient	Database client for persistent storage of file and object tables.
create_file_request	CreateFileRequest	File creation parameters (file content, purpose).
target_model_names_list	List[str]	Models to create the file across.
user_api_key_dict	UserAPIKeyAuth	Authentication info for access control.

Outputs

Output	Type	Description
Unified file object	OpenAIFileObject	OpenAI-compatible file object with base64-encoded unified ID.
Model file ID mapping	Dict[str, Dict[str, str]]	Mapping of unified_file_id -> model_id -> provider_file_id.

Usage Examples

from litellm_enterprise.proxy.hooks.managed_files import _PROXY_LiteLLMManagedFiles

managed_files = _PROXY_LiteLLMManagedFiles(
    internal_usage_cache=internal_usage_cache,
    prisma_client=prisma_client,
)

# Create a file across multiple models
file_obj = await managed_files.acreate_file(
    create_file_request={"file": file_content, "purpose": "batch"},
    llm_router=router,
    target_model_names_list=["gpt-4", "claude-3-opus"],
    litellm_parent_otel_span=None,
    user_api_key_dict=user_key,
)

Related Pages

• BerriAI_Litellm_Check_Batch_Cost -- Polls managed objects to track batch job costs
• BerriAI_Litellm_Managed_Vector_Stores -- Managed vector store hook with similar patterns
• BerriAI_Litellm_Check_Responses_Cost -- Polls managed objects for response cost tracking