geek-cafe-saas-sdk 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

geek_cafe_saas_sdk/domains/files/models/file.py

@@ -19,6 +19,10 @@ class File(BaseModel):
     Represents a file in the system with metadata, virtual path, and S3 location.
     Does not contain file data (stored in S3) - only metadata and references.
     
+    Multi-Tenancy:
+    - tenant_id: Organization/company (can have multiple users)
+    - owner_id: Specific user within the tenant who owns this file
+    
     Access Patterns (DynamoDB Keys):
     - pk: FILE#{tenant_id}#{file_id}
     - sk: METADATA
@@ -35,11 +39,9 @@ class File(BaseModel):
     def __init__(self):
         super().__init__()
         
-        # File Identity
-        self._file_id: str | None = None  # Unique file ID (same as self.id)
-        
-        # Ownership (inherited tenant_id from BaseModel)
-        self._owner_id: str | None = None  # User who owns the file
+        # Identity (inherited from BaseModel: id, tenant_id)
+        # Note: tenant_id = organization/company, owner_id = specific user within tenant
+        self._owner_id: str | None = None  # User ID who owns this file
         
         # File Information
         self._file_name: str | None = None  # Display name (e.g., "report.pdf")
@@ -70,25 +72,36 @@ class File(BaseModel):
         self._status: str = "active"  # "active", "archived", "deleted"
         self._is_shared: bool = False  # Has active shares
         
+        # Lineage Tracking (for data processing pipelines)
+        self._file_role: str = "standalone"  # "standalone", "original", "main", "derived"
+        self._original_file_id: str | None = None  # Root file in lineage chain
+        self._parent_file_id: str | None = None  # Immediate parent file
+        
+        # Transformation Tracking
+        self._transformation_type: str | None = None  # "convert", "clean", "process"
+        self._transformation_operation: str | None = None  # "xls_to_csv", "data_cleaning_v2"
+        self._transformation_metadata: Dict[str, Any] | None = None  # Additional operation details
+        
+        # Relationship Counts
+        self._derived_file_count: int = 0  # Number of files derived from this one
+        
         # Timestamps (inherited from BaseModel)
         # created_utc_ts, updated_utc_ts, deleted_utc_ts
     
-    # Properties - File Identity
+    # Properties - File Identity (alias for BaseModel.id)
     @property
     def file_id(self) -> str | None:
-        """Unique file ID."""
-        return self._file_id or self.id
+        """Unique file ID (alias for id)."""
+        return self.id
     
     @file_id.setter
     def file_id(self, value: str | None):
-        self._file_id = value
-        if value:
-            self.id = value
+        self.id = value
     
     # Properties - Ownership
     @property
     def owner_id(self) -> str | None:
-        """User who owns the file."""
+        """User ID who owns the file (not tenant_id - that's the organization)."""
         return self._owner_id
     
     @owner_id.setter
@@ -258,6 +271,74 @@ class File(BaseModel):
     def is_shared(self, value: bool):
         self._is_shared = bool(value)
     
+    # Properties - Lineage Tracking
+    @property
+    def file_role(self) -> str:
+        """File role in lineage chain: 'standalone', 'original', 'main', 'derived'."""
+        return self._file_role
+    
+    @file_role.setter
+    def file_role(self, value: str | None):
+        valid_roles = ["standalone", "original", "main", "derived"]
+        if value in valid_roles:
+            self._file_role = value
+        else:
+            self._file_role = "standalone"
+    
+    @property
+    def original_file_id(self) -> str | None:
+        """Root file in lineage chain."""
+        return self._original_file_id
+    
+    @original_file_id.setter
+    def original_file_id(self, value: str | None):
+        self._original_file_id = value
+    
+    @property
+    def parent_file_id(self) -> str | None:
+        """Immediate parent file."""
+        return self._parent_file_id
+    
+    @parent_file_id.setter
+    def parent_file_id(self, value: str | None):
+        self._parent_file_id = value
+    
+    @property
+    def transformation_type(self) -> str | None:
+        """Type of transformation applied: 'convert', 'clean', 'process'."""
+        return self._transformation_type
+    
+    @transformation_type.setter
+    def transformation_type(self, value: str | None):
+        self._transformation_type = value
+    
+    @property
+    def transformation_operation(self) -> str | None:
+        """Specific operation performed (e.g., 'xls_to_csv', 'data_cleaning_v2')."""
+        return self._transformation_operation
+    
+    @transformation_operation.setter
+    def transformation_operation(self, value: str | None):
+        self._transformation_operation = value
+    
+    @property
+    def transformation_metadata(self) -> Dict[str, Any] | None:
+        """Additional transformation details."""
+        return self._transformation_metadata
+    
+    @transformation_metadata.setter
+    def transformation_metadata(self, value: Dict[str, Any] | None):
+        self._transformation_metadata = value if isinstance(value, dict) else None
+    
+    @property
+    def derived_file_count(self) -> int:
+        """Number of files derived from this one."""
+        return self._derived_file_count
+    
+    @derived_file_count.setter
+    def derived_file_count(self, value: int | None):
+        self._derived_file_count = value if isinstance(value, int) else 0
+    
     # Helper Methods
     def is_active(self) -> bool:
         """Check if file is active."""
@@ -310,3 +391,28 @@ class File(BaseModel):
         if self._s3_bucket and self._s3_key:
             return f"s3://{self._s3_bucket}/{self._s3_key}"
         return None
+    
+    # Lineage Helper Methods
+    def has_lineage(self) -> bool:
+        """Check if file participates in lineage tracking."""
+        return self._file_role != "standalone"
+    
+    def is_original(self) -> bool:
+        """Check if this is an original file."""
+        return self._file_role == "original"
+    
+    def is_main(self) -> bool:
+        """Check if this is a main file."""
+        return self._file_role == "main"
+    
+    def is_derived(self) -> bool:
+        """Check if this is a derived file."""
+        return self._file_role == "derived"
+    
+    def is_standalone(self) -> bool:
+        """Check if this is a standalone file (no lineage)."""
+        return self._file_role == "standalone"
+    
+    def increment_derived_count(self):
+        """Increment the derived file count."""
+        self._derived_file_count += 1

geek_cafe_saas_sdk/domains/files/services/__init__.py

@@ -0,0 +1,21 @@
+"""File services.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from .file_system_service import FileSystemService
+from .directory_service import DirectoryService
+from .file_version_service import FileVersionService
+from .file_share_service import FileShareService
+from .s3_file_service import S3FileService
+from .file_lineage_service import FileLineageService
+
+__all__ = [
+    "FileSystemService",
+    "DirectoryService",
+    "FileVersionService",
+    "FileShareService",
+    "S3FileService",
+    "FileLineageService",
+]

geek_cafe_saas_sdk/domains/files/services/file_lineage_service.py

@@ -0,0 +1,487 @@
+"""
+File Lineage Service
+
+Helper service for managing file lineage and transformations.
+Works on top of FileSystemService.
+
+Geek Cafe, LLC
+MIT License. See Project Root for the license information.
+"""
+
+from typing import Dict, Any, List, Optional
+from geek_cafe_saas_sdk.domains.files.services.file_system_service import FileSystemService
+from geek_cafe_saas_sdk.domains.files.services.s3_file_service import S3FileService
+from geek_cafe_saas_sdk.domains.files.models.file import File
+from geek_cafe_saas_sdk.core.service_result import ServiceResult
+from geek_cafe_saas_sdk.core.service_errors import ValidationError, NotFoundError
+import datetime as dt
+
+
+class FileLineageService:
+    """Service for managing file lineage and transformations."""
+    
+    def __init__(self, file_service: FileSystemService, s3_service: S3FileService):
+        """
+        Initialize lineage service.
+        
+        Args:
+            file_service: FileSystemService instance
+            s3_service: S3FileService instance
+        """
+        self.file_service = file_service
+        self.s3_service = s3_service
+    
+    def create_main_file(
+        self,
+        tenant_id: str,
+        user_id: str,
+        original_file_id: str,
+        file_name: str,
+        file_data: bytes,
+        mime_type: str,
+        transformation_operation: str,
+        transformation_metadata: Optional[Dict[str, Any]] = None,
+        directory_id: Optional[str] = None
+    ) -> ServiceResult[File]:
+        """
+        Create a main file from an original file.
+        
+        Args:
+            tenant_id: Tenant ID
+            user_id: User ID
+            original_file_id: Original file ID
+            file_name: New file name (e.g., "data.csv")
+            file_data: Converted file data
+            mime_type: MIME type
+            transformation_operation: Operation name (e.g., "xls_to_csv")
+            transformation_metadata: Additional metadata
+            directory_id: Optional directory ID (inherits from original if not provided)
+        
+        Returns:
+            ServiceResult with main File
+        """
+        try:
+            # Get original file
+            original_result = self.file_service.get_by_id(
+                resource_id=original_file_id,
+                tenant_id=tenant_id,
+                user_id=user_id
+            )
+            
+            if not original_result.success:
+                return original_result
+            
+            original_file = original_result.data
+            
+            # Validate original is actually an original
+            if original_file.file_role != "original":
+                return ServiceResult.error_result(
+                    message="Source file must have role 'original'",
+                    error_code="INVALID_FILE_ROLE"
+                )
+            
+            # Use original's directory if not specified
+            target_directory_id = directory_id if directory_id is not None else original_file.directory_id
+            
+            # Create main file
+            result = self.file_service.create(
+                tenant_id=tenant_id,
+                user_id=user_id,
+                file_name=file_name,
+                file_data=file_data,
+                mime_type=mime_type,
+                directory_id=target_directory_id,
+                file_role="main",
+                parent_file_id=original_file_id,
+                original_file_id=original_file_id,
+                transformation_type="convert",
+                transformation_operation=transformation_operation,
+                transformation_metadata=transformation_metadata or {}
+            )
+            
+            if result.success:
+                # Update original file's derived count
+                self.file_service.update(
+                    resource_id=original_file_id,
+                    tenant_id=tenant_id,
+                    user_id=user_id,
+                    updates={'derived_file_count': 1}
+                )
+            
+            return result
+            
+        except Exception as e:
+            return ServiceResult.error_result(
+                message=f"Failed to create main file: {str(e)}",
+                error_code="CREATE_MAIN_FILE_FAILED",
+                error=e
+            )
+    
+    def create_derived_file(
+        self,
+        tenant_id: str,
+        user_id: str,
+        main_file_id: str,
+        file_name: str,
+        file_data: bytes,
+        transformation_operation: str,
+        transformation_metadata: Optional[Dict[str, Any]] = None,
+        directory_id: Optional[str] = None
+    ) -> ServiceResult[File]:
+        """
+        Create a derived file from a main file.
+        
+        Args:
+            tenant_id: Tenant ID
+            user_id: User ID
+            main_file_id: Main file ID (parent)
+            file_name: New file name (e.g., "data_clean_v1.csv")
+            file_data: Processed file data
+            transformation_operation: Operation name (e.g., "data_cleaning_v1")
+            transformation_metadata: Additional metadata
+            directory_id: Optional directory ID (inherits from main if not provided)
+        
+        Returns:
+            ServiceResult with derived File
+        """
+        try:
+            # Get main file
+            main_result = self.file_service.get_by_id(
+                resource_id=main_file_id,
+                tenant_id=tenant_id,
+                user_id=user_id
+            )
+            
+            if not main_result.success:
+                return main_result
+            
+            main_file = main_result.data
+            
+            # Validate main is actually a main file
+            if main_file.file_role != "main":
+                return ServiceResult.error_result(
+                    message="Source file must have role 'main'",
+                    error_code="INVALID_FILE_ROLE"
+                )
+            
+            # Use main's directory if not specified
+            target_directory_id = directory_id if directory_id is not None else main_file.directory_id
+            
+            # Create derived file
+            result = self.file_service.create(
+                tenant_id=tenant_id,
+                user_id=user_id,
+                file_name=file_name,
+                file_data=file_data,
+                mime_type=main_file.mime_type,
+                directory_id=target_directory_id,
+                file_role="derived",
+                parent_file_id=main_file_id,
+                original_file_id=main_file.original_file_id,
+                transformation_type="clean",
+                transformation_operation=transformation_operation,
+                transformation_metadata=transformation_metadata or {}
+            )
+            
+            if result.success:
+                # Atomically increment main file's derived count
+                # Re-fetch to get current count and avoid race conditions
+                fresh_main = self.file_service.get_by_id(
+                    resource_id=main_file_id,
+                    tenant_id=tenant_id,
+                    user_id=user_id
+                )
+                
+                if fresh_main.success:
+                    new_count = fresh_main.data.derived_file_count + 1
+                    self.file_service.update(
+                        resource_id=main_file_id,
+                        tenant_id=tenant_id,
+                        user_id=user_id,
+                        updates={'derived_file_count': new_count}
+                    )
+            
+            return result
+            
+        except Exception as e:
+            return ServiceResult.error_result(
+                message=f"Failed to create derived file: {str(e)}",
+                error_code="CREATE_DERIVED_FILE_FAILED",
+                error=e
+            )
+    
+    def get_lineage(
+        self,
+        file_id: str,
+        tenant_id: str,
+        user_id: str
+    ) -> ServiceResult[Dict[str, Any]]:
+        """
+        Get complete lineage for a file.
+        
+        Returns:
+            ServiceResult with lineage dict containing:
+            - selected: The selected file
+            - main: Main file (if exists)
+            - original: Original file (if exists)
+            - all_derived: List of all derived files (if viewing main)
+        """
+        try:
+            # Get selected file
+            selected_result = self.file_service.get_by_id(
+                resource_id=file_id,
+                tenant_id=tenant_id,
+                user_id=user_id
+            )
+            
+            if not selected_result.success:
+                return selected_result
+            
+            selected_file = selected_result.data
+            
+            lineage = {
+                'selected': selected_file,
+                'main': None,
+                'original': None,
+                'all_derived': []
+            }
+            
+            # Get original file
+            if selected_file.original_file_id:
+                original_result = self.file_service.get_by_id(
+                    resource_id=selected_file.original_file_id,
+                    tenant_id=tenant_id,
+                    user_id=user_id
+                )
+                if original_result.success:
+                    lineage['original'] = original_result.data
+            
+            # Get main file
+            if selected_file.is_derived() and selected_file.parent_file_id:
+                main_result = self.file_service.get_by_id(
+                    resource_id=selected_file.parent_file_id,
+                    tenant_id=tenant_id,
+                    user_id=user_id
+                )
+                if main_result.success:
+                    lineage['main'] = main_result.data
+            elif selected_file.is_main():
+                lineage['main'] = selected_file
+            
+            # Get all derived files if viewing main
+            if selected_file.is_main():
+                derived = self.list_derived_files(
+                    main_file_id=file_id,
+                    tenant_id=tenant_id,
+                    user_id=user_id
+                )
+                if derived.success:
+                    lineage['all_derived'] = derived.data
+            
+            return ServiceResult.success_result(lineage)
+            
+        except Exception as e:
+            return ServiceResult.error_result(
+                message=f"Failed to get lineage: {str(e)}",
+                error_code="GET_LINEAGE_FAILED",
+                error=e
+            )
+    
+    def list_derived_files(
+        self,
+        main_file_id: str,
+        tenant_id: str,
+        user_id: str,
+        limit: int = 100
+    ) -> ServiceResult[List[File]]:
+        """
+        List all files derived from a main file.
+        
+        Returns:
+            ServiceResult with list of derived Files
+        """
+        try:
+            # Get all user's files
+            all_files_result = self.file_service.list_files_by_owner(
+                tenant_id=tenant_id,
+                owner_id=user_id,
+                user_id=user_id,
+                limit=limit
+            )
+            
+            if not all_files_result.success:
+                return all_files_result
+            
+            # Filter to derived files from this main file
+            derived_files = [
+                f for f in all_files_result.data
+                if f.parent_file_id == main_file_id and f.is_derived()
+            ]
+            
+            # Sort by creation date
+            derived_files.sort(key=lambda f: f.created_utc_ts)
+            
+            return ServiceResult.success_result(derived_files)
+            
+        except Exception as e:
+            return ServiceResult.error_result(
+                message=f"Failed to list derived files: {str(e)}",
+                error_code="LIST_DERIVED_FAILED",
+                error=e
+            )
+    
+    def prepare_lineage_bundle(
+        self,
+        selected_file_id: str,
+        tenant_id: str,
+        user_id: str
+    ) -> ServiceResult[Dict[str, Any]]:
+        """
+        Prepare bundle of files for lineage.
+        
+        Returns:
+            ServiceResult with bundle dict containing:
+            - selected_file: Selected file
+            - main_file: Main file
+            - original_file: Original file
+            - metadata: Transformation chain info
+        """
+        try:
+            lineage_result = self.get_lineage(
+                file_id=selected_file_id,
+                tenant_id=tenant_id,
+                user_id=user_id
+            )
+            
+            if not lineage_result.success:
+                return lineage_result
+            
+            lineage = lineage_result.data
+            
+            bundle = {
+                'selected_file': lineage['selected'],
+                'main_file': lineage['main'],
+                'original_file': lineage['original'],
+                'metadata': {
+                    'selected_file_id': selected_file_id,
+                    'selected_file_name': lineage['selected'].file_name,
+                    'transformation_chain': []
+                }
+            }
+            
+            # Build transformation chain
+            if lineage['original']:
+                bundle['metadata']['transformation_chain'].append({
+                    'step': 1,
+                    'type': 'original',
+                    'file_id': lineage['original'].file_id,
+                    'file_name': lineage['original'].file_name
+                })
+            
+            if lineage['main']:
+                bundle['metadata']['transformation_chain'].append({
+                    'step': 2,
+                    'type': 'convert',
+                    'file_id': lineage['main'].file_id,
+                    'file_name': lineage['main'].file_name,
+                    'operation': lineage['main'].transformation_operation
+                })
+            
+            if lineage['selected'].is_derived():
+                bundle['metadata']['transformation_chain'].append({
+                    'step': 3,
+                    'type': 'clean',
+                    'file_id': lineage['selected'].file_id,
+                    'file_name': lineage['selected'].file_name,
+                    'operation': lineage['selected'].transformation_operation
+                })
+            
+            return ServiceResult.success_result(bundle)
+            
+        except Exception as e:
+            return ServiceResult.error_result(
+                message=f"Failed to prepare bundle: {str(e)}",
+                error_code="PREPARE_BUNDLE_FAILED",
+                error=e
+            )
+    
+    def download_lineage_bundle(
+        self,
+        selected_file_id: str,
+        tenant_id: str,
+        user_id: str
+    ) -> ServiceResult[Dict[str, Any]]:
+        """
+        Download all files in lineage chain.
+        
+        Returns:
+            ServiceResult with dict containing:
+            - selected: {'file': File, 'data': bytes}
+            - main: {'file': File, 'data': bytes}
+            - original: {'file': File, 'data': bytes}
+            - metadata: Transformation chain info
+        """
+        try:
+            bundle_result = self.prepare_lineage_bundle(
+                selected_file_id=selected_file_id,
+                tenant_id=tenant_id,
+                user_id=user_id
+            )
+            
+            if not bundle_result.success:
+                return bundle_result
+            
+            bundle = bundle_result.data
+            download_bundle = {
+                'selected': None,
+                'main': None,
+                'original': None,
+                'metadata': bundle['metadata']
+            }
+            
+            # Download selected file
+            selected_download = self.file_service.download_file(
+                tenant_id=tenant_id,
+                file_id=selected_file_id,
+                user_id=user_id
+            )
+            if selected_download.success:
+                download_bundle['selected'] = {
+                    'file': selected_download.data['file'],
+                    'data': selected_download.data['data']
+                }
+            
+            # Download main file
+            if bundle['main_file']:
+                main_download = self.file_service.download_file(
+                    tenant_id=tenant_id,
+                    file_id=bundle['main_file'].file_id,
+                    user_id=user_id
+                )
+                if main_download.success:
+                    download_bundle['main'] = {
+                        'file': main_download.data['file'],
+                        'data': main_download.data['data']
+                    }
+            
+            # Download original file
+            if bundle['original_file']:
+                original_download = self.file_service.download_file(
+                    tenant_id=tenant_id,
+                    file_id=bundle['original_file'].file_id,
+                    user_id=user_id
+                )
+                if original_download.success:
+                    download_bundle['original'] = {
+                        'file': original_download.data['file'],
+                        'data': original_download.data['data']
+                    }
+            
+            return ServiceResult.success_result(download_bundle)
+            
+        except Exception as e:
+            return ServiceResult.error_result(
+                message=f"Failed to download bundle: {str(e)}",
+                error_code="DOWNLOAD_BUNDLE_FAILED",
+                error=e
+            )