flowyml 1.1.0__py3-none-any.whl

flowyml/assets/report.py

@@ -0,0 +1,315 @@
+"""Report asset for generated reports and visualizations."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Literal
+
+from flowyml.assets.base import Asset, AssetMetadata
+
+
+ReportFormat = Literal["html", "pdf", "markdown", "json"]
+
+
+@dataclass
+class ReportMetadata(AssetMetadata):
+    """Metadata specific to Reports."""
+
+    report_format: str = "html"
+    title: str | None = None
+    author: str | None = None
+    generated_at: str | None = None
+    file_path: str | None = None
+    file_size_bytes: int = 0
+    sections: list[str] = field(default_factory=list)
+
+
+class Report(Asset):
+    """Asset representing a generated report.
+
+    Reports can be HTML dashboards, PDF documents, markdown files, or JSON data.
+
+    Example:
+        ```python
+        from flowyml import Report
+
+        # Create HTML report
+        report = Report.create(
+            content=html_content,
+            name="experiment_report",
+            format="html",
+            title="Experiment Results",
+            sections=["Overview", "Metrics", "Conclusions"],
+        )
+
+        # Save to file
+        report.save_to_file("reports/experiment_report.html")
+        ```
+    """
+
+    def __init__(
+        self,
+        name: str,
+        content: Any | None = None,
+        report_format: ReportFormat = "html",
+        title: str | None = None,
+        file_path: str | None = None,
+        **kwargs,
+    ):
+        """Initialize a Report.
+
+        Args:
+            name: Name of the report
+            content: Report content (string or bytes)
+            report_format: Report format
+            title: Report title
+            file_path: Path to saved report file
+            **kwargs: Additional metadata
+        """
+        # Extract Report-specific arguments before passing to parent
+        # report_format is already correct
+        report_title = title or name
+        report_file_path = file_path
+
+        # Pass only Asset-compatible kwargs to parent
+        super().__init__(name=name, **kwargs)
+
+        # Add Report-specific attributes after parent init
+        self.metadata.report_format = report_format
+        self.metadata.title = report_title
+        self.metadata.generated_at = datetime.now().isoformat()
+        self.metadata.file_path = report_file_path
+        self.metadata.file_size_bytes = 0
+        self.metadata.sections = []
+
+        self._content = content
+
+        if content and isinstance(content, (str, bytes)):
+            self.metadata.file_size_bytes = len(content)
+
+    @property
+    def content(self) -> Any | None:
+        """Get report content."""
+        return self._content
+
+    @property
+    def report_format(self) -> str:
+        """Get report format."""
+        return self.metadata.report_format
+
+    @property
+    def title(self) -> str | None:
+        """Get report title."""
+        return self.metadata.title
+
+    @property
+    def file_path(self) -> str | None:
+        """Get file path if saved."""
+        return self.metadata.file_path
+
+    @property
+    def sections(self) -> list[str]:
+        """Get report sections."""
+        return self.metadata.sections
+
+    @classmethod
+    def create(
+        cls,
+        content: Any,
+        name: str | None = None,
+        report_format: ReportFormat = "html",
+        title: str | None = None,
+        sections: list[str] | None = None,
+        **kwargs,
+    ) -> "Report":
+        """Factory method to create a Report.
+
+        Args:
+            content: Report content
+            name: Report name (auto-generated if not provided)
+            report_format: Report format
+            title: Report title
+            sections: List of section names
+            **kwargs: Additional metadata
+
+        Returns:
+            New Report instance
+        """
+        if name is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            name = f"report_{timestamp}"
+
+        if sections:
+            kwargs["sections"] = sections
+
+        return cls(
+            name=name,
+            content=content,
+            report_format=report_format,
+            title=title or name,
+            **kwargs,
+        )
+
+    def save_to_file(self, path: Path | str) -> Path:
+        """Save report content to file.
+
+        Args:
+            path: File path to save to
+
+        Returns:
+            Path where file was saved
+
+        Raises:
+            ValueError: If report has no content
+        """
+        if self._content is None:
+            raise ValueError("Cannot save report with no content")
+
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write content
+        if isinstance(self._content, bytes):
+            with open(path, "wb") as f:
+                f.write(self._content)
+        else:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(str(self._content))
+
+        # Update metadata
+        self.metadata.file_path = str(path)
+        self.metadata.file_size_bytes = path.stat().st_size
+
+        return path
+
+    @classmethod
+    def load_from_file(cls, path: Path | str, name: str | None = None) -> "Report":
+        """Load report from file.
+
+        Args:
+            path: File path to load from
+            name: Report name (uses filename if not provided)
+
+        Returns:
+            Report instance
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+        """
+        path = Path(path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"Report file not found: {path}")
+
+        # Detect format from extension
+        format_map = {
+            ".html": "html",
+            ".htm": "html",
+            ".pdf": "pdf",
+            ".md": "markdown",
+            ".markdown": "markdown",
+            ".json": "json",
+        }
+        report_format = format_map.get(path.suffix.lower(), "html")
+
+        # Read content
+        if report_format == "pdf":
+            with open(path, "rb") as f:
+                content = f.read()
+        else:
+            with open(path, encoding="utf-8") as f:
+                content = f.read()
+
+        # Use filename as name if not provided
+        if name is None:
+            name = path.stem
+
+        return cls(
+            name=name,
+            content=content,
+            report_format=report_format,
+            file_path=str(path),
+        )
+
+    def to_html(self) -> str:
+        """Convert report to HTML string.
+
+        Returns:
+            HTML content
+        """
+        if self.report_format == "html":
+            return str(self._content)
+
+        elif self.report_format == "markdown":
+            try:
+                import markdown
+
+                return markdown.markdown(str(self._content))
+            except ImportError:
+                # Fallback: wrap in pre tags
+                return f"<html><body><pre>{self._content}</pre></body></html>"
+
+        elif self.report_format == "json":
+            import json
+
+            data = json.loads(str(self._content))
+            # Simple JSON to HTML conversion
+            html = "<html><body><pre>"
+            html += json.dumps(data, indent=2)
+            html += "</pre></body></html>"
+            return html
+
+        else:
+            return f"<html><body><p>Format {self.report_format} not supported for HTML conversion</p></body></html>"
+
+    def open_in_browser(self) -> None:
+        """Open report in web browser.
+
+        Works best with HTML and PDF formats.
+        """
+        import webbrowser
+        import tempfile
+
+        if self.file_path:
+            # Open existing file
+            webbrowser.open(f"file://{Path(self.file_path).absolute()}")
+        else:
+            # Create temporary file
+            with tempfile.NamedTemporaryFile(
+                mode="w" if isinstance(self._content, str) else "wb",
+                suffix=f".{self.report_format}",
+                delete=False,
+            ) as f:
+                if isinstance(self._content, bytes):
+                    f.write(self._content)
+                else:
+                    f.write(str(self._content))
+
+                temp_path = f.name
+
+            webbrowser.open(f"file://{Path(temp_path).absolute()}")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert Report to dictionary.
+
+        Returns:
+            Dictionary representation (excluding large content)
+        """
+        return {
+            "asset_id": self.asset_id,
+            "name": self.name,
+            "type": self.metadata.asset_type,
+            "report_format": self.report_format,
+            "title": self.title,
+            "file_path": self.file_path,
+            "file_size_bytes": self.metadata.file_size_bytes,
+            "sections": self.sections,
+            "generated_at": self.metadata.generated_at,
+            "created_at": self.created_at.isoformat(),
+            "tags": self.tags,
+            "properties": self.properties,
+        }
+
+    def __repr__(self) -> str:
+        size_kb = self.metadata.file_size_bytes / 1024 if self.metadata.file_size_bytes else 0
+        return f"Report(name='{self.name}', format='{self.report_format}', size={size_kb:.1f}KB, title='{self.title}')"

flowyml/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI module for flowyml."""
+
+from flowyml.cli.main import cli
+
+__all__ = ["cli"]

flowyml/cli/experiment.py

@@ -0,0 +1,232 @@
+"""Experiment tracking CLI commands."""
+
+from typing import Any
+from pathlib import Path
+import json
+
+
+def list_experiments_cmd(limit: int = 10, pipeline: str | None = None) -> list[dict[str, Any]]:
+    """List experiments.
+
+    Args:
+        limit: Maximum number of experiments to return
+        pipeline: Filter by pipeline name
+
+    Returns:
+        List of experiment dictionaries
+    """
+    experiments_dir = Path(".flowyml/experiments")
+
+    if not experiments_dir.exists():
+        return []
+
+    experiments = []
+
+    for exp_file in experiments_dir.glob("*.json"):
+        try:
+            with open(exp_file) as f:
+                exp_data = json.load(f)
+
+            # Filter by pipeline if specified
+            if pipeline and exp_data.get("pipeline_name") != pipeline:
+                continue
+
+            experiments.append(exp_data)
+        except Exception:
+            continue
+
+    # Sort by created_at
+    experiments.sort(key=lambda x: x.get("created_at", ""), reverse=True)
+
+    return experiments[:limit]
+
+
+def compare_runs(run_ids: list[str]) -> str:
+    """Compare multiple experiment runs.
+
+    Args:
+        run_ids: List of run IDs to compare
+
+    Returns:
+        Formatted comparison string
+    """
+    from flowyml.tracking.runs import Run
+
+    runs = []
+    for run_id in run_ids:
+        run_path = Path(f".flowyml/runs/{run_id}.json")
+        if run_path.exists():
+            run = Run.load(run_path)
+            runs.append(run)
+
+    if not runs:
+        return "No runs found"
+
+    # Build comparison table
+    lines = []
+    lines.append("\nRun Comparison:")
+    lines.append("-" * 80)
+
+    # Headers
+    lines.append(f"{'Metric':<30} " + " ".join(f"{r.id[:8]:>12}" for r in runs))
+    lines.append("-" * 80)
+
+    # Get all metric names
+    all_metrics = set()
+    for run in runs:
+        all_metrics.update(run.metadata.metrics.keys())
+
+    # Print metrics
+    for metric in sorted(all_metrics):
+        values = []
+        for run in runs:
+            value = run.metadata.metrics.get(metric, "-")
+            if isinstance(value, float):
+                values.append(f"{value:>12.4f}")
+            else:
+                values.append(f"{str(value):>12}")
+
+        lines.append(f"{metric:<30} " + " ".join(values))
+
+    lines.append("-" * 80)
+
+    # Get all parameter names
+    all_params = set()
+    for run in runs:
+        all_params.update(run.metadata.parameters.keys())
+
+    if all_params:
+        lines.append("\nParameters:")
+        lines.append("-" * 80)
+
+        for param in sorted(all_params):
+            values = []
+            for run in runs:
+                value = run.metadata.parameters.get(param, "-")
+                values.append(f"{str(value):>12}")
+
+            lines.append(f"{param:<30} " + " ".join(values))
+
+        lines.append("-" * 80)
+
+    # Duration
+    lines.append("\nDuration:")
+    durations = [f"{r.metadata.duration:>12.2f}s" if r.metadata.duration else f"{'N/A':>12}" for r in runs]
+    lines.append(f"{'Time':<30} " + " ".join(durations))
+
+    lines.append("-" * 80)
+
+    return "\n".join(lines)
+
+
+def export_experiment(run_id: str, export_format: str = "html") -> str:
+    """Export experiment run.
+
+    Args:
+        run_id: Run ID to export
+        export_format: Export format (html, json, markdown)
+
+    Returns:
+        Path to exported file
+    """
+    from flowyml.tracking.runs import Run
+
+    run_path = Path(f".flowyml/runs/{run_id}.json")
+    if not run_path.exists():
+        raise FileNotFoundError(f"Run {run_id} not found")
+
+    run = Run.load(run_path)
+
+    output_dir = Path(".flowyml/exports")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if export_format == "json":
+        output_file = output_dir / f"{run_id}.json"
+        run.save(output_file)
+
+    elif export_format == "markdown":
+        output_file = output_dir / f"{run_id}.md"
+        markdown = generate_markdown_report(run)
+        with open(output_file, "w") as f:
+            f.write(markdown)
+
+    elif export_format == "html":
+        output_file = output_dir / f"{run_id}.html"
+        html = generate_html_report(run)
+        with open(output_file, "w") as f:
+            f.write(html)
+
+    else:
+        raise ValueError(f"Unknown format: {export_format}")
+
+    return str(output_file)
+
+
+def generate_markdown_report(run) -> str:
+    """Generate markdown report for run."""
+    lines = []
+    lines.append(f"# Run {run.id}")
+    lines.append(f"\n**Status:** {run.status}")
+    lines.append(f"**Duration:** {run.metadata.duration:.2f}s")
+    lines.append(f"**Started:** {run.metadata.start_time}")
+
+    if run.metadata.metrics:
+        lines.append("\n## Metrics")
+        for key, value in run.metadata.metrics.items():
+            lines.append(f"- **{key}:** {value}")
+
+    if run.metadata.parameters:
+        lines.append("\n## Parameters")
+        for key, value in run.metadata.parameters.items():
+            lines.append(f"- **{key}:** {value}")
+
+    return "\n".join(lines)
+
+
+def generate_html_report(run) -> str:
+    """Generate HTML report for run."""
+    html = f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Run {run.id}</title>
+    <style>
+        body {{ font-family: Arial, sans-serif; margin: 40px; }}
+        h1 {{ color: #333; }}
+        table {{ border-collapse: collapse; width: 100%; margin-top: 20px; }}
+        th, td {{ border: 1px solid #ddd; padding: 12px; text-align: left; }}
+        th {{ background-color: #4CAF50; color: white; }}
+        .status {{ font-weight: bold; color: #4CAF50; }}
+    </style>
+</head>
+<body>
+    <h1>Run {run.id}</h1>
+    <p><strong>Status:</strong> <span class="status">{run.status}</span></p>
+    <p><strong>Duration:</strong> {run.metadata.duration:.2f}s</p>
+    <p><strong>Started:</strong> {run.metadata.start_time}</p>
+
+    <h2>Metrics</h2>
+    <table>
+        <tr><th>Metric</th><th>Value</th></tr>
+"""
+
+    for key, value in run.metadata.metrics.items():
+        html += f"        <tr><td>{key}</td><td>{value}</td></tr>\n"
+
+    html += """
+    </table>
+
+    <h2>Parameters</h2>
+    <table>
+        <tr><th>Parameter</th><th>Value</th></tr>
+"""
+
+    for key, value in run.metadata.parameters.items():
+        html += f"        <tr><td>{key}</td><td>{value}</td></tr>\n"
+
+    html += """
+    </table>
+</body>
+</html>
+"""
+    return html