Core API Reference

Complete API documentation for DeepFix Core models and types.

Models

APIRequest

Bases: BaseModel

Request model for the DeepFix analysis API.

Attributes:

Name	Type	Description
dataset_artifacts	Optional[DatasetArtifacts]	Optional dataset statistics and metadata.
training_artifacts	Optional[TrainingArtifacts]	Optional training metrics and parameters.
deepchecks_artifacts	Optional[DeepchecksArtifacts]	Optional Deepchecks validation results.
model_checkpoint_artifacts	Optional[ModelCheckpointArtifacts]	Optional model checkpoint information.
dataset_name	Optional[str]	Optional name of the dataset being analyzed.
model_name	Optional[str]	Optional name of the model being analyzed.
language	str	Language for the analysis output. Defaults to "english".

Source code in deepfix-core\src\deepfix_core\models\api.py

class APIRequest(BaseModel):
    """Request model for the DeepFix analysis API.

    Attributes:
        dataset_artifacts: Optional dataset statistics and metadata.
        training_artifacts: Optional training metrics and parameters.
        deepchecks_artifacts: Optional Deepchecks validation results.
        model_checkpoint_artifacts: Optional model checkpoint information.
        dataset_name: Optional name of the dataset being analyzed.
        model_name: Optional name of the model being analyzed.
        language: Language for the analysis output. Defaults to "english".
    """

    dataset_artifacts: Optional[DatasetArtifacts] = Field(
        default=None, description="Dataset artifacts"
    )
    training_artifacts: Optional[TrainingArtifacts] = Field(
        default=None, description="Training artifacts"
    )
    deepchecks_artifacts: Optional[DeepchecksArtifacts] = Field(
        default=None, description="Deepchecks artifacts"
    )
    model_checkpoint_artifacts: Optional[ModelCheckpointArtifacts] = Field(
        default=None, description="Model checkpoint artifacts"
    )
    dataset_name: Optional[str] = Field(default=None, description="Name of the dataset")
    model_name: Optional[str] = Field(default=None, description="Name of the model")
    language: str = Field(default="english", description="Language of the analysis")

APIResponse

Bases: BaseModel

Response from the DeepFix analysis API.

Attributes:

Name	Type	Description
agent_results	Dict[str, AgentResult]	Dictionary mapping agent names to their analysis results.
summary	Optional[str]	Optional overall summary of the analysis.
additional_outputs	Dict[str, Any]	Dictionary of additional outputs from agents.
error_messages	Optional[Dict[str, Optional[str]]]	Optional dictionary mapping agent names to error messages if they failed.

Source code in deepfix-core\src\deepfix_core\models\api.py

class APIResponse(BaseModel):
    """Response from the DeepFix analysis API.

    Attributes:
        agent_results: Dictionary mapping agent names to their analysis results.
        summary: Optional overall summary of the analysis.
        additional_outputs: Dictionary of additional outputs from agents.
        error_messages: Optional dictionary mapping agent names to error messages
            if they failed.
    """

    agent_results: Dict[str, AgentResult] = Field(
        default={}, description="Results of the agents"
    )
    summary: Optional[str] = Field(default=None, description="Summary of the analysis")
    additional_outputs: Dict[str, Any] = Field(
        default={}, description="Additional outputs from the agents"
    )
    error_messages: Optional[Dict[str, Optional[str]]] = Field(
        default=None, description="Error messages if the agents failed"
    )

    def get_results_as_dataframe(self) -> pd.DataFrame:
        """Convert all agent results to a single pandas DataFrame.

        Returns:
            DataFrame containing all findings and recommendations from all agents.
        """
        dfs = [result.to_dataframe() for result in self.agent_results.values()]
        return pd.concat(dfs).reset_index(drop=True)

    def get_results_as_text(self) -> str:
        """Convert all agent results to a formatted text string.

        Returns:
            Formatted text report with summary statistics, findings by severity,
            and agent-specific analysis.
        """
        df = self.get_results_as_dataframe()
        summary = "=" * 80
        summary += "\nSUMMARY STATISTICS"
        summary += "\n" + "=" * 80

        summary += f"\nTotal findings: {len(df)}"
        summary += f"\nAgents involved: {df['agent_name'].unique().tolist()}"
        summary += "\nSeverity distribution:"
        summary += f"\n{df['finding_severity'].value_counts().to_dict()}"

        summary += "\nPriority distribution:"
        # summary += f"\n{df['recommendation_priority'].value_counts().to_dict()}"

        for severity in df["finding_severity"].unique():
            summary += "\n" + "=" * 80
            summary += f"\n{severity.upper()} SEVERITY ISSUES"
            summary += "\n" + "=" * 80

            df_severity = df[df["finding_severity"] == severity]
            for i, (_, row) in enumerate(df_severity.iterrows()):
                summary += (
                    f"\n{i + 1}. [{row['agent_name']}] {row['finding_description']}"
                )
                summary += f"\n   Evidence: {row['finding_evidence']}"
                summary += f"\n   Action: {row['recommendation_action']}"
                summary += f"\n   Rationale: {row['recommendation_rationale']}"

        summary += "\n" + "=" * 80
        summary += "\nAGENT-SPECIFIC ANALYSIS"
        summary += "\n" + "=" * 80

        for agent in df["agent_name"].unique():
            agent_df = df[df["agent_name"] == agent]
            summary += f"\n{agent}:"
            summary += f"\n  - Findings: {len(agent_df)}"
            summary += f"\n  - Artifacts analyzed: {agent_df['analyzed_artifacts'].iloc[0] if not agent_df.empty else 'None'}"
            if agent_df["summary"].iloc[0]:
                summary += f"\n  - Summary: {agent_df['summary'].iloc[0]}"

        return summary

    def to_text(self, verbose: bool = False) -> str:
        """Generate a beautifully formatted analysis report using Rich.

        Args:
            verbose: If False, only show results from CrossArtifactReasoningAgent.
                If True, show results from all agents.

        Returns:
            Formatted text report with Rich formatting for terminal display.

        Raises:
            ValueError: If verbose=False and no CrossArtifactReasoningAgent results
                are found.
        """
        # Create a string buffer to capture Rich output
        buffer = StringIO()
        console = Console(file=buffer, width=120, force_terminal=True)

        df = self.get_results_as_dataframe()

        if not verbose:
            mask = df["agent_name"].isin(["CrossArtifactReasoningAgent"])
            if not any(mask):
                raise ValueError(
                    f"No analysis results found for ``CrossArtifactReasoningAgent``. Available agents: {', '.join(self.agent_results.keys())}"
                )
            df = df[mask]

        # Header Panel
        header_text = Text(
            "DEEPFIX ANALYSIS RESULT", style="bold blue", justify="center"
        )
        console.print(Panel(header_text, style="bold blue"))
        console.print()

        # Context Information (if available)
        if self.additional_outputs.get(
            "optimization_areas"
        ) or self.additional_outputs.get("constraints"):
            context_table = Table(show_header=False, box=None, padding=(0, 2))
            context_table.add_column("Label", style="blue bold")
            context_table.add_column("Value", style="black")

            if self.additional_outputs.get("optimization_areas"):
                context_table.add_row(
                    "Optimization Areas",
                    str(self.additional_outputs["optimization_areas"]),
                )
            if self.additional_outputs.get("constraints"):
                context_table.add_row(
                    "Constraints", str(self.additional_outputs["constraints"])
                )

            console.print(
                Panel(
                    context_table,
                    title="[bold blue]Context[/bold blue]",
                    border_style="blue",
                )
            )
            console.print()

        # Summary Panel
        if self.summary:
            summary_text = Text(self.summary, style="black")
            console.print(
                Panel(
                    summary_text,
                    title="[bold green]Summary[/bold green]",
                    border_style="green",
                )
            )
            console.print()

        # Summary Statistics Table
        stats_table = self._summary_table(df, verbose=verbose)
        console.print(stats_table)
        console.print()

        # Issues by Severity
        for severity in sorted(
            df["finding_severity"].unique(),
            key=lambda x: {"high": 0, "medium": 1, "low": 2}.get(x, 3),
        ):
            severity_color = {"high": "red", "medium": "yellow", "low": "green"}.get(
                severity, "black"
            )
            df_severity = df[df["finding_severity"] == severity]

            # Create a table for issues of this severity
            issues_table = self._issues_table(
                df_severity, severity, severity_color, verbose=verbose
            )
            console.print(issues_table)
            console.print()

        # Agent-Specific Analysis
        # if verbose:
        #    agent_table = self._agent_table(df)
        #    console.print(agent_table)

        # Get the string output
        return buffer.getvalue()

    def _summary_table(self, df: pd.DataFrame, verbose: bool = False) -> Table:
        """Create a Rich table with summary statistics.

        Args:
            df: DataFrame containing agent results.
            verbose: If True, include agents involved in the summary.

        Returns:
            Rich Table object with summary statistics.
        """
        stats_table = Table(
            title="Summary Statistics",
            show_header=True,
            header_style="bold blue",
            box=None,
        )
        stats_table.add_column("Metric", style="blue bold", width=30)
        stats_table.add_column("Value", style="black", width=60)

        stats_table.add_row("Total Findings", str(len(df)))
        if verbose:
            stats_table.add_row(
                "Agents Involved", ", ".join(df["agent_name"].unique().tolist())
            )

        # Severity distribution with color coding
        severity_counts = df["finding_severity"].value_counts().to_dict()
        severity_text = Text()
        for severity, count in severity_counts.items():
            color = {"high": "red", "medium": "yellow", "low": "green"}.get(
                severity, "black"
            )
            severity_text.append(
                f"{severity.upper()}: {count}  ", style=f"bold {color}"
            )
        stats_table.add_row("Severity Distribution", severity_text)

        # Priority distribution with color coding
        # priority_counts = df['recommendation_priority'].value_counts().to_dict()
        # priority_text = Text()
        # for priority, count in priority_counts.items():
        #    color = {"high": "red", "medium": "yellow", "low": "green"}.get(priority, "black")
        #    priority_text.append(f"{priority.upper()}: {count}  ", style=f"bold {color}")
        # stats_table.add_row("Priority Distribution", priority_text)

        return stats_table

    def _issues_table(
        self,
        df_severity: pd.DataFrame,
        severity: Severity,
        severity_color: str,
        verbose: bool = False,
    ) -> Table:
        """Create a Rich table for issues of a specific severity.

        Args:
            df_severity: DataFrame filtered to issues of the given severity.
            severity: Severity level (high, medium, low).
            severity_color: Color to use for the table border and headers.
            verbose: If True, include agent name column.

        Returns:
            Rich Table object with issues of the specified severity.
        """
        issues_table = Table(
            title=f"{severity.upper()} Severity Issues ({len(df_severity)})",
            show_header=True,
            header_style=f"bold {severity_color}",
            border_style=severity_color,
            expand=False,
        )
        issues_table.add_column("#", style="dim", width=3)
        if verbose:
            issues_table.add_column("Agent", style="blue bold", width=30)
        issues_table.add_column("Finding", style="black", width=40)
        issues_table.add_column("Action", style="black", width=40)

        for i, (_, row) in enumerate(df_severity.iterrows(), 1):
            if verbose:
                issues_table.add_row(
                    str(i),
                    row["agent_name"],
                    f"{row['finding_description']}\n[dim]Evidence: {row['finding_evidence']}[/dim]",
                    f"{row['recommendation_action']}\n[dim italic]{row['recommendation_rationale']}[/dim italic]",
                )
            else:
                issues_table.add_row(
                    str(i),
                    f"{row['finding_description']}\n[dim]Evidence: {row['finding_evidence']}[/dim]",
                    f"{row['recommendation_action']}\n[dim italic]{row['recommendation_rationale']}[/dim italic]",
                )
        return issues_table

    def _agent_table(self, df: pd.DataFrame) -> Table:
        """Create a Rich table with agent-specific analysis summary.

        Args:
            df: DataFrame containing agent results.

        Returns:
            Rich Table object with agent-specific statistics.
        """
        # Agent-Specific Analysis
        agent_table = Table(
            title="Agent-Specific Analysis",
            show_header=True,
            header_style="bold blue",
            border_style="blue",
        )
        # agent_table.add_column("Agent", style="blue bold", width=30)
        agent_table.add_column("Findings", justify="center", style="yellow", width=10)
        agent_table.add_column("Artifacts", style="black", width=30)
        agent_table.add_column("Summary", style="black", width=40)

        for agent in df["agent_name"].unique():
            agent_df = df[df["agent_name"] == agent]
            artifacts = (
                agent_df["analyzed_artifacts"].iloc[0] if not agent_df.empty else "None"
            )
            summary = (
                agent_df["summary"].iloc[0] if agent_df["summary"].iloc[0] else "N/A"
            )

            agent_table.add_row(
                # agent,
                str(len(agent_df)),
                artifacts,
                summary,
            )
        return agent_table

get_results_as_dataframe()

Convert all agent results to a single pandas DataFrame.

Returns:

Type	Description
DataFrame	DataFrame containing all findings and recommendations from all agents.

Source code in deepfix-core\src\deepfix_core\models\api.py

def get_results_as_dataframe(self) -> pd.DataFrame:
    """Convert all agent results to a single pandas DataFrame.

    Returns:
        DataFrame containing all findings and recommendations from all agents.
    """
    dfs = [result.to_dataframe() for result in self.agent_results.values()]
    return pd.concat(dfs).reset_index(drop=True)

get_results_as_text()

Convert all agent results to a formatted text string.

Returns:

Type	Description
str	Formatted text report with summary statistics, findings by severity,
str	and agent-specific analysis.

Source code in deepfix-core\src\deepfix_core\models\api.py

def get_results_as_text(self) -> str:
    """Convert all agent results to a formatted text string.

    Returns:
        Formatted text report with summary statistics, findings by severity,
        and agent-specific analysis.
    """
    df = self.get_results_as_dataframe()
    summary = "=" * 80
    summary += "\nSUMMARY STATISTICS"
    summary += "\n" + "=" * 80

    summary += f"\nTotal findings: {len(df)}"
    summary += f"\nAgents involved: {df['agent_name'].unique().tolist()}"
    summary += "\nSeverity distribution:"
    summary += f"\n{df['finding_severity'].value_counts().to_dict()}"

    summary += "\nPriority distribution:"
    # summary += f"\n{df['recommendation_priority'].value_counts().to_dict()}"

    for severity in df["finding_severity"].unique():
        summary += "\n" + "=" * 80
        summary += f"\n{severity.upper()} SEVERITY ISSUES"
        summary += "\n" + "=" * 80

        df_severity = df[df["finding_severity"] == severity]
        for i, (_, row) in enumerate(df_severity.iterrows()):
            summary += (
                f"\n{i + 1}. [{row['agent_name']}] {row['finding_description']}"
            )
            summary += f"\n   Evidence: {row['finding_evidence']}"
            summary += f"\n   Action: {row['recommendation_action']}"
            summary += f"\n   Rationale: {row['recommendation_rationale']}"

    summary += "\n" + "=" * 80
    summary += "\nAGENT-SPECIFIC ANALYSIS"
    summary += "\n" + "=" * 80

    for agent in df["agent_name"].unique():
        agent_df = df[df["agent_name"] == agent]
        summary += f"\n{agent}:"
        summary += f"\n  - Findings: {len(agent_df)}"
        summary += f"\n  - Artifacts analyzed: {agent_df['analyzed_artifacts'].iloc[0] if not agent_df.empty else 'None'}"
        if agent_df["summary"].iloc[0]:
            summary += f"\n  - Summary: {agent_df['summary'].iloc[0]}"

    return summary

to_text(verbose=False)

Generate a beautifully formatted analysis report using Rich.

Parameters:

Name	Type	Description	Default
verbose	bool	If False, only show results from CrossArtifactReasoningAgent. If True, show results from all agents.	False

Returns:

Type	Description
str	Formatted text report with Rich formatting for terminal display.

Raises:

Type	Description
ValueError	If verbose=False and no CrossArtifactReasoningAgent results are found.

Source code in deepfix-core\src\deepfix_core\models\api.py

def to_text(self, verbose: bool = False) -> str:
    """Generate a beautifully formatted analysis report using Rich.

    Args:
        verbose: If False, only show results from CrossArtifactReasoningAgent.
            If True, show results from all agents.

    Returns:
        Formatted text report with Rich formatting for terminal display.

    Raises:
        ValueError: If verbose=False and no CrossArtifactReasoningAgent results
            are found.
    """
    # Create a string buffer to capture Rich output
    buffer = StringIO()
    console = Console(file=buffer, width=120, force_terminal=True)

    df = self.get_results_as_dataframe()

    if not verbose:
        mask = df["agent_name"].isin(["CrossArtifactReasoningAgent"])
        if not any(mask):
            raise ValueError(
                f"No analysis results found for ``CrossArtifactReasoningAgent``. Available agents: {', '.join(self.agent_results.keys())}"
            )
        df = df[mask]

    # Header Panel
    header_text = Text(
        "DEEPFIX ANALYSIS RESULT", style="bold blue", justify="center"
    )
    console.print(Panel(header_text, style="bold blue"))
    console.print()

    # Context Information (if available)
    if self.additional_outputs.get(
        "optimization_areas"
    ) or self.additional_outputs.get("constraints"):
        context_table = Table(show_header=False, box=None, padding=(0, 2))
        context_table.add_column("Label", style="blue bold")
        context_table.add_column("Value", style="black")

        if self.additional_outputs.get("optimization_areas"):
            context_table.add_row(
                "Optimization Areas",
                str(self.additional_outputs["optimization_areas"]),
            )
        if self.additional_outputs.get("constraints"):
            context_table.add_row(
                "Constraints", str(self.additional_outputs["constraints"])
            )

        console.print(
            Panel(
                context_table,
                title="[bold blue]Context[/bold blue]",
                border_style="blue",
            )
        )
        console.print()

    # Summary Panel
    if self.summary:
        summary_text = Text(self.summary, style="black")
        console.print(
            Panel(
                summary_text,
                title="[bold green]Summary[/bold green]",
                border_style="green",
            )
        )
        console.print()

    # Summary Statistics Table
    stats_table = self._summary_table(df, verbose=verbose)
    console.print(stats_table)
    console.print()

    # Issues by Severity
    for severity in sorted(
        df["finding_severity"].unique(),
        key=lambda x: {"high": 0, "medium": 1, "low": 2}.get(x, 3),
    ):
        severity_color = {"high": "red", "medium": "yellow", "low": "green"}.get(
            severity, "black"
        )
        df_severity = df[df["finding_severity"] == severity]

        # Create a table for issues of this severity
        issues_table = self._issues_table(
            df_severity, severity, severity_color, verbose=verbose
        )
        console.print(issues_table)
        console.print()

    # Agent-Specific Analysis
    # if verbose:
    #    agent_table = self._agent_table(df)
    #    console.print(agent_table)

    # Get the string output
    return buffer.getvalue()

AgentResult

Bases: BaseModel

Result from an analysis agent.

Attributes:

Name	Type	Description
agent_name	str	Name of the agent that performed the analysis.
analysis	List[Analysis]	List of analysis results (findings and recommendations).
analyzed_artifacts	Optional[List[str]]	Optional list of artifact types that were analyzed.
retrieved_knowledge	Optional[List[str]]	Optional list of external knowledge sources used.
additional_outputs	Dict[str, Any]	Dictionary of additional outputs from the agent.
error_message	Optional[str]	Optional error message if the agent failed.

Source code in deepfix-core\src\deepfix_core\models\analysis.py

class AgentResult(BaseModel):
    """Result from an analysis agent.

    Attributes:
        agent_name: Name of the agent that performed the analysis.
        analysis: List of analysis results (findings and recommendations).
        analyzed_artifacts: Optional list of artifact types that were analyzed.
        retrieved_knowledge: Optional list of external knowledge sources used.
        additional_outputs: Dictionary of additional outputs from the agent.
        error_message: Optional error message if the agent failed.
    """

    agent_name: str
    analysis: List[Analysis] = Field(
        default=[], description="List of Analysis elements"
    )
    analyzed_artifacts: Optional[List[str]] = Field(
        default=None, description="List of artifacts analyzed by the agent"
    )
    retrieved_knowledge: Optional[List[str]] = Field(
        default=None, description="External knowledge relevant to the analysis"
    )
    additional_outputs: Dict[str, Any] = Field(
        default={}, description="Additional outputs from the agent"
    )
    error_message: Optional[str] = Field(
        default=None, description="Error message if the agent failed"
    )

    def to_dataframe(self) -> pd.DataFrame:
        """Convert agent results to a pandas DataFrame.

        Each row represents one analysis (finding + recommendation) with
        all associated metadata.

        Returns:
            DataFrame with columns: agent_name, analyzed_artifacts,
            retrieved_knowledge, summary, finding_description, finding_evidence,
            error_message, finding_severity, finding_confidence,
            recommendation_action, recommendation_rationale,
            recommendation_confidence.
        """
        rows = []
        for analysis in self.analysis:
            # Extract findings and recommendations from the Analysis object
            findings = analysis.findings
            recommendations = analysis.recommendations

            # Create a row combining findings and recommendations
            row = {
                "agent_name": self.agent_name,
                "analyzed_artifacts": ", ".join(self.analyzed_artifacts)
                if self.analyzed_artifacts
                else "",
                "retrieved_knowledge": ", ".join(self.retrieved_knowledge)
                if self.retrieved_knowledge
                else "",
                "summary": self.additional_outputs.get("summary", ""),
                "finding_description": findings.description,
                "finding_evidence": findings.evidence,
                "error_message": self.error_message,
                "finding_severity": findings.severity.value,
                "finding_confidence": findings.confidence,
                "recommendation_action": recommendations.action,
                "recommendation_rationale": recommendations.rationale,
                #'recommendation_priority': recommendations.priority.value,
                "recommendation_confidence": recommendations.confidence,
            }
            rows.append(row)

        return pd.DataFrame(rows)

to_dataframe()

Convert agent results to a pandas DataFrame.

Each row represents one analysis (finding + recommendation) with all associated metadata.

Returns:

Type	Description
DataFrame	DataFrame with columns: agent_name, analyzed_artifacts,
DataFrame	retrieved_knowledge, summary, finding_description, finding_evidence,
DataFrame	error_message, finding_severity, finding_confidence,
DataFrame	recommendation_action, recommendation_rationale,
DataFrame	recommendation_confidence.

Source code in deepfix-core\src\deepfix_core\models\analysis.py

def to_dataframe(self) -> pd.DataFrame:
    """Convert agent results to a pandas DataFrame.

    Each row represents one analysis (finding + recommendation) with
    all associated metadata.

    Returns:
        DataFrame with columns: agent_name, analyzed_artifacts,
        retrieved_knowledge, summary, finding_description, finding_evidence,
        error_message, finding_severity, finding_confidence,
        recommendation_action, recommendation_rationale,
        recommendation_confidence.
    """
    rows = []
    for analysis in self.analysis:
        # Extract findings and recommendations from the Analysis object
        findings = analysis.findings
        recommendations = analysis.recommendations

        # Create a row combining findings and recommendations
        row = {
            "agent_name": self.agent_name,
            "analyzed_artifacts": ", ".join(self.analyzed_artifacts)
            if self.analyzed_artifacts
            else "",
            "retrieved_knowledge": ", ".join(self.retrieved_knowledge)
            if self.retrieved_knowledge
            else "",
            "summary": self.additional_outputs.get("summary", ""),
            "finding_description": findings.description,
            "finding_evidence": findings.evidence,
            "error_message": self.error_message,
            "finding_severity": findings.severity.value,
            "finding_confidence": findings.confidence,
            "recommendation_action": recommendations.action,
            "recommendation_rationale": recommendations.rationale,
            #'recommendation_priority': recommendations.priority.value,
            "recommendation_confidence": recommendations.confidence,
        }
        rows.append(row)

    return pd.DataFrame(rows)

DatasetArtifacts

Bases: Artifacts

Artifacts containing dataset statistics and metadata.

Attributes:

Name	Type	Description
dataset_name	str	Name of the dataset.
train_statistics	Union[BaseDatasetStatistics, Dict[str, Any]]	Training dataset statistics (can be any BaseDatasetStatistics subclass or a dictionary).
task_type	TaskType	Type of ML task (classification, regression, etc.).
test_statistics	Optional[Union[BaseDatasetStatistics, Dict[str, Any]]]	Optional test/validation dataset statistics.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

class DatasetArtifacts(Artifacts):
    """Artifacts containing dataset statistics and metadata.

    Attributes:
        dataset_name: Name of the dataset.
        train_statistics: Training dataset statistics (can be any BaseDatasetStatistics
            subclass or a dictionary).
        task_type: Type of ML task (classification, regression, etc.).
        test_statistics: Optional test/validation dataset statistics.
    """

    dataset_name: str = Field(..., description="Name of the dataset")
    train_statistics: Union[BaseDatasetStatistics, Dict[str, Any]] = Field(
        ..., description="Train statistics of the dataset"
    )
    task_type: TaskType = Field(..., description="Task type of the dataset")
    test_statistics: Optional[Union[BaseDatasetStatistics, Dict[str, Any]]] = Field(
        default=None, description="Test statistics of the dataset"
    )

    def to_dict(self) -> Dict[str, Any]:
        """Convert dataset artifacts to a dictionary.

        Returns:
            Dictionary representation with statistics serialized and task_type
            converted to its string value.
        """
        dumped_dict = self.model_dump()
        dumped_dict["train_statistics"] = self.train_statistics.to_dict()
        if self.test_statistics is not None:
            dumped_dict["test_statistics"] = self.test_statistics.to_dict()
        dumped_dict["task_type"] = self.task_type.value
        return dumped_dict

    @classmethod
    def from_file(cls, path: str) -> "DatasetArtifacts":
        """Load dataset artifacts from a YAML file.

        Args:
            path: Path to the YAML file containing artifact data.

        Returns:
            DatasetArtifacts instance loaded from the file.

        Raises:
            FileNotFoundError: If the file does not exist.
            yaml.YAMLError: If the file contains invalid YAML.
        """
        with open(path, "r", encoding="utf-8") as f:
            d = yaml.safe_load(f)
        return cls(**d)

from_file(path) classmethod

Load dataset artifacts from a YAML file.

Parameters:

Name	Type	Description	Default
path	str	Path to the YAML file containing artifact data.	required

Returns:

Type	Description
'DatasetArtifacts'	DatasetArtifacts instance loaded from the file.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.
YAMLError	If the file contains invalid YAML.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

@classmethod
def from_file(cls, path: str) -> "DatasetArtifacts":
    """Load dataset artifacts from a YAML file.

    Args:
        path: Path to the YAML file containing artifact data.

    Returns:
        DatasetArtifacts instance loaded from the file.

    Raises:
        FileNotFoundError: If the file does not exist.
        yaml.YAMLError: If the file contains invalid YAML.
    """
    with open(path, "r", encoding="utf-8") as f:
        d = yaml.safe_load(f)
    return cls(**d)

to_dict()

Convert dataset artifacts to a dictionary.

Returns:

Type	Description
Dict[str, Any]	Dictionary representation with statistics serialized and task_type
Dict[str, Any]	converted to its string value.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

def to_dict(self) -> Dict[str, Any]:
    """Convert dataset artifacts to a dictionary.

    Returns:
        Dictionary representation with statistics serialized and task_type
        converted to its string value.
    """
    dumped_dict = self.model_dump()
    dumped_dict["train_statistics"] = self.train_statistics.to_dict()
    if self.test_statistics is not None:
        dumped_dict["test_statistics"] = self.test_statistics.to_dict()
    dumped_dict["task_type"] = self.task_type.value
    return dumped_dict

DeepchecksArtifacts

Bases: Artifacts

Artifacts containing Deepchecks validation results.

Attributes:

Name	Type	Description
dataset_name	str	Name of the dataset that was validated.
model_name	Optional[str]	Optional name of the model used in validation.
results	Dict[str, List[DeepchecksParsedResult]]	Dictionary mapping check categories to lists of parsed results.
config	Optional[DeepchecksConfig]	Optional Deepchecks configuration used for validation.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

class DeepchecksArtifacts(Artifacts):
    """Artifacts containing Deepchecks validation results.

    Attributes:
        dataset_name: Name of the dataset that was validated.
        model_name: Optional name of the model used in validation.
        results: Dictionary mapping check categories to lists of parsed results.
        config: Optional Deepchecks configuration used for validation.
    """

    dataset_name: str = Field(description="Name of the dataset")
    model_name: Optional[str] = Field(default=None, description="Name of the model")
    results: Dict[str, List[DeepchecksParsedResult]] = Field(
        description="Results of the artifact"
    )
    config: Optional[DeepchecksConfig] = Field(
        default=None, description="Config of the artifact"
    )

    def to_dict(self) -> Dict[str, Any]:
        """Convert Deepchecks artifacts to a dictionary.

        Returns:
            Dictionary representation with nested results and config serialized.
        """
        dumped_dict = self.model_dump()
        dumped_dict["results"] = {
            k: [r.to_dict() for r in v] for k, v in self.results.items()
        }
        dumped_dict["config"] = self.config.to_dict() if self.config else None
        return dumped_dict

    @classmethod
    def from_dict(self, d: Union[Dict[str, Any], DictConfig]) -> "DeepchecksArtifacts":
        """Create DeepchecksArtifacts from a dictionary.

        Args:
            d: Dictionary or DictConfig containing artifact data.

        Returns:
            DeepchecksArtifacts instance with parsed results and config.
        """
        results = {
            k: [DeepchecksParsedResult.from_dict(r) for r in v]
            for k, v in d["results"].items()
        }
        config = None
        if d.get("config"):
            config = DeepchecksConfig.from_dict(d["config"])
        return DeepchecksArtifacts(
            dataset_name=d["dataset_name"],
            model_name=d.get("model_name"),
            results=results,
            config=config,
        )

    @classmethod
    def from_file(cls, file_path: str) -> "DeepchecksArtifacts":
        """Load Deepchecks artifacts from a YAML file.

        Args:
            file_path: Path to the YAML file containing artifact data.

        Returns:
            DeepchecksArtifacts instance loaded from the file.

        Raises:
            FileNotFoundError: If the file does not exist.
            yaml.YAMLError: If the file contains invalid YAML.
        """
        with open(file_path, "r", encoding="utf-8") as f:
            d = yaml.safe_load(f)
        artifacts = cls.from_dict(d)
        return artifacts

from_dict(d) classmethod

Create DeepchecksArtifacts from a dictionary.

Parameters:

Name	Type	Description	Default
d	Union[Dict[str, Any], DictConfig]	Dictionary or DictConfig containing artifact data.	required

Returns:

Type	Description
'DeepchecksArtifacts'	DeepchecksArtifacts instance with parsed results and config.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

@classmethod
def from_dict(self, d: Union[Dict[str, Any], DictConfig]) -> "DeepchecksArtifacts":
    """Create DeepchecksArtifacts from a dictionary.

    Args:
        d: Dictionary or DictConfig containing artifact data.

    Returns:
        DeepchecksArtifacts instance with parsed results and config.
    """
    results = {
        k: [DeepchecksParsedResult.from_dict(r) for r in v]
        for k, v in d["results"].items()
    }
    config = None
    if d.get("config"):
        config = DeepchecksConfig.from_dict(d["config"])
    return DeepchecksArtifacts(
        dataset_name=d["dataset_name"],
        model_name=d.get("model_name"),
        results=results,
        config=config,
    )

from_file(file_path) classmethod

Load Deepchecks artifacts from a YAML file.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the YAML file containing artifact data.	required

Returns:

Type	Description
'DeepchecksArtifacts'	DeepchecksArtifacts instance loaded from the file.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.
YAMLError	If the file contains invalid YAML.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

@classmethod
def from_file(cls, file_path: str) -> "DeepchecksArtifacts":
    """Load Deepchecks artifacts from a YAML file.

    Args:
        file_path: Path to the YAML file containing artifact data.

    Returns:
        DeepchecksArtifacts instance loaded from the file.

    Raises:
        FileNotFoundError: If the file does not exist.
        yaml.YAMLError: If the file contains invalid YAML.
    """
    with open(file_path, "r", encoding="utf-8") as f:
        d = yaml.safe_load(f)
    artifacts = cls.from_dict(d)
    return artifacts

to_dict()

Convert Deepchecks artifacts to a dictionary.

Returns:

Type	Description
Dict[str, Any]	Dictionary representation with nested results and config serialized.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

def to_dict(self) -> Dict[str, Any]:
    """Convert Deepchecks artifacts to a dictionary.

    Returns:
        Dictionary representation with nested results and config serialized.
    """
    dumped_dict = self.model_dump()
    dumped_dict["results"] = {
        k: [r.to_dict() for r in v] for k, v in self.results.items()
    }
    dumped_dict["config"] = self.config.to_dict() if self.config else None
    return dumped_dict

ModelCheckpointArtifacts

Bases: Artifacts

Artifacts containing model checkpoint information.

Attributes:

Name	Type	Description
path	Optional[str]	Path to the model checkpoint file.
config	Optional[Dict[str, Any]]	Optional model configuration dictionary.
model_type	Optional[str]	Optional type or class name of the model.
hyperparameters	Optional[Dict[str, Any]]	Optional dictionary of model hyperparameters.
context	Optional[Dict[str, Any]]	Optional context information about the checkpoint.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

class ModelCheckpointArtifacts(Artifacts):
    """Artifacts containing model checkpoint information.

    Attributes:
        path: Path to the model checkpoint file.
        config: Optional model configuration dictionary.
        model_type: Optional type or class name of the model.
        hyperparameters: Optional dictionary of model hyperparameters.
        context: Optional context information about the checkpoint.
    """

    path: Optional[str] = Field(
        default=None, description="Path to the model checkpoint"
    )
    config: Optional[Dict[str, Any]] = Field(
        default=None, description="Config of the model"
    )
    model_type: Optional[str] = Field(
        default=None, description="Type/class name of the model"
    )
    hyperparameters: Optional[Dict[str, Any]] = Field(
        default=None, description="Model hyperparameters"
    )
    context: Optional[Dict[str, Any]] = Field(
        default=None, description="Context of the model checkpoint"
    )

TrainingArtifacts

Bases: Artifacts

Artifacts containing training metrics and parameters.

Attributes:

Name	Type	Description
metrics_path	Optional[str]	Optional path to a CSV file containing metrics.
metrics_values	Optional[Any]	Optional pandas DataFrame or dictionary containing metrics.
params	Optional[Dict[str, Any]]	Optional dictionary of training parameters.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

class TrainingArtifacts(Artifacts):
    """Artifacts containing training metrics and parameters.

    Attributes:
        metrics_path: Optional path to a CSV file containing metrics.
        metrics_values: Optional pandas DataFrame or dictionary containing metrics.
        params: Optional dictionary of training parameters.
    """

    model_config = {"arbitrary_types_allowed": True}

    metrics_path: Optional[str] = Field(
        default=None, description="Path to the metrics file"
    )
    metrics_values: Optional[Any] = Field(
        default=None, description="Metrics of the artifact"
    )
    params: Optional[Dict[str, Any]] = Field(
        default=None, description="Parameters of the training routine"
    )

    def to_dict(self) -> Dict[str, Any]:
        """Convert training artifacts to a dictionary.

        Converts pandas DataFrame metrics to dictionary format for serialization.

        Returns:
            Dictionary representation with metrics as lists.
        """
        dumped_dict = self.model_dump()
        if (
            isinstance(self.metrics_values, pd.DataFrame)
            and self.metrics_values is not None
        ):
            dumped_dict["metrics_values"] = self.metrics_values.to_dict(orient="list")
        return dumped_dict

    @classmethod
    def from_dict(cls, d: dict) -> "TrainingArtifacts":
        """Create TrainingArtifacts from a dictionary.

        Args:
            d: Dictionary containing artifact data. If metrics_values is present,
                it's converted to a DataFrame. If metrics_path is present, the CSV
                is loaded.

        Returns:
            TrainingArtifacts instance with loaded metrics and parameters.
        """
        if d.get("metrics_values"):
            metrics_values = pd.DataFrame.from_dict(d.get("metrics_values"))
        elif d.get("metrics_path"):
            metrics_values = pd.read_csv(d.get("metrics_path"))
        else:
            metrics_values = None
        return cls(
            metrics_path=d.get("metrics_path"),
            metrics_values=metrics_values,
            params=d.get("params"),
        )

    @classmethod
    def from_file(cls, metrics_path: str) -> "TrainingArtifacts":
        """Load training artifacts from a metrics CSV file.

        Args:
            metrics_path: Path to the CSV file containing training metrics.

        Returns:
            TrainingArtifacts instance with metrics loaded from the file.

        Raises:
            FileNotFoundError: If the file does not exist.
            pd.errors.EmptyDataError: If the CSV file is empty.
        """
        return cls(metrics_path=metrics_path, metrics_values=pd.read_csv(metrics_path))

from_dict(d) classmethod

Create TrainingArtifacts from a dictionary.

Parameters:

Name	Type	Description	Default
d	dict	Dictionary containing artifact data. If metrics_values is present, it's converted to a DataFrame. If metrics_path is present, the CSV is loaded.	required

Returns:

Type	Description
'TrainingArtifacts'	TrainingArtifacts instance with loaded metrics and parameters.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

@classmethod
def from_dict(cls, d: dict) -> "TrainingArtifacts":
    """Create TrainingArtifacts from a dictionary.

    Args:
        d: Dictionary containing artifact data. If metrics_values is present,
            it's converted to a DataFrame. If metrics_path is present, the CSV
            is loaded.

    Returns:
        TrainingArtifacts instance with loaded metrics and parameters.
    """
    if d.get("metrics_values"):
        metrics_values = pd.DataFrame.from_dict(d.get("metrics_values"))
    elif d.get("metrics_path"):
        metrics_values = pd.read_csv(d.get("metrics_path"))
    else:
        metrics_values = None
    return cls(
        metrics_path=d.get("metrics_path"),
        metrics_values=metrics_values,
        params=d.get("params"),
    )

from_file(metrics_path) classmethod

Load training artifacts from a metrics CSV file.

Parameters:

Name	Type	Description	Default
metrics_path	str	Path to the CSV file containing training metrics.	required

Returns:

Type	Description
'TrainingArtifacts'	TrainingArtifacts instance with metrics loaded from the file.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.
EmptyDataError	If the CSV file is empty.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

@classmethod
def from_file(cls, metrics_path: str) -> "TrainingArtifacts":
    """Load training artifacts from a metrics CSV file.

    Args:
        metrics_path: Path to the CSV file containing training metrics.

    Returns:
        TrainingArtifacts instance with metrics loaded from the file.

    Raises:
        FileNotFoundError: If the file does not exist.
        pd.errors.EmptyDataError: If the CSV file is empty.
    """
    return cls(metrics_path=metrics_path, metrics_values=pd.read_csv(metrics_path))

to_dict()

Convert training artifacts to a dictionary.

Converts pandas DataFrame metrics to dictionary format for serialization.

Returns:

Type	Description
Dict[str, Any]	Dictionary representation with metrics as lists.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

def to_dict(self) -> Dict[str, Any]:
    """Convert training artifacts to a dictionary.

    Converts pandas DataFrame metrics to dictionary format for serialization.

    Returns:
        Dictionary representation with metrics as lists.
    """
    dumped_dict = self.model_dump()
    if (
        isinstance(self.metrics_values, pd.DataFrame)
        and self.metrics_values is not None
    ):
        dumped_dict["metrics_values"] = self.metrics_values.to_dict(orient="list")
    return dumped_dict

Types

DataType

Bases: StrEnum

Types of data supported by the system.

Source code in deepfix-core\src\deepfix_core\models\defaults.py

class DataType(StrEnum):
    """Types of data supported by the system."""

    VISION = "vision"
    TABULAR = "tabular"
    NLP = "nlp"

ArtifactPath

Bases: StrEnum

Enumeration of artifact path identifiers.

Defines standard paths for different types of artifacts used in the system, including training artifacts, deepchecks results, and dataset metadata.

Source code in deepfix-core\src\deepfix_core\models\artifacts.py

class ArtifactPath(StrEnum):
    """Enumeration of artifact path identifiers.

    Defines standard paths for different types of artifacts used in the system,
    including training artifacts, deepchecks results, and dataset metadata.
    """

    # training artifacts
    TRAINING = "training_artifacts"
    TRAINING_METRICS = "metrics.csv"
    MODEL_CHECKPOINT = "model_checkpoint"
    TRAINING_PARAMS = "params.yaml"
    # deepchecks artifacts
    DEEPCHECKS = "deepchecks"
    # dataset artifacts
    DATASET = "dataset"

Examples

See the Quickstart Guide for usage examples.