refactor: improve multimodal file handling architecture

- Make crewai_files an optional dependency with graceful fallbacks
- Move file formatting from executor to LLM layer (_process_message_files)
- Add files field to LLMMessage type for cleaner message passing
- Add cache_control to Anthropic content blocks for prompt caching
- Clean up formatters: static methods for OpenAI/Gemini, proper error handling
- Remove unused ContentFormatter protocol
- Move test fixtures to lib/crewai-files/tests/fixtures
- Add Azure and Bedrock multimodal integration tests
- Fix mypy errors in crew_agent_executor.py

lib/crewai-files/src/crewai_files/formatting/anthropic.py

@@ -8,7 +8,8 @@ from typing import Any
 from crewai_files.core.resolved import (
     FileReference,
     InlineBase64,
-    ResolvedFile,
+    InlineBytes,
+    ResolvedFileType,
     UrlReference,
 )
 from crewai_files.core.types import FileInput
@@ -20,7 +21,7 @@ class AnthropicFormatter:
     def format_block(
         self,
         file: FileInput,
-        resolved: ResolvedFile,
+        resolved: ResolvedFileType,
     ) -> dict[str, Any] | None:
         """Format a resolved file into an Anthropic content block.
 
@@ -43,6 +44,7 @@ class AnthropicFormatter:
                     "type": "file",
                     "file_id": resolved.file_id,
                 },
+                "cache_control": {"type": "ephemeral"},
             }
 
         if isinstance(resolved, UrlReference):
@@ -52,6 +54,7 @@ class AnthropicFormatter:
                     "type": "url",
                     "url": resolved.url,
                 },
+                "cache_control": {"type": "ephemeral"},
             }
 
         if isinstance(resolved, InlineBase64):
@@ -62,17 +65,21 @@ class AnthropicFormatter:
                     "media_type": resolved.content_type,
                     "data": resolved.data,
                 },
+                "cache_control": {"type": "ephemeral"},
             }
 
-        data = base64.b64encode(file.read()).decode("ascii")
-        return {
-            "type": block_type,
-            "source": {
-                "type": "base64",
-                "media_type": content_type,
-                "data": data,
-            },
-        }
+        if isinstance(resolved, InlineBytes):
+            return {
+                "type": block_type,
+                "source": {
+                    "type": "base64",
+                    "media_type": resolved.content_type,
+                    "data": base64.b64encode(resolved.data).decode("ascii"),
+                },
+                "cache_control": {"type": "ephemeral"},
+            }
+
+        raise TypeError(f"Unexpected resolved type: {type(resolved).__name__}")
 
     @staticmethod
     def _get_block_type(content_type: str) -> str | None:

lib/crewai-files/src/crewai_files/formatting/api.py

@@ -274,4 +274,8 @@ def _format_block(
     """
     if isinstance(formatter, BedrockFormatter):
         return formatter.format_block(file_input, resolved, name=name)
-    return formatter.format_block(file_input, resolved)
+    if isinstance(formatter, AnthropicFormatter):
+        return formatter.format_block(file_input, resolved)
+    if isinstance(formatter, (OpenAIFormatter, GeminiFormatter)):
+        return formatter.format_block(resolved)
+    raise TypeError(f"Unknown formatter type: {type(formatter).__name__}")

lib/crewai-files/src/crewai_files/formatting/base.py

@@ -1,28 +0,0 @@
-"""Base formatter protocol for provider-specific content blocks."""
-
-from __future__ import annotations
-
-from typing import Any, Protocol
-
-from crewai_files.core.resolved import ResolvedFile
-from crewai_files.core.types import FileInput
-
-
-class ContentFormatter(Protocol):
-    """Protocol for formatting resolved files into provider content blocks."""
-
-    def format_block(
-        self,
-        file: FileInput,
-        resolved: ResolvedFile,
-    ) -> dict[str, Any] | None:
-        """Format a resolved file into a provider-specific content block.
-
-        Args:
-            file: Original file input with metadata.
-            resolved: Resolved file (FileReference, InlineBase64, etc.).
-
-        Returns:
-            Content block dict or None if file type not supported.
-        """
-        ...

lib/crewai-files/src/crewai_files/formatting/bedrock.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
+import base64
 from typing import Any
 
 from crewai_files.core.resolved import (
     FileReference,
+    InlineBase64,
     InlineBytes,
-    ResolvedFile,
+    ResolvedFileType,
+    UrlReference,
 )
 from crewai_files.core.types import FileInput
 
@@ -49,7 +52,7 @@ class BedrockFormatter:
     def format_block(
         self,
         file: FileInput,
-        resolved: ResolvedFile,
+        resolved: ResolvedFileType,
         name: str | None = None,
     ) -> dict[str, Any] | None:
         """Format a resolved file into a Bedrock content block.
@@ -64,15 +67,24 @@ class BedrockFormatter:
         """
         content_type = file.content_type
 
-        if isinstance(resolved, FileReference) and resolved.file_uri:
+        if isinstance(resolved, FileReference):
+            if not resolved.file_uri:
+                raise ValueError("Bedrock requires file_uri for FileReference (S3 URI)")
             return self._format_s3_block(content_type, resolved.file_uri, name)
 
         if isinstance(resolved, InlineBytes):
-            file_bytes = resolved.data
-        else:
-            file_bytes = file.read()
+            return self._format_bytes_block(content_type, resolved.data, name)
 
-        return self._format_bytes_block(content_type, file_bytes, name)
+        if isinstance(resolved, InlineBase64):
+            file_bytes = base64.b64decode(resolved.data)
+            return self._format_bytes_block(content_type, file_bytes, name)
+
+        if isinstance(resolved, UrlReference):
+            raise ValueError(
+                "Bedrock does not support URL references - resolve to bytes first"
+            )
+
+        raise TypeError(f"Unexpected resolved type: {type(resolved).__name__}")
 
     def _format_s3_block(
         self,

lib/crewai-files/src/crewai_files/formatting/gemini.py

@@ -8,32 +8,31 @@ from typing import Any
 from crewai_files.core.resolved import (
     FileReference,
     InlineBase64,
-    ResolvedFile,
+    InlineBytes,
+    ResolvedFileType,
     UrlReference,
 )
-from crewai_files.core.types import FileInput
 
 
 class GeminiFormatter:
     """Formats resolved files into Gemini content blocks."""
 
-    def format_block(
-        self,
-        file: FileInput,
-        resolved: ResolvedFile,
-    ) -> dict[str, Any] | None:
+    @staticmethod
+    def format_block(resolved: ResolvedFileType) -> dict[str, Any]:
         """Format a resolved file into a Gemini content block.
 
         Args:
-            file: Original file input with metadata.
             resolved: Resolved file.
 
         Returns:
-            Content block dict or None if not supported.
-        """
-        content_type = file.content_type
+            Content block dict.
 
-        if isinstance(resolved, FileReference) and resolved.file_uri:
+        Raises:
+            TypeError: If resolved type is not supported.
+        """
+        if isinstance(resolved, FileReference):
+            if not resolved.file_uri:
+                raise ValueError("Gemini requires file_uri for FileReference")
             return {
                 "fileData": {
                     "mimeType": resolved.content_type,
@@ -44,7 +43,7 @@ class GeminiFormatter:
         if isinstance(resolved, UrlReference):
             return {
                 "fileData": {
-                    "mimeType": content_type,
+                    "mimeType": resolved.content_type,
                     "fileUri": resolved.url,
                 }
             }
@@ -57,10 +56,12 @@ class GeminiFormatter:
                 }
             }
 
-        data = base64.b64encode(file.read()).decode("ascii")
-        return {
-            "inlineData": {
-                "mimeType": content_type,
-                "data": data,
+        if isinstance(resolved, InlineBytes):
+            return {
+                "inlineData": {
+                    "mimeType": resolved.content_type,
+                    "data": base64.b64encode(resolved.data).decode("ascii"),
+                }
             }
-        }
+
+        raise TypeError(f"Unexpected resolved type: {type(resolved).__name__}")

lib/crewai-files/src/crewai_files/formatting/openai.py

@@ -8,31 +8,28 @@ from typing import Any
 from crewai_files.core.resolved import (
     FileReference,
     InlineBase64,
-    ResolvedFile,
+    InlineBytes,
+    ResolvedFileType,
     UrlReference,
 )
-from crewai_files.core.types import FileInput
 
 
 class OpenAIFormatter:
     """Formats resolved files into OpenAI content blocks."""
 
-    def format_block(
-        self,
-        file: FileInput,
-        resolved: ResolvedFile,
-    ) -> dict[str, Any] | None:
+    @staticmethod
+    def format_block(resolved: ResolvedFileType) -> dict[str, Any]:
         """Format a resolved file into an OpenAI content block.
 
         Args:
-            file: Original file input with metadata.
             resolved: Resolved file.
 
         Returns:
-            Content block dict or None if not supported.
-        """
-        content_type = file.content_type
+            Content block dict.
 
+        Raises:
+            TypeError: If resolved type is not supported.
+        """
         if isinstance(resolved, FileReference):
             return {
                 "type": "file",
@@ -53,8 +50,11 @@ class OpenAIFormatter:
                 },
             }
 
-        data = base64.b64encode(file.read()).decode("ascii")
-        return {
-            "type": "image_url",
-            "image_url": {"url": f"data:{content_type};base64,{data}"},
-        }
+        if isinstance(resolved, InlineBytes):
+            data = base64.b64encode(resolved.data).decode("ascii")
+            return {
+                "type": "image_url",
+                "image_url": {"url": f"data:{resolved.content_type};base64,{data}"},
+            }
+
+        raise TypeError(f"Unexpected resolved type: {type(resolved).__name__}")