abstractcore 2.4.2__py3-none-any.whl → 2.4.4__py3-none-any.whl

abstractcore/server/app.py

@@ -1,31 +1,51 @@
 """
-AbstractCore Server - Clean Architecture with Universal Tool Call Syntax Support
+AbstractCore Server - Universal LLM Gateway with Media Processing
 
 A focused FastAPI server that provides OpenAI-compatible endpoints with support for
-multiple agent formats through the enhanced syntax rewriter.
+multiple agent formats, tool calling, and comprehensive media processing capabilities.
 
 Key Features:
 - Universal tool call syntax conversion (OpenAI, Codex, Qwen3, LLaMA3, custom)
 - Auto-detection of target agent format
+- Media processing for images, documents, and data files
+- OpenAI Vision API compatible format support
+- Streaming responses with media attachments
 - Clean delegation to AbstractCore
 - Proper ReAct loop support
 - Comprehensive model listing from AbstractCore providers
+
+Media Support:
+- Images: PNG, JPEG, GIF, WEBP, BMP, TIFF
+- Documents: PDF, DOCX, XLSX, PPTX
+- Data: CSV, TSV, JSON, XML, TXT, MD
+- Size limits: 10MB per file, 32MB total per request
+- Both base64 data URLs and HTTP URLs supported
 """
 
 import os
 import json
 import time
 import uuid
-from typing import List, Dict, Any, Optional, Literal, Union, Iterator
+import base64
+import tempfile
+import urllib.request
+import urllib.parse
+import argparse
+import sys
+import logging
+from typing import List, Dict, Any, Optional, Literal, Union, Iterator, Tuple, Annotated
 from enum import Enum
-from fastapi import FastAPI, HTTPException, Request, Query
-from fastapi.responses import StreamingResponse
+from fastapi import FastAPI, HTTPException, Request, Query, Body
+from fastapi.responses import StreamingResponse, JSONResponse
 from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel, Field
+from fastapi.exceptions import RequestValidationError
+from pydantic import BaseModel, Field, ValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from ..core.factory import create_llm
 from ..utils.structured_logging import get_logger, configure_logging
 from ..utils.version import __version__
+from ..utils.message_preprocessor import MessagePreprocessor
 # Removed simple_model_discovery import - now using provider methods directly
 from ..tools.syntax_rewriter import (
     ToolCallSyntaxRewriter,
@@ -40,21 +60,52 @@ from ..tools.syntax_rewriter import (
 # Configuration
 # ============================================================================
 
-# Configure structured logging
+# Initialize with default logging configuration (can be overridden later)
 debug_mode = os.getenv("ABSTRACTCORE_DEBUG", "false").lower() == "true"
+
+# Initial logging setup (will be reconfigured if --debug is used)
+# Check environment variable for debug mode
+initial_console_level = logging.DEBUG if debug_mode else logging.INFO
 configure_logging(
-    console_level="DEBUG" if debug_mode else "INFO",
-    file_level="DEBUG",
+    console_level=initial_console_level,
+    file_level=logging.DEBUG,
     log_dir="logs",
     verbatim_enabled=True,
     console_json=False,
     file_json=True
 )
 
-# Create FastAPI app
+# Get initial logger
+logger = get_logger("server")
+
+# Log initial startup with debug mode status
+logger.info("🚀 AbstractCore Server Initializing", version=__version__, debug_mode=debug_mode)
+
+def reconfigure_for_debug():
+    """Reconfigure logging for debug mode when --debug flag is used."""
+    global debug_mode, logger
+
+    debug_mode = True
+
+    # Reconfigure with debug levels
+    configure_logging(
+        console_level=logging.DEBUG,
+        file_level=logging.DEBUG,
+        log_dir="logs",
+        verbatim_enabled=True,
+        console_json=False,
+        file_json=True
+    )
+
+    # Update logger instance
+    logger = get_logger("server")
+
+    return logger
+
+# Create FastAPI app (will be initialized after argument parsing)
 app = FastAPI(
     title="AbstractCore Server",
-    description="Universal LLM Gateway with Multi-Agent Tool Call Syntax Support",
+    description="Universal LLM Gateway with Multi-Agent Tool Call Syntax Support and Media Processing",
     version=__version__
 )
 
@@ -66,9 +117,145 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
-# Get logger
-logger = get_logger("server")
-logger.info("🚀 AbstractCore Server Starting", version=__version__, debug_mode=debug_mode)
+# ============================================================================
+# Enhanced Error Handling and Logging Middleware
+# ============================================================================
+
+@app.middleware("http")
+async def debug_logging_middleware(request: Request, call_next):
+    """Enhanced logging middleware for debug mode."""
+    start_time = time.time()
+
+    # Log request details in debug mode
+    if debug_mode:
+        logger.debug(
+            "📥 HTTP Request",
+            method=request.method,
+            url=str(request.url),
+            headers=dict(request.headers),
+            client=request.client.host if request.client else "unknown"
+        )
+
+    response = await call_next(request)
+
+    process_time = time.time() - start_time
+
+    # Log response details
+    log_data = {
+        "method": request.method,
+        "url": str(request.url),
+        "status_code": response.status_code,
+        "process_time_ms": round(process_time * 1000, 2)
+    }
+
+    if response.status_code >= 400:
+        logger.error("❌ HTTP Error Response", **log_data)
+    elif debug_mode:
+        logger.debug("📤 HTTP Response", **log_data)
+    else:
+        logger.info("✅ HTTP Request", **log_data)
+
+    return response
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Enhanced handler for 422 validation errors with detailed logging."""
+    error_details = []
+    for error in exc.errors():
+        error_details.append({
+            "field": " -> ".join(str(loc) for loc in error["loc"]),
+            "message": error["msg"],
+            "type": error["type"],
+            "input": error.get("input")
+        })
+
+    # Log detailed validation error information
+    logger.error(
+        "🔴 Request Validation Error (422)",
+        method=request.method,
+        url=str(request.url),
+        error_count=len(error_details),
+        errors=error_details,
+        client=request.client.host if request.client else "unknown"
+    )
+
+    # In debug mode, also try to log the request body if possible
+    if debug_mode:
+        try:
+            # Try to get the request body for debugging
+            body = await request.body()
+            if body:
+                try:
+                    import json
+                    body_json = json.loads(body)
+                    logger.debug(
+                        "📋 Request Body (Validation Error)",
+                        body=body_json
+                    )
+                except json.JSONDecodeError:
+                    logger.debug(
+                        "📋 Request Body (Validation Error)",
+                        body_text=body.decode('utf-8', errors='replace')[:1000]  # Limit to 1000 chars
+                    )
+        except Exception as e:
+            logger.debug(f"Could not read request body for debugging: {e}")
+
+    # Return detailed error response
+    return JSONResponse(
+        status_code=422,
+        content={
+            "error": {
+                "message": "Request validation failed",
+                "type": "validation_error",
+                "details": error_details
+            }
+        }
+    )
+
+@app.exception_handler(StarletteHTTPException)
+async def http_exception_handler(request: Request, exc: StarletteHTTPException):
+    """Enhanced handler for HTTP exceptions with detailed logging."""
+    logger.error(
+        "🔴 HTTP Exception",
+        method=request.method,
+        url=str(request.url),
+        status_code=exc.status_code,
+        detail=str(exc.detail),
+        client=request.client.host if request.client else "unknown"
+    )
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": {
+                "message": str(exc.detail),
+                "type": "http_error"
+            }
+        }
+    )
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request: Request, exc: Exception):
+    """Handler for unexpected exceptions with detailed logging."""
+    logger.error(
+        "💥 Unexpected Server Error",
+        method=request.method,
+        url=str(request.url),
+        exception_type=type(exc).__name__,
+        exception_message=str(exc),
+        client=request.client.host if request.client else "unknown",
+        exc_info=True  # This will include the full stack trace
+    )
+
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": {
+                "message": "Internal server error",
+                "type": "server_error"
+            }
+        }
+    )
 
 # ============================================================================
 # Model Type Detection
@@ -121,19 +308,91 @@ def get_models_from_provider(provider_name: str) -> List[str]:
         logger.debug(f"Failed to get models from provider {provider_name}: {e}")
         return []
 
+# ============================================================================
+# OpenAI Responses API Models (100% Compatible)
+# ============================================================================
+
+class OpenAIInputContent(BaseModel):
+    """OpenAI Responses API content item"""
+    type: Literal["input_text", "input_file"] = Field(
+        description="Content type - 'input_text' for text or 'input_file' for files"
+    )
+    text: Optional[str] = Field(
+        default=None,
+        description="Text content (required when type='input_text')"
+    )
+    file_url: Optional[str] = Field(
+        default=None,
+        description="Direct file URL (required when type='input_file')"
+    )
+
+class OpenAIResponsesInput(BaseModel):
+    """OpenAI Responses API input message"""
+    role: Literal["user"] = Field(
+        description="Message role (OpenAI responses only supports 'user')"
+    )
+    content: List[OpenAIInputContent] = Field(
+        description="Array of input content items"
+    )
+
+class OpenAIResponsesRequest(BaseModel):
+    """OpenAI Responses API request format (100% compatible)"""
+    model: str = Field(
+        description="Model identifier",
+        example="gpt-4o"
+    )
+    input: List[OpenAIResponsesInput] = Field(
+        description="Array of input messages"
+    )
+    max_tokens: Optional[int] = Field(
+        default=None,
+        description="Maximum tokens to generate"
+    )
+    temperature: Optional[float] = Field(
+        default=None,
+        description="Sampling temperature"
+    )
+    top_p: Optional[float] = Field(
+        default=None,
+        description="Top-p sampling"
+    )
+    stream: Optional[bool] = Field(
+        default=False,
+        description="Enable streaming (false by default, set to true for real-time responses)"
+    )
+
 # ============================================================================
 # Models
 # ============================================================================
 
+class ContentItem(BaseModel):
+    """Individual content item within a message (OpenAI Vision API format with file support)"""
+    type: Literal["text", "image_url", "file"] = Field(
+        description="Content type - 'text' for text content, 'image_url' for images, or 'file' for file attachments"
+    )
+    text: Optional[str] = Field(
+        default=None,
+        description="Text content (required when type='text')"
+    )
+    image_url: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Image URL object (required when type='image_url'). Should contain 'url' field with base64 data URL or HTTP(S) URL"
+    )
+    file_url: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="File URL object (required when type='file'). Should contain 'url' field with HTTP(S) URL, local path, or base64 data URL"
+    )
+
 class ChatMessage(BaseModel):
-    """OpenAI-compatible message format"""
+    """Enhanced OpenAI-compatible message format with media support"""
     role: Literal["system", "user", "assistant", "tool"] = Field(
         description="The role of the message author. One of 'system', 'user', 'assistant', or 'tool'.",
         example="user"
     )
-    content: Optional[str] = Field(
+    content: Optional[Union[str, List[ContentItem]]] = Field(
         default=None,
-        description="The contents of the message. Can be null for assistant messages with tool calls.",
+        description="Message content - can be a string or array of content objects for multimodal messages. "
+                   "For multimodal messages, use array format with text, image_url, and file objects.",
         example="What is the capital of France?"
     )
     tool_call_id: Optional[str] = Field(
@@ -260,21 +519,209 @@ class ChatCompletionRequest(BaseModel):
     
     class Config:
         schema_extra = {
-            "example": {
-                "model": "openai/gpt-4",
-                "messages": [
-                    {
-                        "role": "system",
-                        "content": "You are a helpful assistant."
-                    },
-                    {
-                        "role": "user",
-                        "content": "What is the capital of France?"
+            "examples": {
+                "basic_text": {
+                    "summary": "Basic Text Chat",
+                    "description": "Simple text-based conversation",
+                    "value": {
+                        "model": "openai/gpt-4",
+                        "messages": [
+                            {
+                                "role": "system",
+                                "content": "You are a helpful assistant."
+                            },
+                            {
+                                "role": "user",
+                                "content": "What is the capital of France?"
+                            }
+                        ],
+                        "temperature": 0.7,
+                        "max_tokens": 150,
+                        "stream": False
+                    }
+                },
+                "vision_image": {
+                    "summary": "Image Analysis",
+                    "description": "Analyze images using vision-capable models with OpenAI Vision API format",
+                    "value": {
+                        "model": "ollama/qwen2.5vl:7b",
+                        "messages": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {
+                                        "type": "text",
+                                        "text": "What's in this image?"
+                                    },
+                                    {
+                                        "type": "image_url",
+                                        "image_url": {
+                                            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k="
+                                        }
+                                    }
+                                ]
+                            }
+                        ],
+                        "temperature": 0.7,
+                        "max_tokens": 200
+                    }
+                },
+                "document_analysis": {
+                    "summary": "Document Analysis",
+                    "description": "Process documents (PDF, CSV, Excel, etc.) with file attachments",
+                    "value": {
+                        "model": "lmstudio/qwen/qwen3-next-80b",
+                        "messages": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {
+                                        "type": "text",
+                                        "text": "Analyze this CSV file and calculate the total sales"
+                                    },
+                                    {
+                                        "type": "image_url",
+                                        "image_url": {
+                                            "url": "data:text/csv;base64,RGF0ZSxQcm9kdWN0LFNhbGVzCjIwMjQtMDEtMDEsUHJvZHVjdCBBLDEwMDAwCjIwMjQtMDEtMDIsUHJvZHVjdCBCLDE1MDAwCjIwMjQtMDEtMDMsUHJvZHVjdCBDLDI1MDAw"
+                                        }
+                                    }
+                                ]
+                            }
+                        ],
+                        "temperature": 0.3,
+                        "max_tokens": 300
+                    }
+                },
+                "mixed_media": {
+                    "summary": "Mixed Media Analysis",
+                    "description": "Process multiple file types in a single request",
+                    "value": {
+                        "model": "ollama/qwen2.5vl:7b",
+                        "messages": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {
+                                        "type": "text",
+                                        "text": "Compare this chart image with the data in this PDF report"
+                                    },
+                                    {
+                                        "type": "image_url",
+                                        "image_url": {
+                                            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
+                                        }
+                                    },
+                                    {
+                                        "type": "image_url",
+                                        "image_url": {
+                                            "url": "data:application/pdf;base64,JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPJ4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQo+PgplbmRvYmoKeHJlZgowIDQKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDQKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjE5NQolJUVPRgo="
+                                        }
+                                    }
+                                ]
+                            }
+                        ],
+                        "temperature": 0.5,
+                        "max_tokens": 500,
+                        "stream": False
+                    }
+                },
+                "tools_with_media": {
+                    "summary": "Tools + Media",
+                    "description": "Combine tool usage with file attachments for complex workflows",
+                    "value": {
+                        "model": "openai/gpt-4",
+                        "messages": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {
+                                        "type": "text",
+                                        "text": "Analyze this financial data and create a summary chart"
+                                    },
+                                    {
+                                        "type": "image_url",
+                                        "image_url": {
+                                            "url": "data:text/csv;base64,Q29tcGFueSxRMSxRMixRMyxRNApBY21lIEluYywyMDAsMjUwLDMwMCwzNTAKVGVjaCBDb3JwLDE1MCwyMDAsMjUwLDMwMApCaXogTHRkLDEwMCwxMjAsMTQwLDE2MA=="
+                                        }
+                                    }
+                                ]
+                            }
+                        ],
+                        "temperature": 0.7,
+                        "max_tokens": 2048,
+                        "stream": False,
+                        "tools": [
+                            {
+                                "type": "function",
+                                "function": {
+                                    "name": "create_chart",
+                                    "description": "Create a chart from data",
+                                    "parameters": {
+                                        "type": "object",
+                                        "properties": {
+                                            "chart_type": {"type": "string"},
+                                            "data": {"type": "array"}
+                                        }
+                                    }
+                                }
+                            }
+                        ],
+                        "tool_choice": "auto"
                     }
-                ],
-                "temperature": 0.7,
-                "max_tokens": 150,
-                "stream": False
+                },
+                "complete_request": {
+                    "summary": "Complete Request with Media",
+                    "description": "Full example showing all possible fields with file attachment",
+                    "value": {
+                        "model": "openai/gpt-4",
+                        "messages": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {
+                                        "type": "text",
+                                        "text": "Analyze this CSV file and provide insights"
+                                    },
+                                    {
+                                        "type": "image_url",
+                                        "image_url": {
+                                            "url": "data:text/csv;base64,RGF0ZSxQcm9kdWN0LFNhbGVzCjIwMjQtMDEtMDEsUHJvZHVjdCBBLDEwMDAwCjIwMjQtMDEtMDIsUHJvZHVjdCBCLDE1MDAwCjIwMjQtMDEtMDMsUHJvZHVjdCBDLDI1MDAw"
+                                        }
+                                    }
+                                ],
+                                "tool_call_id": None,
+                                "tool_calls": None,
+                                "name": "DataAnalyst"
+                            }
+                        ],
+                        "temperature": 0.7,
+                        "max_tokens": 2048,
+                        "top_p": 1,
+                        "stream": False,
+                        "tools": [
+                            {
+                                "type": "function",
+                                "function": {
+                                    "name": "analyze_data",
+                                    "description": "Analyze data and generate insights",
+                                    "parameters": {
+                                        "type": "object",
+                                        "properties": {
+                                            "analysis_type": {"type": "string"},
+                                            "metrics": {"type": "array"}
+                                        }
+                                    }
+                                }
+                            }
+                        ],
+                        "tool_choice": "auto",
+                        "stop": ["END"],
+                        "seed": 12345,
+                        "frequency_penalty": 0.0,
+                        "presence_penalty": 0.0,
+                        "agent_format": "auto"
+                    }
+                }
             }
         }
 
@@ -324,6 +771,117 @@ class EmbeddingRequest(BaseModel):
             }
         }
 
+# ============================================================================
+# Union Request Model for /v1/responses endpoint
+# ============================================================================
+
+class ResponsesAPIRequest(BaseModel):
+    """
+    Union request model for /v1/responses endpoint supporting both OpenAI and legacy formats.
+
+    The endpoint automatically detects the format based on the presence of 'input' vs 'messages' field.
+    """
+    class Config:
+        schema_extra = {
+            "oneOf": [
+                {
+                    "title": "OpenAI Responses API Format",
+                    "description": "OpenAI-compatible responses format with input_file support",
+                    "$ref": "#/components/schemas/OpenAIResponsesRequest"
+                },
+                {
+                    "title": "Legacy Format (ChatCompletionRequest)",
+                    "description": "Backward-compatible format using messages array",
+                    "$ref": "#/components/schemas/ChatCompletionRequest"
+                }
+            ],
+            "examples": {
+                "openai_format": {
+                    "summary": "OpenAI Responses API Format",
+                    "description": "Use input array with input_text and input_file objects",
+                    "value": {
+                        "model": "gpt-4o",
+                        "input": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "input_text", "text": "Analyze this document"},
+                                    {"type": "input_file", "file_url": "https://example.com/doc.pdf"}
+                                ]
+                            }
+                        ],
+                        "stream": False
+                    }
+                },
+                "legacy_format": {
+                    "summary": "Legacy Format (Backward Compatible)",
+                    "description": "Use messages array like standard chat completions",
+                    "value": {
+                        "model": "openai/gpt-4",
+                        "messages": [
+                            {"role": "user", "content": "Tell me a story"}
+                        ],
+                        "stream": False
+                    }
+                }
+            }
+        }
+
+# ============================================================================
+# OpenAI Responses API Compatibility
+# ============================================================================
+
+def convert_openai_responses_to_chat_completion(openai_request: OpenAIResponsesRequest) -> ChatCompletionRequest:
+    """
+    Convert OpenAI Responses API format to internal ChatCompletionRequest format.
+
+    Transforms:
+    - input -> messages
+    - input_text -> text
+    - input_file -> file with file_url
+
+    Args:
+        openai_request: OpenAI responses API request
+
+    Returns:
+        ChatCompletionRequest compatible with our internal processing
+    """
+    # Convert input messages to chat messages
+    messages = []
+
+    for input_msg in openai_request.input:
+        # Build content array as list of dicts (not ContentItem objects)
+        content_items = []
+
+        for content in input_msg.content:
+            if content.type == "input_text":
+                content_items.append({
+                    "type": "text",
+                    "text": content.text
+                })
+            elif content.type == "input_file":
+                content_items.append({
+                    "type": "file",
+                    "file_url": {"url": content.file_url}  # Convert to our format
+                })
+
+        # Create chat message with list content (not ContentItem objects)
+        message_dict = {
+            "role": input_msg.role,
+            "content": content_items
+        }
+        messages.append(ChatMessage(**message_dict))
+
+    # Build ChatCompletionRequest
+    return ChatCompletionRequest(
+        model=openai_request.model,
+        messages=messages,
+        max_tokens=openai_request.max_tokens,
+        temperature=openai_request.temperature,
+        top_p=openai_request.top_p,
+        stream=openai_request.stream
+    )
+
 # ============================================================================
 # Helper Functions
 # ============================================================================
@@ -588,31 +1146,101 @@ async def list_providers():
         }
 
 @app.post("/v1/responses")
-async def create_response(request: ChatCompletionRequest, http_request: Request):
+async def create_response(
+    http_request: Request,
+    request_body: Annotated[
+        Dict[str, Any],
+        Body(
+            ...,
+            examples={
+                "openai_format": {
+                    "summary": "OpenAI Responses API Format",
+                    "description": "Use input array with input_text and input_file objects",
+                    "value": {
+                        "model": "gpt-4o",
+                        "input": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "input_text", "text": "Analyze this document"},
+                                    {"type": "input_file", "file_url": "https://example.com/doc.pdf"}
+                                ]
+                            }
+                        ],
+                        "stream": False
+                    }
+                },
+                "legacy_format": {
+                    "summary": "Legacy Format (Backward Compatible)",
+                    "description": "Use messages array like standard chat completions",
+                    "value": {
+                        "model": "openai/gpt-4",
+                        "messages": [
+                            {"role": "user", "content": "Tell me a story"}
+                        ],
+                        "stream": False
+                    }
+                },
+                "file_analysis": {
+                    "summary": "Document Analysis",
+                    "description": "Analyze files using OpenAI format",
+                    "value": {
+                        "model": "openai/gpt-4",
+                        "input": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "input_text", "text": "What's the key information in this CSV?"},
+                                    {"type": "input_file", "file_url": "data:text/csv;base64,RGF0ZSxQcm9kdWN0LFNhbGVzCjIwMjQtMDEtMDEsUHJvZHVjdCBBLDEwMDAwCjIwMjQtMDEtMDIsUHJvZHVjdCBCLDE1MDAwCjIwMjQtMDEtMDMsUHJvZHVjdCBDLDI1MDAw"}
+                                ]
+                            }
+                        ]
+                    }
+                },
+                "streaming_example": {
+                    "summary": "Streaming Response",
+                    "description": "Enable streaming for real-time responses",
+                    "value": {
+                        "model": "lmstudio/qwen/qwen3-next-80b",
+                        "input": [
+                            {
+                                "role": "user",
+                                "content": [
+                                    {"type": "input_text", "text": "Analyze the letter and provide a summary of the key points."},
+                                    {"type": "input_file", "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf"}
+                                ]
+                            }
+                        ],
+                        "stream": True
+                    }
+                }
+            }
+        )
+    ]
+):
     """
-    Create a real-time streaming response for the given chat conversation.
-    
-    This endpoint provides real-time conversation capabilities optimized for streaming interaction.
-    It's similar to OpenAI's Realtime/Responses API, automatically enabling streaming for immediate token delivery.
-    
-    **Key Features:**
-    - **Always Streams**: Streaming is automatically enabled for real-time interaction
-    - **Lower Latency**: Optimized for quick first-token delivery
-    - **Same Parameters**: Uses the same request format as `/v1/chat/completions`
-    - **Multi-Provider**: Supports all providers (OpenAI, Anthropic, Ollama, etc.)
-    
-    **Use Cases:**
-    - Real-time chat interfaces
-    - Voice-to-text streaming
-    - Live coding assistants
-    - Interactive agents
-    
-    **Differences from `/v1/chat/completions`:**
-    - Streaming is always enabled (ignores `stream: false`)
-    - Optimized for immediate response delivery
-    - Better for user-facing real-time applications
-    
-    **Example:**
+    OpenAI Responses API (100% Compatible) + Backward Compatibility
+
+    Supports both OpenAI's responses format and our legacy format for seamless migration.
+    Streaming can be enabled by setting "stream": true for real-time interaction.
+
+    **OpenAI Format (input_file support):**
+    ```json
+    {
+      "model": "gpt-4o",
+      "input": [
+        {
+          "role": "user",
+          "content": [
+            {"type": "input_text", "text": "Analyze this document"},
+            {"type": "input_file", "file_url": "https://example.com/doc.pdf"}
+          ]
+        }
+      ]
+    }
+    ```
+
+    **Legacy Format (backward compatibility):**
     ```json
     {
       "model": "openai/gpt-4",
@@ -621,24 +1249,65 @@ async def create_response(request: ChatCompletionRequest, http_request: Request)
       ]
     }
     ```
-    
-    **Returns:** Server-sent events stream of chat completion chunks, terminated by `data: [DONE]`.
+
+    **Key Features:**
+    - **100% OpenAI Compatible**: Supports input_file with file_url
+    - **Universal File Support**: PDF, DOCX, XLSX, CSV, images, and more
+    - **Multi-Provider**: Works with all providers (OpenAI, Anthropic, Ollama, etc.)
+    - **Optional Streaming**: Set "stream": true for real-time responses
+    - **Backward Compatible**: Existing clients continue to work
+
+    **Returns:** Chat completion object, or server-sent events stream if streaming is enabled.
     """
-    # For now, delegate to chat completions with streaming enabled
-    # The OpenAI Responses API is essentially streaming chat completions with enhanced real-time features
-    request.stream = True  # Force streaming for responses API
+    try:
+        # Use the parsed request body directly
+        request_data = request_body
 
-    provider, model = parse_model_string(request.model)
+        # Detect OpenAI responses format vs legacy format
+        if "input" in request_data:
+            # OpenAI Responses API format
+            logger.info("📡 OpenAI Responses API format detected")
 
-    logger.info(
-        "📡 Responses API Request",
-        provider=provider,
-        model=model,
-        messages=len(request.messages),
-        has_tools=bool(request.tools)
-    )
+            # Parse as OpenAI format
+            openai_request = OpenAIResponsesRequest(**request_data)
 
-    return await process_chat_completion(provider, model, request, http_request)
+            # Convert to internal format
+            chat_request = convert_openai_responses_to_chat_completion(openai_request)
+
+        elif "messages" in request_data:
+            # Legacy format (backward compatibility)
+            logger.info("📡 Legacy responses format detected")
+
+            # Parse as ChatCompletionRequest
+            chat_request = ChatCompletionRequest(**request_data)
+
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": {"message": "Request must contain either 'input' (OpenAI format) or 'messages' (legacy format)", "type": "invalid_request"}}
+            )
+
+        # Respect user's streaming preference (defaults to False)
+
+        # Process using our standard pipeline
+        provider, model = parse_model_string(chat_request.model)
+
+        logger.info(
+            "📡 Responses API Request",
+            provider=provider,
+            model=model,
+            format="openai" if "input" in request_data else "legacy",
+            messages=len(chat_request.messages)
+        )
+
+        return await process_chat_completion(provider, model, chat_request, http_request)
+
+    except Exception as e:
+        logger.error(f"Responses API error: {e}")
+        raise HTTPException(
+            status_code=400,
+            detail={"error": {"message": str(e), "type": "processing_error"}}
+        )
 
 @app.post("/v1/embeddings")
 async def create_embeddings(request: EmbeddingRequest):
@@ -755,25 +1424,491 @@ async def create_embeddings(request: EmbeddingRequest):
             detail={"error": {"message": str(e), "type": "embedding_error"}}
         )
 
+# ============================================================================
+# Media Processing Utilities
+# ============================================================================
+
+def handle_base64_image(data_url: str) -> str:
+    """
+    Process base64 data URL and save to temporary file.
+
+    Args:
+        data_url: Base64 data URL (e.g., "data:image/jpeg;base64,..." or "data:application/pdf;base64,...")
+
+    Returns:
+        Path to temporary file
+    """
+    try:
+        # Parse data URL
+        if not data_url.startswith("data:"):
+            raise ValueError("Invalid data URL format")
+
+        # Extract media type and base64 data
+        header, data = data_url.split(",", 1)
+        media_type = header.split(";")[0].split(":")[1]
+
+        # Determine file extension for all supported media types
+        ext_map = {
+            # Images
+            "image/jpeg": ".jpg",
+            "image/jpg": ".jpg",
+            "image/png": ".png",
+            "image/gif": ".gif",
+            "image/webp": ".webp",
+            "image/bmp": ".bmp",
+            "image/tiff": ".tiff",
+            # Documents
+            "application/pdf": ".pdf",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+            "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+            # Data files
+            "text/csv": ".csv",
+            "text/tab-separated-values": ".tsv",
+            "application/json": ".json",
+            "application/xml": ".xml",
+            "text/xml": ".xml",
+            "text/plain": ".txt",
+            "text/markdown": ".md",
+            # Generic fallback
+            "application/octet-stream": ".bin"
+        }
+        extension = ext_map.get(media_type, ".bin")
+
+        # Decode base64 data
+        file_data = base64.b64decode(data)
+
+        # Save to temporary file with request-specific prefix for better isolation
+        import hashlib
+        data_hash = hashlib.md5(data[:100].encode() if len(data) > 100 else data.encode()).hexdigest()[:8]
+        request_id = uuid.uuid4().hex[:8]
+        prefix = f"abstractcore_b64_{data_hash}_{request_id}_"
+
+        with tempfile.NamedTemporaryFile(delete=False, suffix=extension, prefix=prefix) as temp_file:
+            temp_file.write(file_data)
+            temp_file_path = temp_file.name
+
+        # Log the temporary file creation for debugging
+        logger.debug(f"Processed base64 media to temporary file: {temp_file_path} (size: {len(file_data)} bytes)")
+        return temp_file_path
+
+    except Exception as e:
+        logger.error(f"Failed to process base64 media: {e}")
+        raise HTTPException(
+            status_code=400,
+            detail={"error": {"message": f"Invalid base64 media data: {e}", "type": "media_error"}}
+        )
+
+def download_file_temporarily(url: str) -> str:
+    """
+    Download file from URL to temporary file (supports images, documents, data files).
+
+    Args:
+        url: HTTP(S) URL to file
+
+    Returns:
+        Path to temporary file
+    """
+    try:
+        # Validate URL
+        parsed = urllib.parse.urlparse(url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError("Only HTTP and HTTPS URLs are allowed")
+
+        # Create request with browser-like headers to avoid 403 Forbidden errors
+        request = urllib.request.Request(url)
+        request.add_header('User-Agent', 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36')
+        # Generic accept header for all file types
+        request.add_header('Accept', '*/*')
+        request.add_header('Accept-Language', 'en-US,en;q=0.9')
+        request.add_header('Accept-Encoding', 'gzip, deflate, br')
+        request.add_header('Connection', 'keep-alive')
+        request.add_header('Upgrade-Insecure-Requests', '1')
+        request.add_header('Sec-Fetch-Dest', 'document')  # More generic than 'image'
+        request.add_header('Sec-Fetch-Mode', 'no-cors')
+        request.add_header('Sec-Fetch-Site', 'cross-site')
+
+        # Download with size limit (10MB)
+        response = urllib.request.urlopen(request, timeout=30)
+        if response.getheader('content-length'):
+            size = int(response.getheader('content-length'))
+            if size > 10 * 1024 * 1024:  # 10MB limit
+                raise ValueError("File too large (max 10MB)")
+
+        # Read data with size check
+        data = b""
+        while True:
+            chunk = response.read(8192)
+            if not chunk:
+                break
+            data += chunk
+            if len(data) > 10 * 1024 * 1024:  # 10MB limit
+                raise ValueError("File too large (max 10MB)")
+
+        # Determine extension from content-type or URL
+        content_type = response.getheader('content-type', '').lower()
+        ext_map = {
+            # Images
+            "image/jpeg": ".jpg",
+            "image/jpg": ".jpg",
+            "image/png": ".png",
+            "image/gif": ".gif",
+            "image/webp": ".webp",
+            "image/bmp": ".bmp",
+            "image/tiff": ".tiff",
+            # Documents
+            "application/pdf": ".pdf",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+            "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+            # Data files
+            "text/csv": ".csv",
+            "text/tab-separated-values": ".tsv",
+            "application/json": ".json",
+            "application/xml": ".xml",
+            "text/xml": ".xml",
+            "text/plain": ".txt",
+            "text/markdown": ".md",
+            # Generic fallback
+            "application/octet-stream": ".bin"
+        }
+
+        # Try to get extension from content-type first, then URL
+        extension = ext_map.get(content_type)
+        if not extension:
+            # Try to get extension from URL
+            url_path = parsed.path.lower()
+            if url_path.endswith('.pdf'):
+                extension = '.pdf'
+            elif url_path.endswith('.jpg') or url_path.endswith('.jpeg'):
+                extension = '.jpg'
+            elif url_path.endswith('.png'):
+                extension = '.png'
+            elif url_path.endswith('.docx'):
+                extension = '.docx'
+            elif url_path.endswith('.xlsx'):
+                extension = '.xlsx'
+            elif url_path.endswith('.csv'):
+                extension = '.csv'
+            else:
+                extension = '.bin'  # Generic fallback
+
+        # Save to temporary file with request-specific prefix for better isolation
+        import hashlib
+        url_hash = hashlib.md5(url.encode()).hexdigest()[:8]
+        request_id = uuid.uuid4().hex[:8]
+        prefix = f"abstractcore_file_{url_hash}_{request_id}_"
+
+        with tempfile.NamedTemporaryFile(delete=False, suffix=extension, prefix=prefix) as temp_file:
+            temp_file.write(data)
+            temp_file_path = temp_file.name
+
+        # Log the temporary file creation for debugging
+        logger.info(f"Downloaded file to temporary file: {temp_file_path} (size: {len(data)} bytes, type: {content_type})")
+        return temp_file_path
+
+    except Exception as e:
+        logger.error(f"Failed to download file from URL {url}: {e}")
+        raise HTTPException(
+            status_code=400,
+            detail={"error": {"message": f"Failed to download file: {e}", "type": "media_error"}}
+        )
+
+def download_image_temporarily(url: str) -> str:
+    """
+    Download image from URL to temporary file (backward compatibility wrapper).
+
+    Args:
+        url: HTTP(S) URL to image
+
+    Returns:
+        Path to temporary file
+    """
+    return download_file_temporarily(url)
+
+def process_image_url_object(image_url_obj: Dict[str, Any]) -> Optional[str]:
+    """
+    Process OpenAI image_url object and return local file path.
+
+    Args:
+        image_url_obj: Image URL object with 'url' field
+
+    Returns:
+        Local file path or None if processing failed
+    """
+    try:
+        url = image_url_obj.get("url", "")
+        if not url:
+            return None
+
+        if url.startswith("data:"):
+            # Base64 encoded image
+            return handle_base64_image(url)
+        elif url.startswith(("http://", "https://")):
+            # Download from URL
+            return download_image_temporarily(url)
+        else:
+            # Assume local file path
+            if os.path.exists(url):
+                return url
+            else:
+                logger.warning(f"Local file not found: {url}")
+                return None
+
+    except Exception as e:
+        logger.error(f"Failed to process image URL object: {e}")
+        return None
+
+def process_file_url_object(file_url_obj: Dict[str, Any]) -> Optional[str]:
+    """
+    Process OpenAI file_url object and return local file path.
+
+    Simplified format (consistent with image_url):
+    {"url": "https://example.com/file.pdf"} or
+    {"url": "/local/path/file.pdf"} or
+    {"url": "data:application/pdf;base64,..."}
+
+    Args:
+        file_url_obj: File URL object with 'url' field (same as image_url)
+
+    Returns:
+        Local file path or None if processing failed
+    """
+    try:
+        # Reuse existing image URL processing logic - works perfectly for any file type
+        return process_image_url_object(file_url_obj)
+
+    except Exception as e:
+        logger.error(f"Failed to process file URL object: {e}")
+        return None
+
+def process_message_content(message: ChatMessage) -> Tuple[str, List[str]]:
+    """
+    Extract media files from message content and return clean text + media list.
+
+    Supports both OpenAI formats:
+    - content as string: "Analyze this @image.jpg"
+    - content as array: [{"type": "text", "text": "..."}, {"type": "image_url", "image_url": {...}}, {"type": "file", "file_url": {...}}]
+
+    Args:
+        message: ChatMessage with content to process
+
+    Returns:
+        Tuple of (clean_text, media_file_paths)
+    """
+    if message.content is None:
+        return "", []
+
+    if isinstance(message.content, str):
+        # Legacy format: extract @filename references
+        clean_text, media_files = MessagePreprocessor.parse_file_attachments(
+            message.content,
+            validate_existence=True,
+            verbose=False
+        )
+        return clean_text, media_files
+
+    elif isinstance(message.content, list):
+        # OpenAI array format: extract image_url objects
+        text_parts = []
+        media_files = []
+
+        for item in message.content:
+            if isinstance(item, dict):
+                item_type = item.get("type")
+                if item_type == "text" and item.get("text"):
+                    text_parts.append(item["text"])
+                elif item_type == "image_url" and item.get("image_url"):
+                    media_file = process_image_url_object(item["image_url"])
+                    if media_file:
+                        media_files.append(media_file)
+                elif item_type == "file" and item.get("file_url"):
+                    media_file = process_file_url_object(item["file_url"])
+                    if media_file:
+                        media_files.append(media_file)
+            elif hasattr(item, 'type'):
+                # Pydantic ContentItem object
+                if item.type == "text" and item.text:
+                    text_parts.append(item.text)
+                elif item.type == "image_url" and item.image_url:
+                    media_file = process_image_url_object(item.image_url)
+                    if media_file:
+                        media_files.append(media_file)
+                elif item.type == "file" and item.file_url:
+                    media_file = process_file_url_object(item.file_url)
+                    if media_file:
+                        media_files.append(media_file)
+
+        return " ".join(text_parts), media_files
+
+    return str(message.content), []
+
+def adapt_prompt_for_media_types(text: str, media_files: List[str]) -> str:
+    """
+    Intelligently adapt prompts based on attached media file types.
+
+    Fixes common mismatches like "What is in this image?" when sending documents.
+
+    Args:
+        text: Original text content
+        media_files: List of media file paths
+
+    Returns:
+        Adapted text content
+    """
+    if not media_files or not text:
+        return text
+
+    # Analyze media file types
+    image_extensions = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.tiff'}
+    document_extensions = {'.pdf', '.docx', '.xlsx', '.pptx'}
+    data_extensions = {'.csv', '.tsv', '.json', '.xml'}
+    text_extensions = {'.txt', '.md'}
+
+    has_images = False
+    has_documents = False
+    has_data = False
+    has_text = False
+
+    for file_path in media_files:
+        ext = os.path.splitext(file_path)[1].lower()
+        if ext in image_extensions:
+            has_images = True
+        elif ext in document_extensions:
+            has_documents = True
+        elif ext in data_extensions:
+            has_data = True
+        elif ext in text_extensions:
+            has_text = True
+
+    # Common prompt adaptations
+    adapted_text = text
+
+    # Fix "What is in this image?" when not dealing with images
+    if "what is in this image" in text.lower():
+        if has_documents and not has_images:
+            adapted_text = text.replace("What is in this image?", "What is in this document?")
+            adapted_text = adapted_text.replace("what is in this image?", "what is in this document?")
+            adapted_text = adapted_text.replace("What is in this image", "What is in this document")
+            adapted_text = adapted_text.replace("what is in this image", "what is in this document")
+        elif has_data and not has_images:
+            adapted_text = text.replace("What is in this image?", "What data is in this file?")
+            adapted_text = adapted_text.replace("what is in this image?", "what data is in this file?")
+            adapted_text = adapted_text.replace("What is in this image", "What data is in this file")
+            adapted_text = adapted_text.replace("what is in this image", "what data is in this file")
+        elif has_text and not has_images:
+            adapted_text = text.replace("What is in this image?", "What is in this text file?")
+            adapted_text = adapted_text.replace("what is in this image?", "what is in this text file?")
+            adapted_text = adapted_text.replace("What is in this image", "What is in this text file")
+            adapted_text = adapted_text.replace("what is in this image", "what is in this text file")
+
+    # Fix "What is in this document?" when dealing with images
+    elif "what is in this document" in text.lower() and has_images and not (has_documents or has_data or has_text):
+        adapted_text = text.replace("What is in this document?", "What is in this image?")
+        adapted_text = adapted_text.replace("what is in this document?", "what is in this image?")
+        adapted_text = adapted_text.replace("What is in this document", "What is in this image")
+        adapted_text = adapted_text.replace("what is in this document", "what is in this image")
+
+    # Handle mixed content with specific naming
+    if adapted_text != text:
+        # Count media types for better description
+        total_files = len(media_files)
+        if total_files > 1:
+            types = []
+            if has_images:
+                types.append("image(s)")
+            if has_documents:
+                types.append("document(s)")
+            if has_data:
+                types.append("data file(s)")
+            if has_text:
+                types.append("text file(s)")
+
+            if len(types) > 1:
+                adapted_text = adapted_text.replace("this document", f"these {' and '.join(types)}")
+                adapted_text = adapted_text.replace("this image", f"these {' and '.join(types)}")
+                adapted_text = adapted_text.replace("this file", f"these {' and '.join(types)}")
+
+    if adapted_text != text:
+        logger.info(f"Adapted prompt for media types: '{text}' → '{adapted_text}'")
+
+    return adapted_text
+
+def validate_media_files(files: List[str]) -> None:
+    """
+    Validate media files for security and size limits.
+
+    Args:
+        files: List of file paths to validate
+
+    Raises:
+        HTTPException: If validation fails
+    """
+    ALLOWED_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.tiff',
+                         '.pdf', '.docx', '.xlsx', '.pptx', '.csv', '.tsv', '.txt', '.md',
+                         '.json', '.xml'}
+
+    total_size = 0
+    max_total_size = 32 * 1024 * 1024  # 32MB total limit
+
+    for file_path in files:
+        if not os.path.exists(file_path):
+            raise HTTPException(
+                status_code=400,
+                detail={"error": {"message": f"File not found: {file_path}", "type": "file_not_found"}}
+            )
+
+        # Check extension
+        ext = os.path.splitext(file_path)[1].lower()
+        if ext not in ALLOWED_EXTENSIONS:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": {"message": f"File type {ext} not allowed", "type": "invalid_file_type"}}
+            )
+
+        # Check individual file size (10MB per file)
+        file_size = os.path.getsize(file_path)
+        if file_size > 10 * 1024 * 1024:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": {"message": f"File too large: {file_path} (max 10MB per file)", "type": "file_too_large"}}
+            )
+
+        total_size += file_size
+
+        # Check total size across all files
+        if total_size > max_total_size:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": {"message": "Total file size exceeds 32MB limit", "type": "total_size_exceeded"}}
+            )
+
 @app.post("/v1/chat/completions")
 async def chat_completions(request: ChatCompletionRequest, http_request: Request):
     """
-    Create a model response for the given chat conversation.
-    
-    Given a list of messages comprising a conversation, the model will return a response. 
-    This endpoint supports streaming, tool calling, and multiple providers.
-    
+    Create a model response for the given chat conversation with optional media attachments.
+
+    Given a list of messages comprising a conversation, the model will return a response.
+    This endpoint supports streaming, tool calling, media attachments, and multiple providers.
+
     **Key Features:**
     - Multi-provider support (OpenAI, Anthropic, Ollama, LMStudio, etc.)
     - Streaming responses with server-sent events
     - Tool/function calling with automatic syntax conversion
-    - OpenAI-compatible format
+    - Media attachments (images, documents, data files)
+    - OpenAI Vision API compatible format
     
     **Provider Format:** Use `provider/model` format in the model field:
     - `openai/gpt-4` - OpenAI GPT-4
     - `ollama/llama3:latest` - Ollama LLaMA 3
     - `anthropic/claude-3-opus-20240229` - Anthropic Claude 3 Opus
-    
+
+    **Media Attachments:** Support for OpenAI Vision API compatible format:
+    - String content: "Analyze this @image.jpg" (AbstractCore @filename syntax)
+    - Array content: [{"type": "text", "text": "..."}, {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}]
+    - Supported formats: Images (PNG, JPEG, GIF, WEBP), Documents (PDF, DOCX, XLSX, PPTX), Data (CSV, TSV, TXT, MD)
+    - Size limits: 10MB per file, 32MB total per request
+
     **To see available models:** `GET /v1/models?type=text-generation`
     
     **Returns:** A chat completion object, or a stream of chat completion chunks if streaming is enabled.
@@ -833,11 +1968,40 @@ async def process_chat_completion(
             user_agent=http_request.headers.get("user-agent", "")[:50]
         )
 
+        # Process media from messages
+        all_media_files = []
+        processed_messages = []
+
+        for message in request.messages:
+            clean_text, media_files = process_message_content(message)
+            all_media_files.extend(media_files)
+
+            # Adapt prompt based on media file types to avoid confusion
+            if media_files:
+                adapted_text = adapt_prompt_for_media_types(clean_text, media_files)
+            else:
+                adapted_text = clean_text
+
+            # Create processed message with adapted text
+            processed_message = message.model_copy()
+            processed_message.content = adapted_text
+            processed_messages.append(processed_message)
+
+        # Validate media files if any were found
+        if all_media_files:
+            validate_media_files(all_media_files)
+            logger.info(
+                "📎 Media Files Processed",
+                request_id=request_id,
+                file_count=len(all_media_files),
+                files=[os.path.basename(f) for f in all_media_files[:5]]  # Log first 5 filenames
+            )
+
         # Create LLM instance
         llm = create_llm(provider, model=model)
 
         # Convert messages
-        messages = convert_to_abstractcore_messages(request.messages)
+        messages = convert_to_abstractcore_messages(processed_messages)
 
         # Create syntax rewriter
         syntax_rewriter = create_syntax_rewriter(target_format, f"{provider}/{model}")
@@ -846,6 +2010,7 @@ async def process_chat_completion(
         gen_kwargs = {
             "prompt": "",  # Empty when using messages
             "messages": messages,
+            "media": all_media_files if all_media_files else None,  # Add media files
             "temperature": request.temperature,
             "max_tokens": request.max_tokens,
             "stream": request.stream,
@@ -865,19 +2030,53 @@ async def process_chat_completion(
             gen_kwargs["presence_penalty"] = request.presence_penalty
 
         # Generate response
-        if request.stream:
-            return StreamingResponse(
-                generate_streaming_response(
-                    llm, gen_kwargs, provider, model, syntax_rewriter, request_id
-                ),
-                media_type="text/event-stream",
-                headers={"Cache-Control": "no-cache", "Connection": "keep-alive"}
-            )
-        else:
-            response = llm.generate(**gen_kwargs)
-            return convert_to_openai_response(
-                response, provider, model, syntax_rewriter, request_id
+        # Only cleanup files created by this request (with our specific prefixes)
+        temp_files_to_cleanup = [
+            f for f in all_media_files
+            if f.startswith("/tmp/") and (
+                "abstractcore_img_" in f or
+                "abstractcore_file_" in f or
+                "abstractcore_b64_" in f or
+                "temp" in f
             )
+        ]
+
+        try:
+            if request.stream:
+                return StreamingResponse(
+                    generate_streaming_response(
+                        llm, gen_kwargs, provider, model, syntax_rewriter, request_id, temp_files_to_cleanup
+                    ),
+                    media_type="text/event-stream",
+                    headers={"Cache-Control": "no-cache", "Connection": "keep-alive"}
+                )
+            else:
+                response = llm.generate(**gen_kwargs)
+                return convert_to_openai_response(
+                    response, provider, model, syntax_rewriter, request_id
+                )
+        finally:
+            # Cleanup temporary files (base64 and downloaded images) with delay to avoid race conditions
+            import threading
+
+            def delayed_cleanup():
+                """Cleanup temporary files after a short delay to avoid race conditions"""
+                time.sleep(1)  # Short delay to ensure generation is complete
+                for temp_file in temp_files_to_cleanup:
+                    try:
+                        if os.path.exists(temp_file):
+                            # Additional check: only delete files created by this session
+                            if ("abstractcore_img_" in temp_file or "abstractcore_file_" in temp_file or "abstractcore_b64_" in temp_file):
+                                os.unlink(temp_file)
+                                logger.debug(f"Cleaned up temporary file: {temp_file}")
+                            else:
+                                logger.debug(f"Skipped cleanup of non-AbstractCore file: {temp_file}")
+                    except Exception as e:
+                        logger.warning(f"Failed to cleanup temporary file {temp_file}: {e}")
+
+            # Run cleanup in background thread to avoid blocking response
+            cleanup_thread = threading.Thread(target=delayed_cleanup, daemon=True)
+            cleanup_thread.start()
 
     except Exception as e:
         logger.error(
@@ -897,7 +2096,8 @@ def generate_streaming_response(
     provider: str,
     model: str,
     syntax_rewriter: ToolCallSyntaxRewriter,
-    request_id: str
+    request_id: str,
+    temp_files_to_cleanup: List[str] = None
 ) -> Iterator[str]:
     """Generate OpenAI-compatible streaming response with syntax rewriting."""
     try:
@@ -983,6 +2183,29 @@ def generate_streaming_response(
             has_tool_calls=has_tool_calls
         )
 
+        # Cleanup temporary files for streaming with delay to avoid race conditions
+        if temp_files_to_cleanup:
+            import threading
+
+            def delayed_streaming_cleanup():
+                """Cleanup temporary files after streaming completes"""
+                time.sleep(2)  # Longer delay for streaming to ensure all chunks are sent
+                for temp_file in temp_files_to_cleanup:
+                    try:
+                        if os.path.exists(temp_file):
+                            # Additional check: only delete files created by this session
+                            if ("abstractcore_img_" in temp_file or "abstractcore_file_" in temp_file or "abstractcore_b64_" in temp_file):
+                                os.unlink(temp_file)
+                                logger.debug(f"Cleaned up temporary file during streaming: {temp_file}")
+                            else:
+                                logger.debug(f"Skipped cleanup of non-AbstractCore streaming file: {temp_file}")
+                    except Exception as cleanup_error:
+                        logger.warning(f"Failed to cleanup temporary file {temp_file}: {cleanup_error}")
+
+            # Run cleanup in background thread
+            cleanup_thread = threading.Thread(target=delayed_streaming_cleanup, daemon=True)
+            cleanup_thread.start()
+
     except Exception as e:
         logger.error(
             "❌ Streaming failed",
@@ -1072,25 +2295,88 @@ def run_server(host: str = "0.0.0.0", port: int = 8000):
     uvicorn.run(app, host=host, port=port)
 
 # ============================================================================
-# Startup
+# Server Runner Function
 # ============================================================================
 
-if __name__ == "__main__":
-    import uvicorn
+def run_server_with_args():
+    """Run the server with argument parsing for CLI usage."""
+    parser = argparse.ArgumentParser(
+        description="AbstractCore Server - Universal LLM Gateway with Media Processing",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python -m abstractcore.server.app                    # Start server with defaults
+  python -m abstractcore.server.app --debug           # Start with debug logging
+  python -m abstractcore.server.app --host 127.0.0.1 --port 8080  # Custom host/port
+  python -m abstractcore.server.app --debug --port 8080           # Debug on custom port
+
+Environment Variables:
+  ABSTRACTCORE_DEBUG=true    # Enable debug mode (equivalent to --debug)
+  HOST=127.0.0.1            # Server host (overridden by --host)
+  PORT=8080                  # Server port (overridden by --port)
+
+Debug Mode:
+  The --debug flag enables verbose logging and better error reporting, including:
+  - Detailed HTTP request/response logging
+  - Full error traces for 422 Unprocessable Entity errors
+  - Media processing diagnostics
+  - Provider initialization details
+        """
+    )
+
+    parser.add_argument(
+        '--debug',
+        action='store_true',
+        help='Enable debug logging and show detailed diagnostics (overrides centralized config)'
+    )
+    parser.add_argument(
+        '--host',
+        default=os.getenv("HOST", "0.0.0.0"),
+        help='Host to bind the server to (default: 0.0.0.0)'
+    )
+    parser.add_argument(
+        '--port',
+        type=int,
+        default=int(os.getenv("PORT", "8000")),
+        help='Port to bind the server to (default: 8000)'
+    )
 
-    port = int(os.getenv("PORT", "8000"))
-    host = os.getenv("HOST", "0.0.0.0")
+    args = parser.parse_args()
+
+    # Reconfigure logging if debug mode is requested (--debug overrides config defaults)
+    if args.debug:
+        reconfigure_for_debug()
+        print("🐛 Debug mode enabled - detailed logging active")
 
     logger.info(
         "🚀 Starting AbstractCore Server",
-        host=host,
-        port=port,
-        debug=debug_mode
+        host=args.host,
+        port=args.port,
+        debug=debug_mode,
+        version=__version__
     )
 
-    uvicorn.run(
-        app,
-        host=host,
-        port=port,
-        log_level="debug" if debug_mode else "info"
-    )
+    # Enhanced uvicorn configuration for debug mode
+    uvicorn_config = {
+        "app": app,
+        "host": args.host,
+        "port": args.port,
+        "log_level": "debug" if debug_mode else "info"
+    }
+
+    # In debug mode, enable more detailed uvicorn logging
+    if debug_mode:
+        uvicorn_config.update({
+            "access_log": True,
+            "use_colors": True,
+        })
+
+    import uvicorn
+    uvicorn.run(**uvicorn_config)
+
+# ============================================================================
+# Startup
+# ============================================================================
+
+if __name__ == "__main__":
+    run_server_with_args()