jaf-py 2.4.1__py3-none-any.whl → 2.4.3__py3-none-any.whl

jaf/server/types.py

@@ -7,22 +7,118 @@ for the JAF HTTP server implementation.
 
 from dataclasses import dataclass
 from typing import Any, Dict, Generic, List, Literal, Optional, TypeVar, Union
+import base64
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator, model_validator
 
-from ..core.types import Agent, RunConfig
+from ..core.types import Agent, RunConfig, Attachment, MessageContentPart, get_text_content
 from ..memory.types import MemoryProvider
 
 Ctx = TypeVar('Ctx')
 
+# Pydantic models for attachments to work with HTTP API
+class HttpAttachment(BaseModel):
+    """HTTP attachment format for API requests."""
+    kind: Literal['image', 'document', 'file']
+    mime_type: Optional[str] = None
+    name: Optional[str] = None
+    url: Optional[str] = None
+    data: Optional[str] = None  # Base64 encoded data
+    format: Optional[str] = None
+    use_litellm_format: Optional[bool] = None
+    
+    @model_validator(mode='after')
+    def validate_url_or_data_present(self) -> 'HttpAttachment':
+        """Validate that at least one of url or data is present."""
+        if self.url is None and self.data is None:
+            raise ValueError("At least one of 'url' or 'data' must be provided")
+        return self
+    
+    @field_validator('data')
+    @classmethod
+    def validate_base64_data(cls, v: Optional[str]) -> Optional[str]:
+        """Validate that data is proper base64 encoded."""
+        if v is not None:
+            try:
+                # Try to decode the base64 data to verify it's valid
+                decoded = base64.b64decode(v)
+                # Check if it's empty
+                if len(decoded) == 0:
+                    raise ValueError("Base64 data decodes to empty content")
+            except Exception as e:
+                raise ValueError(f"Invalid base64 encoding: {str(e)}")
+        return v
+    
+    @model_validator(mode='after')
+    def validate_mime_type_consistency(self) -> 'HttpAttachment':
+        """Validate that mime_type is consistent with kind."""
+        if self.mime_type is not None and self.kind is not None:
+            if self.kind == 'image' and not self.mime_type.startswith('image/'):
+                raise ValueError(f"For kind='image', mime_type must start with 'image/'. Got: {self.mime_type}")
+            
+            elif self.kind == 'document' and not (
+                self.mime_type.startswith('application/') or 
+                self.mime_type.startswith('text/') or
+                self.mime_type.startswith('document/')
+            ):
+                raise ValueError(
+                    f"For kind='document', mime_type must start with 'application/', 'text/', "
+                    f"or 'document/'. Got: {self.mime_type}"
+                )
+        return self
+
+class HttpMessageContentPart(BaseModel):
+    """HTTP message content part for multi-part messages."""
+    type: Literal['text', 'image_url', 'file']
+    text: Optional[str] = None
+    image_url: Optional[Dict[str, Any]] = None
+    file: Optional[Dict[str, Any]] = None
+    
+    @model_validator(mode='after')
+    def validate_content_consistency(self) -> 'HttpMessageContentPart':
+        """Validate that exactly one field is populated and it matches the declared type."""
+        # Count non-None content fields
+        populated_fields = []
+        if self.text is not None:
+            populated_fields.append('text')
+        if self.image_url is not None:
+            populated_fields.append('image_url')
+        if self.file is not None:
+            populated_fields.append('file')
+        
+        # Check if exactly one field is populated
+        if len(populated_fields) != 1:
+            raise ValueError(f"Exactly one content field must be populated. Found {len(populated_fields)}: {populated_fields}")
+        
+        # Check that the populated field matches the declared type
+        populated_field = populated_fields[0]
+        if self.type == 'text' and populated_field != 'text':
+            raise ValueError(f"For type='text', the 'text' field must be populated, but found '{populated_field}' instead")
+        elif self.type == 'image_url' and populated_field != 'image_url':
+            raise ValueError(f"For type='image_url', the 'image_url' field must be populated, but found '{populated_field}' instead")
+        elif self.type == 'file' and populated_field != 'file':
+            raise ValueError(f"For type='file', the 'file' field must be populated, but found '{populated_field}' instead")
+        
+        return self
+
 # HTTP Message types
 class HttpMessage(BaseModel):
     """HTTP message format for API requests."""
     role: Literal['user', 'assistant', 'system', 'tool']
-    content: str
+    content: Union[str, List[HttpMessageContentPart]]
+    attachments: Optional[List[HttpAttachment]] = None
     tool_call_id: Optional[str] = None
     tool_calls: Optional[List[Dict[str, Any]]] = None
 
+# Approval types for HITL
+class ApprovalMessage(BaseModel):
+    """Approval message for tool execution."""
+    type: Literal['approval'] = 'approval'
+    session_id: str = Field(..., description="Session ID for the approval")
+    tool_call_id: str = Field(..., description="ID of the tool call being approved")
+    approved: bool = Field(..., description="Whether the tool execution is approved")
+    additional_context: Optional[Dict[str, Any]] = Field(default=None, description="Additional context for the approval")
+
 # Request types
 class ChatRequest(BaseModel):
     """Request format for chat endpoints."""
@@ -33,6 +129,33 @@ class ChatRequest(BaseModel):
     stream: bool = Field(default=False, description="Whether to stream the response")
     conversation_id: Optional[str] = Field(default=None, description="Conversation ID for memory persistence")
     memory: Optional[Dict[str, Any]] = Field(default=None, description="Memory configuration override")
+    store_on_completion: Optional[bool] = Field(default=None, description="Whether to store conversation on completion")
+    approvals: Optional[List[ApprovalMessage]] = Field(default=None, description="Approval decisions for tool calls")
+
+# Interruption types for HITL
+class ToolCallInterruption(BaseModel):
+    """Tool call interruption data."""
+    id: str
+    type: Literal['function'] = 'function'
+    function: Dict[str, str]  # name and arguments
+
+class InterruptionData(BaseModel):
+    """Interruption information."""
+    type: Literal['tool_approval'] = 'tool_approval'
+    tool_call: Optional[ToolCallInterruption]
+    session_id: str
+
+# Base outcome types
+class BaseOutcomeData(BaseModel):
+    """Base outcome data."""
+    status: Literal['completed', 'error', 'max_turns', 'interrupted']
+    output: Optional[str] = None
+    error: Optional[Any] = None
+
+class InterruptedOutcomeData(BaseOutcomeData):
+    """Outcome data for interrupted runs."""
+    status: Literal['interrupted'] = 'interrupted'
+    interruptions: Optional[List[InterruptionData]] = None
 
 # Response types
 class CompletedChatData(BaseModel):
@@ -40,7 +163,7 @@ class CompletedChatData(BaseModel):
     run_id: str
     trace_id: str
     messages: List[HttpMessage]
-    outcome: Dict[str, Any]
+    outcome: BaseOutcomeData
     turn_count: int
     execution_time_ms: int
     conversation_id: Optional[str] = None
@@ -123,6 +246,28 @@ class ServerConfig(Generic[Ctx]):
     cors: Union[bool, Dict[str, Any]] = True
     default_memory_provider: Optional[MemoryProvider] = None
 
+# Approval response types
+class PendingApprovalData(BaseModel):
+    """Data for a pending approval."""
+    conversation_id: str
+    tool_call_id: str
+    tool_name: str
+    args: Dict[str, Any]
+    signature: Optional[str] = None
+    status: Literal['pending'] = 'pending'
+    session_id: Optional[str] = None
+
+class PendingApprovalsData(BaseModel):
+    """Data for pending approvals response."""
+    pending: List[PendingApprovalData]
+
+class PendingApprovalsResponse(BaseModel):
+    """Response format for pending approvals endpoint."""
+    success: bool
+    data: Optional[PendingApprovalsData] = None
+    error: Optional[str] = None
+
+
 # Validation schemas
 def validate_chat_request(data: Dict[str, Any]) -> ChatRequest:
     """Validate and parse a chat request."""

jaf/utils/__init__.py

@@ -0,0 +1,50 @@
+"""
+Utility modules for the JAF framework.
+
+This package provides various utility functions and classes for working
+with attachments, document processing, and other common tasks.
+"""
+
+# Import attachment utilities
+from .attachments import (
+    make_image_attachment,
+    make_file_attachment,
+    make_document_attachment,
+    validate_attachment,
+    assert_non_empty_attachment,
+    AttachmentValidationError,
+    ATTACHMENT_LIMITS,
+)
+
+# Import document processing utilities  
+from .document_processor import (
+    extract_document_content,
+    is_document_supported,
+    get_document_description,
+    get_missing_dependencies,
+    check_dependencies,
+    ProcessedDocument,
+    DocumentProcessingError,
+    NetworkError,
+)
+
+__all__ = [
+    # Attachment utilities
+    'make_image_attachment',
+    'make_file_attachment', 
+    'make_document_attachment',
+    'validate_attachment',
+    'assert_non_empty_attachment',
+    'AttachmentValidationError',
+    'ATTACHMENT_LIMITS',
+    
+    # Document processing
+    'extract_document_content',
+    'is_document_supported',
+    'get_document_description',
+    'get_missing_dependencies',
+    'check_dependencies',
+    'ProcessedDocument',
+    'DocumentProcessingError',
+    'NetworkError',
+]

jaf/utils/attachments.py

@@ -0,0 +1,401 @@
+"""
+Attachment validation and utility functions for the JAF framework.
+
+This module provides type-safe attachment creation and validation with
+comprehensive error handling and security checks.
+"""
+
+import base64
+import re
+from typing import Union, Optional, List
+from urllib.parse import urlparse
+
+from ..core.types import Attachment
+
+
+class AttachmentValidationError(Exception):
+    """Exception raised when attachment validation fails."""
+    
+    def __init__(self, message: str, field: Optional[str] = None):
+        super().__init__(message)
+        self.field = field
+
+
+# Constants
+MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024  # 10MB
+MAX_FILENAME_LENGTH = 255
+BASE64_SIZE_RATIO = 0.75  # Base64 decoded size is approximately 3/4 of the encoded size
+MAX_FORMAT_LENGTH = 10
+
+ALLOWED_IMAGE_MIME_TYPES = [
+    'image/jpeg', 'image/jpg', 'image/png', 'image/gif', 
+    'image/webp', 'image/bmp', 'image/svg+xml'
+]
+
+ALLOWED_DOCUMENT_MIME_TYPES = [
+    'application/pdf', 'text/plain', 'text/csv', 'application/json',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+]
+
+
+def _validate_base64(data: str) -> bool:
+    """Validate base64 string format."""
+    try:
+        # Basic base64 pattern check
+        base64_pattern = re.compile(r'^[A-Za-z0-9+/]*={0,2}$')
+        if not base64_pattern.match(data):
+            return False
+        
+        # Try to decode to verify it's valid base64
+        decoded = base64.b64decode(data)
+        reencoded = base64.b64encode(decoded).decode('ascii')
+        
+        # Account for padding differences
+        normalized_input = data.rstrip('=')
+        normalized_reencoded = reencoded.rstrip('=')
+        
+        return normalized_input == normalized_reencoded
+    except Exception:
+        return False
+
+
+def _validate_attachment_size(data: Optional[str]) -> None:
+    """Validate attachment size doesn't exceed limits."""
+    if data:
+        # Calculate exact decoded size for base64 data
+        # Remove padding to get accurate count
+        data_without_padding = data.rstrip('=')
+        # Each 4 base64 chars encode 3 bytes, with the last group potentially having padding
+        exact_groups = len(data_without_padding) // 4
+        remaining_chars = len(data_without_padding) % 4
+        
+        decoded_size = exact_groups * 3
+        if remaining_chars == 2:
+            decoded_size += 1  # 2 chars = 1 byte
+        elif remaining_chars == 3:
+            decoded_size += 2  # 3 chars = 2 bytes
+        
+        if decoded_size > MAX_ATTACHMENT_SIZE:
+            size_mb = round(decoded_size / 1024 / 1024, 2)
+            max_mb = MAX_ATTACHMENT_SIZE // 1024 // 1024
+            raise AttachmentValidationError(
+                f"Attachment size ({size_mb}MB) exceeds maximum allowed size ({max_mb}MB)"
+            )
+
+
+def _validate_filename(name: Optional[str]) -> None:
+    """Validate filename for security and length constraints."""
+    if not name:
+        return
+        
+    if len(name) > MAX_FILENAME_LENGTH:
+        raise AttachmentValidationError(
+            f"Filename length ({len(name)}) exceeds maximum allowed length ({MAX_FILENAME_LENGTH})"
+        )
+    
+    # Check for dangerous characters and control characters
+    dangerous_chars = re.compile(r'[<>:"|?*]')
+    control_chars = re.compile(r'[\x00-\x1f]')
+    
+    if dangerous_chars.search(name) or control_chars.search(name):
+        raise AttachmentValidationError('Filename contains invalid characters')
+    
+    # Check for path traversal attempts
+    if '..' in name or '/' in name or '\\' in name:
+        raise AttachmentValidationError(
+            'Filename cannot contain path separators or traversal sequences'
+        )
+
+
+def _validate_mime_type(mime_type: Optional[str], allowed_types: List[str], kind: str) -> None:
+    """Validate MIME type against allowed types."""
+    if mime_type:
+        # Normalize the input mime_type
+        normalized_mime_type = mime_type.lower().strip()
+        
+        # Normalize the allowed types list
+        normalized_allowed_types = {t.lower().strip() for t in allowed_types}
+        
+        if normalized_mime_type not in normalized_allowed_types:
+            raise AttachmentValidationError(
+                f"MIME type '{mime_type}' is not allowed for {kind} attachments. "
+                f"Allowed types: {', '.join(allowed_types)}"
+            )
+
+
+def _validate_url(url: Optional[str]) -> None:
+    """Validate URL format and protocol."""
+    if not url:
+        return
+        
+    try:
+        parsed = urlparse(url)
+        allowed_protocols = ['http', 'https', 'data']
+        
+        if parsed.scheme not in allowed_protocols:
+            raise AttachmentValidationError(
+                f"URL protocol '{parsed.scheme}' is not allowed. "
+                f"Allowed protocols: {', '.join(allowed_protocols)}"
+            )
+        
+        # Additional validation for data URLs
+        if parsed.scheme == 'data':
+            # For data URLs, the "path" component in urlparse contains the mediatype and data
+            # Proper data URL format: mediatype[;charset][;base64],data
+            data_content_pattern = re.compile(r'^([^;,]+)(;[^;,]+)*(;base64)?,(.+)$')
+            data_content = parsed.path
+            
+            # Some URLs might have query components that are part of the data
+            if parsed.query:
+                data_content += "?" + parsed.query
+                
+            if not data_content_pattern.match(data_content):
+                raise AttachmentValidationError(
+                    'Invalid data URL format: must match mediatype[;charset][;base64],data pattern'
+                )
+                
+    except ValueError as e:
+        raise AttachmentValidationError(f"Invalid URL: {e}")
+
+
+def _process_base64_data(data: Union[bytes, str, None]) -> Optional[str]:
+    """Process and validate base64 data."""
+    if not data:
+        return None
+    
+    if isinstance(data, bytes):
+        base64_str = base64.b64encode(data).decode('ascii')
+    else:
+        base64_str = data
+    
+    # Validate base64 format if it was provided as string
+    if isinstance(data, str) and not _validate_base64(base64_str):
+        raise AttachmentValidationError('Invalid base64 data format')
+    
+    return base64_str
+
+
+def make_image_attachment(
+    data: Union[bytes, str, None] = None,
+    url: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    name: Optional[str] = None
+) -> Attachment:
+    """
+    Create a validated image attachment.
+    
+    Args:
+        data: Raw bytes or base64 string
+        url: Remote or data URL
+        mime_type: MIME type (e.g., 'image/png')
+        name: Optional filename
+        
+    Returns:
+        Validated Attachment object
+        
+    Raises:
+        AttachmentValidationError: If validation fails
+    """
+    # Validate inputs
+    _validate_filename(name)
+    _validate_url(url)
+    _validate_mime_type(mime_type, ALLOWED_IMAGE_MIME_TYPES, 'image')
+    
+    # Process data to base64 first, so we can validate size for both bytes and string inputs
+    base64_data = _process_base64_data(data)
+    
+    # Validate size if we have data
+    if base64_data:
+        _validate_attachment_size(base64_data)
+    
+    # Ensure at least one content source
+    if not url and not base64_data:
+        raise AttachmentValidationError('Image attachment must have either url or data')
+    
+    return Attachment(
+        kind='image',
+        mime_type=mime_type,
+        name=name,
+        url=url,
+        data=base64_data
+    )
+
+
+def make_file_attachment(
+    data: Union[bytes, str, None] = None,
+    url: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    name: Optional[str] = None,
+    format: Optional[str] = None
+) -> Attachment:
+    """
+    Create a validated file attachment.
+    
+    Args:
+        data: Raw bytes or base64 string
+        url: Remote or data URL
+        mime_type: MIME type
+        name: Optional filename
+        format: Optional format identifier (e.g., 'pdf', 'txt')
+        
+    Returns:
+        Validated Attachment object
+        
+    Raises:
+        AttachmentValidationError: If validation fails
+    """
+    # Validate inputs
+    _validate_filename(name)
+    _validate_url(url)
+    
+    # Process data to base64 first, so we can validate size for both bytes and string inputs
+    base64_data = _process_base64_data(data)
+    
+    # Validate size if we have data
+    if base64_data:
+        _validate_attachment_size(base64_data)
+    
+    # Ensure at least one content source
+    if not url and not base64_data:
+        raise AttachmentValidationError('File attachment must have either url or data')
+    
+    # Validate format if provided
+    if format and len(format) > MAX_FORMAT_LENGTH:
+        raise AttachmentValidationError('File format must be 10 characters or less')
+    
+    return Attachment(
+        kind='file',
+        mime_type=mime_type,
+        name=name,
+        url=url,
+        data=base64_data,
+        format=format
+    )
+
+
+def make_document_attachment(
+    data: Union[bytes, str, None] = None,
+    url: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    name: Optional[str] = None,
+    format: Optional[str] = None,
+    use_litellm_format: Optional[bool] = None
+) -> Attachment:
+    """
+    Create a validated document attachment.
+    
+    Args:
+        data: Raw bytes or base64 string
+        url: Remote or data URL
+        mime_type: MIME type
+        name: Optional filename
+        format: Optional format identifier
+        use_litellm_format: Whether to use LiteLLM native format
+        
+    Returns:
+        Validated Attachment object
+        
+    Raises:
+        AttachmentValidationError: If validation fails
+    """
+    # Additional validation for documents
+    _validate_mime_type(mime_type, ALLOWED_DOCUMENT_MIME_TYPES, 'document')
+    
+    attachment = make_file_attachment(
+        data=data,
+        url=url,
+        mime_type=mime_type,
+        name=name,
+        format=format
+    )
+    
+    return Attachment(
+        kind='document',
+        mime_type=attachment.mime_type,
+        name=attachment.name,
+        url=attachment.url,
+        data=attachment.data,
+        format=attachment.format,
+        use_litellm_format=use_litellm_format
+    )
+
+
+def validate_attachment(attachment: Attachment) -> None:
+    """
+    Validate an existing attachment object.
+    
+    Args:
+        attachment: Attachment to validate
+        
+    Raises:
+        AttachmentValidationError: If validation fails
+    """
+    try:
+        if not attachment.url and not attachment.data:
+            raise AttachmentValidationError(
+                'Attachment must have either url or data',
+                field='url/data'
+            )
+        
+        if attachment.name:
+            try:
+                _validate_filename(attachment.name)
+            except AttachmentValidationError as e:
+                raise AttachmentValidationError(f"Invalid filename: {e}", field='name') from e
+        
+        if attachment.url:
+            try:
+                _validate_url(attachment.url)
+            except AttachmentValidationError as e:
+                raise AttachmentValidationError(f"Invalid URL: {e}", field='url') from e
+        
+        if attachment.data:
+            try:
+                _validate_attachment_size(attachment.data)
+            except AttachmentValidationError as e:
+                raise AttachmentValidationError(f"Size validation failed: {e}", field='data') from e
+                
+            if not _validate_base64(attachment.data):
+                raise AttachmentValidationError(
+                    'Invalid base64 data format in attachment',
+                    field='data'
+                )
+        
+        # Validate MIME type based on attachment kind
+        if attachment.kind == 'image':
+            try:
+                _validate_mime_type(attachment.mime_type, ALLOWED_IMAGE_MIME_TYPES, 'image')
+            except AttachmentValidationError as e:
+                raise AttachmentValidationError(f"Image MIME type validation failed: {e}", field='mime_type') from e
+        elif attachment.kind == 'document':
+            try:
+                _validate_mime_type(attachment.mime_type, ALLOWED_DOCUMENT_MIME_TYPES, 'document')
+            except AttachmentValidationError as e:
+                raise AttachmentValidationError(f"Document MIME type validation failed: {e}", field='mime_type') from e
+        elif attachment.kind == 'file':
+            # Files can have any MIME type, but still validate format
+            if attachment.format and len(attachment.format) > MAX_FORMAT_LENGTH:
+                raise AttachmentValidationError(
+                    f'File format "{attachment.format}" exceeds maximum length of {MAX_FORMAT_LENGTH} characters',
+                    field='format'
+                )
+    except AttachmentValidationError:
+        raise
+    except Exception as e:
+        raise AttachmentValidationError(f"Unexpected validation error: {e}") from e
+
+
+# Legacy function for backwards compatibility
+def assert_non_empty_attachment(attachment: Attachment) -> None:
+    """Legacy function for backwards compatibility."""
+    validate_attachment(attachment)
+
+
+# Export validation constants for external use
+ATTACHMENT_LIMITS = {
+    'MAX_SIZE': MAX_ATTACHMENT_SIZE,
+    'MAX_FILENAME_LENGTH': MAX_FILENAME_LENGTH,
+    'ALLOWED_IMAGE_MIME_TYPES': ALLOWED_IMAGE_MIME_TYPES,
+    'ALLOWED_DOCUMENT_MIME_TYPES': ALLOWED_DOCUMENT_MIME_TYPES,
+}