Analysis Orchestrator¶

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()