Application Services¶

def execute_workflow(
    self,
    content: str,
    filename: str,
    session_id: str,
    export_formats: Optional[List[ExportFormat]] = None,
) -> AnalysisSessionDTO:
    """
    Execute the complete analysis workflow.

    Coordinates the entire pipeline:
    1. Upload and validate file
    2. Process and merge data
    3. Export results in requested formats
    4. Update session state

    Parameters
    ----------
    content : str
        Base64-encoded file content
    filename : str
        Original filename
    session_id : str
        Unique session identifier
    export_formats : Optional[List[ExportFormat]], default=None
        Formats to export (CSV, Excel, JSON), defaults to [CSV]

    Returns
    -------
    AnalysisSessionDTO
        Complete session state with results

    Notes
    -----
    - Creates new session if doesn't exist
    - Updates progress at each step
    - Handles errors without stopping entire workflow
    - Caches results for performance
    """
    if export_formats is None:
        export_formats = [ExportFormat.CSV]

    # Initialize session
    created_at = datetime.now().isoformat()

    # Step 1: Process upload
    self._progress_tracker.update_progress(
        session_id=session_id,
        current_stage="upload",
        stage_number=1,
        total_stages=8,
        message="Processing file upload...",
    )

    upload_result = self._upload_handler.process_upload(content, filename)

    if not upload_result.success:
        # Upload failed - return early
        session = AnalysisSessionDTO(
            session_id=session_id,
            upload_result=upload_result,
            processing_result=None,
            export_results=[],
            created_at=created_at,
            is_complete=False,
        )
        self._sessions[session_id] = session
        return session

    # Step 2: Process data
    self._progress_tracker.update_progress(
        session_id=session_id,
        current_stage="processing",
        stage_number=2,
        total_stages=8,
        message="Processing and merging data...",
    )

    processing_result = self._data_processor.process(
        dataset=upload_result.dataset, session_id=session_id
    )

    # Step 3: Export results
    self._progress_tracker.update_progress(
        session_id=session_id,
        current_stage="exporting",
        stage_number=7,
        total_stages=8,
        message="Exporting results...",
    )

    export_results = []
    for fmt in export_formats:
        export_result = self._export_result_by_format(
            processing_result=processing_result, format=fmt, session_id=session_id
        )
        export_results.append(export_result)

    # Step 4: Finalize
    self._progress_tracker.update_progress(
        session_id=session_id,
        current_stage="complete",
        stage_number=8,
        total_stages=8,
        message="Analysis complete!",
    )

    session = AnalysisSessionDTO(
        session_id=session_id,
        upload_result=upload_result,
        processing_result=processing_result,
        export_results=export_results,
        created_at=created_at,
        is_complete=True,
    )

    self._sessions[session_id] = session
    return session

def process_upload(self, content: str, filename: str) -> UploadResultDTO:
    """
    Process file upload independently.

    Parameters
    ----------
    content : str
        Base64-encoded file content
    filename : str
        Original filename

    Returns
    -------
    UploadResultDTO
        Upload processing result

    Notes
    -----
    Can be used for upload-only operations without full workflow execution.
    """
    return self._upload_handler.process_upload(content, filename)

def process_data(self, dataset, session_id: str) -> MergedDataDTO:
    """
    Process data merging independently.

    Parameters
    ----------
    dataset : Dataset
        Domain entity with samples
    session_id : str
        Session identifier

    Returns
    -------
    MergedDataDTO
        Processing result

    Notes
    -----
    Can be used when upload is already complete and only processing is
    needed.
    """
    return self._data_processor.process(dataset, session_id)

def export_results(
    self,
    data: pd.DataFrame,
    session_id: str,
    formats: Optional[List[ExportFormat]] = None,
) -> List[ExportResultDTO]:
    """
    Export results in multiple formats.

    Parameters
    ----------
    data : pd.DataFrame
        Data to export
    session_id : str
        Session identifier for filenames
    formats : Optional[List[ExportFormat]], default=None
        Export formats, defaults to [CSV]

    Returns
    -------
    List[ExportResultDTO]
        List of export results

    Notes
    -----
    Can be used for exporting existing data without running the full
    workflow.
    """
    if formats is None:
        formats = [ExportFormat.CSV]

    results = []
    for fmt in formats:
        filename = f"biorempp_results_{session_id}"
        result = self._result_exporter.export(data, fmt, filename)
        results.append(result)

    return results

def get_session_state(self, session_id: str) -> Optional[AnalysisSessionDTO]:
    """
    Retrieve current session state.

    Parameters
    ----------
    session_id : str
        Session identifier

    Returns
    -------
    Optional[AnalysisSessionDTO]
        Session state or None if not found

    Notes
    -----
    Returns None if session doesn't exist.
    """
    return self._sessions.get(session_id)

def get_progress(self, session_id: str) -> Optional[ProcessingProgressDTO]:
    """
    Get current progress for a session.

    Parameters
    ----------
    session_id : str
        Session identifier

    Returns
    -------
    Optional[ProcessingProgressDTO]
        Current progress or None
    """
    return self._progress_tracker.get_progress(session_id)

def clear_session(self, session_id: str) -> None:
    """
    Clear session data and cache.

    Parameters
    ----------
    session_id : str
        Session identifier to clear

    Notes
    -----
    Removes session from memory and clears cache.
    """
    if session_id in self._sessions:
        del self._sessions[session_id]

    # Clear cache for this session
    self._cache_service.clear()

def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
    """
    Store value in cache.

    Parameters
    ----------
    key : str
        Cache key
    value : Any
        Value to cache
    ttl_seconds : Optional[int]
        Time-to-live (uses default if None)

    Notes
    -----
    If cache is full, removes oldest entry (FIFO eviction).
    """
    # Check size limit and evict if needed
    if len(self._cache) >= self._max_size:
        self._evict_oldest()

    ttl = ttl_seconds if ttl_seconds is not None else self._default_ttl

    self._cache[key] = {
        "value": value,
        "timestamp": time.time(),
        "ttl": ttl,
    }

def get(self, key: str) -> Optional[Any]:
    """
    Retrieve value from cache.

    Parameters
    ----------
    key : str
        Cache key

    Returns
    -------
    Optional[Any]
        Cached value or None if not found/expired

    Notes
    -----
    Automatically removes expired entries.
    """
    if key not in self._cache:
        return None

    entry = self._cache[key]

    # Check expiration
    if self._is_expired(entry):
        del self._cache[key]
        return None

    return entry["value"]

def delete(self, key: str) -> bool:
    """
    Remove value from cache.

    Parameters
    ----------
    key : str
        Cache key

    Returns
    -------
    bool
        True if key was deleted, False if not found
    """
    if key in self._cache:
        del self._cache[key]
        return True
    return False

def clear(self) -> None:
    """Clear entire cache."""
    self._cache.clear()

def generate_hash_key(self, content: str) -> str:
    """
    Generate SHA256 hash-based cache key.

    Parameters
    ----------
    content : str
        Content to hash (e.g., upload content or dataset identifier)

    Returns
    -------
    str
        SHA256 hash hexadecimal string

    Notes
    -----
    - Same content always generates same key (deterministic)
    - Compatible with legacy cache key generation
    """
    return hashlib.sha256(content.encode("utf-8")).hexdigest()

def has(self, key: str) -> bool:
    """
    Check if key exists and is valid (not expired).

    Parameters
    ----------
    key : str
        Cache key

    Returns
    -------
    bool
        True if key exists and not expired
    """
    if key not in self._cache:
        return False

    entry = self._cache[key]
    if self._is_expired(entry):
        del self._cache[key]
        return False

    return True

def size(self) -> int:
    """
    Get current cache size (number of entries).

    Returns
    -------
    int
        Number of cached entries
    """
    # Clean expired entries first
    self._clean_expired()
    return len(self._cache)

def start_stage(self, stage: int, stage_name: str, message: str = "") -> None:
    """
    Start a new processing stage.

    Parameters
    ----------
    stage : int
        Stage number (1-8)
    stage_name : str
        Stage description (optional, uses default if empty)
    message : str, default=""
        Initial stage message

    Raises
    ------
    ValueError
        If stage number is invalid

    Examples
    --------
    >>> tracker = ProgressTracker("session_1")
    >>> tracker.start_stage(1, "Validation", "Starting validation")
    """
    if stage < 1 or stage > self.TOTAL_STAGES:
        raise ValueError(
            f"Invalid stage number: {stage} (must be 1-{self.TOTAL_STAGES})"
        )

    self._current_stage = stage
    self._current_message = message
    self._stage_progress = 0.0

def update_progress(self, progress: float, message: Optional[str] = None) -> None:
    """
    Update progress within current stage.

    Parameters
    ----------
    progress : float
        Progress percentage within stage (0.0-100.0)
    message : Optional[str]
        Optional progress message

    Raises
    ------
    ValueError
        If progress is out of range

    Examples
    --------
    >>> tracker.start_stage(3, "Merge", "Merging data")
    >>> tracker.update_progress(50.0, "Processed 500/1000 records")
    """
    if not 0.0 <= progress <= 100.0:
        raise ValueError("Progress must be between 0.0 and 100.0")

    self._stage_progress = progress
    if message is not None:
        self._current_message = message

def complete(self) -> None:
    """
    Mark processing as complete (100%).

    Examples
    --------
    >>> tracker.complete()
    >>> tracker.get_progress().is_complete()
    True
    """
    self._current_stage = self.TOTAL_STAGES
    self._stage_progress = 100.0
    self._current_message = "Processing complete"

def set_error(self, error: str) -> None:
    """
    Set error message and halt progress.

    Parameters
    ----------
    error : str
        Error description

    Examples
    --------
    >>> tracker.set_error("Database connection failed")
    >>> tracker.get_progress().has_error()
    True
    """
    self._error = error
    self._current_message = f"Error: {error}"

def get_progress(self) -> ProcessingProgressDTO:
    """
    Get current progress as DTO.

    Returns
    -------
    ProcessingProgressDTO
        Current progress information

    Examples
    --------
    >>> tracker.start_stage(3, "Merge", "Processing")
    >>> tracker.update_progress(50.0)
    >>> dto = tracker.get_progress()
    >>> dto.current_stage
    'BioRemPP Database Merge'
    """
    overall_progress = self.calculate_overall_progress()
    estimated_time = self._calculate_estimated_time(overall_progress)

    stage_name = (
        self._stages.get(self._current_stage, "Unknown")
        if self._current_stage > 0
        else "Not Started"
    )

    return ProcessingProgressDTO(
        current_stage=stage_name,
        stage_number=max(1, self._current_stage),
        total_stages=self.TOTAL_STAGES,
        progress_percentage=overall_progress,
        message=self._current_message,
        estimated_time_remaining=estimated_time,
        error=self._error,
    )

def calculate_overall_progress(self) -> float:
    """
    Calculate weighted overall progress across all stages.

    Returns
    -------
    float
        Overall progress percentage (0.0-100.0)

    Notes
    -----
    Formula: Σ(completed_stages_weights) + (current_stage_weight * stage_progress%)

    Examples
    --------
    >>> tracker.start_stage(3, "Merge", "Processing")
    >>> tracker.update_progress(50.0)  # 50% of stage 3
    >>> overall = tracker.calculate_overall_progress()
    >>> # Stages 1-2 complete (15%) + 50% of stage 3 (15% of 30%)
    >>> round(overall, 1)
    30.0
    """
    if self._current_stage == 0:
        return 0.0

    # Sum weights of completed stages
    completed_weight = sum(
        self._stage_weights[s]
        for s in range(1, self._current_stage)
        if s in self._stage_weights
    )

    # Add progress of current stage
    current_stage_weight = self._stage_weights.get(self._current_stage, 0.0)
    current_contribution = current_stage_weight * self._stage_progress / 100.0

    total_progress = completed_weight + current_contribution

    return min(100.0, total_progress)  # Cap at 100%