ob-metaflow 2.11.13.1__py2.py3-none-any.whl → 2.19.7.1rc0__py2.py3-none-any.whl

metaflow/plugins/cards/card_modules/components.py

@@ -1,4 +1,4 @@
-from typing import Any, List, Optional, Union
+from typing import Any, List, Optional, Union, Callable
 from .basic import (
     LogComponent,
     ErrorComponent,
@@ -7,25 +7,15 @@ from .basic import (
     ImageComponent,
     SectionComponent,
     MarkdownComponent,
+    PythonCodeComponent,
 )
-from .card import MetaflowCardComponent
+from .card import MetaflowCardComponent, with_default_component_id
 from .convert_to_native_type import TaskToDict, _full_classname
 from .renderer_tools import render_safely
+from .json_viewer import JSONViewer as _JSONViewer, YAMLViewer as _YAMLViewer
 import uuid
-
-
-def create_component_id(component):
-    uuid_bit = "".join(uuid.uuid4().hex.split("-"))[:6]
-    return type(component).__name__.lower() + "_" + uuid_bit
-
-
-def with_default_component_id(func):
-    def ret_func(self, *args, **kwargs):
-        if self.component_id is None:
-            self.component_id = create_component_id(self)
-        return func(self, *args, **kwargs)
-
-    return ret_func
+import inspect
+import textwrap
 
 
 def _warning_with_component(component, msg):
@@ -667,19 +657,38 @@ class Markdown(UserComponent):
     )
     ```
 
+    Multi-line strings with indentation are automatically dedented:
+    ```
+    current.card.append(
+        Markdown(f'''
+            # Header
+            - Item 1
+            - Item 2
+        ''')
+    )
+    ```
+
     Parameters
     ----------
     text : str
-        Text formatted in Markdown.
+        Text formatted in Markdown. Leading whitespace common to all lines
+        is automatically removed to support indented multi-line strings.
     """
 
     REALTIME_UPDATABLE = True
 
+    @staticmethod
+    def _dedent_text(text):
+        """Remove common leading whitespace from all lines."""
+        if text is None:
+            return None
+        return textwrap.dedent(text)
+
     def update(self, text=None):
-        self._text = text
+        self._text = self._dedent_text(text)
 
     def __init__(self, text=None):
-        self._text = text
+        self._text = self._dedent_text(text)
 
     @with_default_component_id
     @render_safely
@@ -712,15 +721,15 @@ class ProgressBar(UserComponent):
 
     Parameters
     ----------
-    max : int
+    max : int, default 100
         The maximum value of the progress bar.
-    label : str, optional
+    label : str, optional, default None
         Optional label for the progress bar.
-    value : int, optional
+    value : int, default 0
         Optional initial value of the progress bar.
-    unit : str, optional
+    unit : str, optional, default None
         Optional unit for the progress bar.
-    metadata : str, optional
+    metadata : str, optional, default None
         Optional additional information to show on the progress bar.
     """
 
@@ -731,10 +740,10 @@ class ProgressBar(UserComponent):
     def __init__(
         self,
         max: int = 100,
-        label: str = None,
+        label: Optional[str] = None,
         value: int = 0,
-        unit: str = None,
-        metadata: str = None,
+        unit: Optional[str] = None,
+        metadata: Optional[str] = None,
     ):
         self._label = label
         self._max = max
@@ -742,7 +751,7 @@ class ProgressBar(UserComponent):
         self._unit = unit
         self._metadata = metadata
 
-    def update(self, new_value: int, metadata: str = None):
+    def update(self, new_value: int, metadata: Optional[str] = None):
         self._value = new_value
         if metadata is not None:
             self._metadata = metadata
@@ -765,6 +774,234 @@ class ProgressBar(UserComponent):
         return data
 
 
+class ValueBox(UserComponent):
+    """
+    A Value Box component for displaying key metrics with styling and change indicators.
+
+    Inspired by Shiny's value box component, this displays a primary value with optional
+    title, subtitle, theme, and change indicators.
+
+    Example:
+    ```
+    # Basic value box
+    value_box = ValueBox(
+        title="Revenue",
+        value="$1.2M",
+        subtitle="Monthly Revenue",
+        change_indicator="Up 15% from last month"
+    )
+    current.card.append(value_box)
+
+    # Themed value box
+    value_box = ValueBox(
+        title="Total Savings",
+        value=50000,
+        theme="success",
+        change_indicator="Up 30% from last month"
+    )
+    current.card.append(value_box)
+
+    # Updatable value box for real-time metrics
+    metrics_box = ValueBox(
+        title="Processing Progress",
+        value=0,
+        subtitle="Items processed"
+    )
+    current.card.append(metrics_box)
+
+    for i in range(1000):
+        metrics_box.update(value=i, change_indicator=f"Rate: {i*2}/sec")
+    ```
+
+    Parameters
+    ----------
+    title : str, optional
+        The title/label for the value box (usually displayed above the value).
+        Must be 200 characters or less.
+    value : Union[str, int, float]
+        The main value to display prominently. Required parameter.
+    subtitle : str, optional
+        Additional descriptive text displayed below the title.
+        Must be 300 characters or less.
+    theme : str, optional
+        CSS class name for styling the value box. Supported themes: 'default', 'success',
+        'warning', 'danger', 'bg-gradient-indigo-purple'. Custom themes must be valid CSS class names.
+    change_indicator : str, optional
+        Text indicating change or additional context (e.g., "Up 30% VS PREVIOUS 30 DAYS").
+        Must be 200 characters or less.
+    """
+
+    type = "valueBox"
+
+    REALTIME_UPDATABLE = True
+
+    # Valid built-in themes
+    VALID_THEMES = {
+        "default",
+        "success",
+        "warning",
+        "danger",
+        "bg-gradient-indigo-purple",
+    }
+
+    def __init__(
+        self,
+        title: Optional[str] = None,
+        value: Union[str, int, float] = "",
+        subtitle: Optional[str] = None,
+        theme: Optional[str] = None,
+        change_indicator: Optional[str] = None,
+    ):
+        # Validate inputs
+        self._validate_title(title)
+        self._validate_value(value)
+        self._validate_subtitle(subtitle)
+        self._validate_theme(theme)
+        self._validate_change_indicator(change_indicator)
+
+        self._title = title
+        self._value = value
+        self._subtitle = subtitle
+        self._theme = theme
+        self._change_indicator = change_indicator
+
+    def update(
+        self,
+        title: Optional[str] = None,
+        value: Optional[Union[str, int, float]] = None,
+        subtitle: Optional[str] = None,
+        theme: Optional[str] = None,
+        change_indicator: Optional[str] = None,
+    ):
+        """
+        Update the value box with new data.
+
+        Parameters
+        ----------
+        title : str, optional
+            New title for the value box.
+        value : Union[str, int, float], optional
+            New value to display.
+        subtitle : str, optional
+            New subtitle text.
+        theme : str, optional
+            New theme/styling class.
+        change_indicator : str, optional
+            New change indicator text.
+        """
+        if title is not None:
+            self._validate_title(title)
+            self._title = title
+        if value is not None:
+            self._validate_value(value)
+            self._value = value
+        if subtitle is not None:
+            self._validate_subtitle(subtitle)
+            self._subtitle = subtitle
+        if theme is not None:
+            self._validate_theme(theme)
+            self._theme = theme
+        if change_indicator is not None:
+            self._validate_change_indicator(change_indicator)
+            self._change_indicator = change_indicator
+
+    def _validate_title(self, title: Optional[str]) -> None:
+        """Validate title parameter."""
+        if title is not None:
+            if not isinstance(title, str):
+                raise TypeError(f"Title must be a string, got {type(title).__name__}")
+            if len(title) > 200:
+                raise ValueError(
+                    f"Title must be 200 characters or less, got {len(title)} characters"
+                )
+            if not title.strip():
+                raise ValueError("Title cannot be empty or whitespace only")
+
+    def _validate_value(self, value: Union[str, int, float]) -> None:
+        """Validate value parameter."""
+        if value is None:
+            raise ValueError("Value is required and cannot be None")
+        if not isinstance(value, (str, int, float)):
+            raise TypeError(
+                f"Value must be str, int, or float, got {type(value).__name__}"
+            )
+        if isinstance(value, str):
+            if len(value) > 100:
+                raise ValueError(
+                    f"String value must be 100 characters or less, got {len(value)} characters"
+                )
+            if not value.strip():
+                raise ValueError("String value cannot be empty or whitespace only")
+        if isinstance(value, (int, float)):
+            if not (-1e15 <= value <= 1e15):
+                raise ValueError(
+                    f"Numeric value must be between -1e15 and 1e15, got {value}"
+                )
+
+    def _validate_subtitle(self, subtitle: Optional[str]) -> None:
+        """Validate subtitle parameter."""
+        if subtitle is not None:
+            if not isinstance(subtitle, str):
+                raise TypeError(
+                    f"Subtitle must be a string, got {type(subtitle).__name__}"
+                )
+            if len(subtitle) > 300:
+                raise ValueError(
+                    f"Subtitle must be 300 characters or less, got {len(subtitle)} characters"
+                )
+            if not subtitle.strip():
+                raise ValueError("Subtitle cannot be empty or whitespace only")
+
+    def _validate_theme(self, theme: Optional[str]) -> None:
+        """Validate theme parameter."""
+        if theme is not None:
+            if not isinstance(theme, str):
+                raise TypeError(f"Theme must be a string, got {type(theme).__name__}")
+            if not theme.strip():
+                raise ValueError("Theme cannot be empty or whitespace only")
+            # Allow custom themes but warn if not in valid set
+            if theme not in self.VALID_THEMES:
+                import re
+
+                # Basic CSS class name validation
+                if not re.match(r"^[a-zA-Z][a-zA-Z0-9_-]*$", theme):
+                    raise ValueError(
+                        f"Theme must be a valid CSS class name, got '{theme}'"
+                    )
+
+    def _validate_change_indicator(self, change_indicator: Optional[str]) -> None:
+        """Validate change_indicator parameter."""
+        if change_indicator is not None:
+            if not isinstance(change_indicator, str):
+                raise TypeError(
+                    f"Change indicator must be a string, got {type(change_indicator).__name__}"
+                )
+            if len(change_indicator) > 200:
+                raise ValueError(
+                    f"Change indicator must be 200 characters or less, got {len(change_indicator)} characters"
+                )
+            if not change_indicator.strip():
+                raise ValueError("Change indicator cannot be empty or whitespace only")
+
+    @with_default_component_id
+    @render_safely
+    def render(self):
+        data = {
+            "type": self.type,
+            "id": self.component_id,
+            "value": self._value,
+        }
+        if self._title is not None:
+            data["title"] = self._title
+        if self._subtitle is not None:
+            data["subtitle"] = self._subtitle
+        if self._theme is not None:
+            data["theme"] = self._theme
+        if self._change_indicator is not None:
+            data["change_indicator"] = self._change_indicator
+        return data
+
+
 class VegaChart(UserComponent):
     type = "vegaChart"
 
@@ -823,3 +1060,403 @@ class VegaChart(UserComponent):
         if self._chart_inside_table and "autosize" not in self._spec:
             data["spec"]["autosize"] = "fit-x"
         return data
+
+
+class PythonCode(UserComponent):
+    """
+    A component to display Python code with syntax highlighting.
+
+    Example:
+    ```python
+    @card
+    @step
+    def my_step(self):
+        # Using code_func
+        def my_function():
+            x = 1
+            y = 2
+            return x + y
+        current.card.append(
+            PythonCode(my_function)
+        )
+
+        # Using code_string
+        code = '''
+        def another_function():
+            return "Hello World"
+        '''
+        current.card.append(
+            PythonCode(code_string=code)
+        )
+    ```
+
+    Parameters
+    ----------
+    code_func : Callable[..., Any], optional, default None
+        The function whose source code should be displayed.
+    code_string : str, optional, default None
+        A string containing Python code to display.
+        Either code_func or code_string must be provided.
+    """
+
+    def __init__(
+        self,
+        code_func: Optional[Callable[..., Any]] = None,
+        code_string: Optional[str] = None,
+    ):
+        if code_func is not None:
+            self._code_string = inspect.getsource(code_func)
+        else:
+            self._code_string = code_string
+
+    @with_default_component_id
+    @render_safely
+    def render(self):
+        if self._code_string is None:
+            return ErrorComponent(
+                "`PythonCode` component requires a `code_func` or `code_string` argument. ",
+                "None provided for both",
+            ).render()
+        _code_component = PythonCodeComponent(self._code_string)
+        _code_component.component_id = self.component_id
+        return _code_component.render()
+
+
+class EventsTimeline(UserComponent):
+    """
+    An events timeline component for displaying structured log messages in real-time.
+
+    This component displays events in a timeline format with the latest events at the top.
+    Each event can contain structured data including other UserComponents for rich display.
+
+    Example: Basic usage
+    ```python
+    @card
+    @step
+    def my_step(self):
+        from metaflow.cards import EventsTimeline
+        from metaflow import current
+
+        # Create an events component
+        events = EventsTimeline(title="Processing Events")
+        current.card.append(events)
+
+        # Add events during processing
+        for i in range(10):
+            events.update(
+                event_data={
+                    "timestamp": datetime.now().isoformat(),
+                    "event_type": "processing",
+                    "item_id": i,
+                    "status": "completed",
+                    "duration_ms": random.randint(100, 500)
+                }
+            )
+            time.sleep(1)
+    ```
+
+    Example: With styling and rich components
+    ```python
+    from metaflow.cards import EventsTimeline, Markdown, PythonCode
+
+    events = EventsTimeline(title="Agent Actions")
+    current.card.append(events)
+
+    # Event with styling
+    events.update(
+        event_data={
+            "action": "tool_call",
+            "function": "get_weather",
+            "result": "Success"
+        },
+        style_theme="success"
+    )
+
+    # Event with rich components
+    events.update(
+        event_data={
+            "action": "code_execution",
+            "status": "completed"
+        },
+        payloads={
+            "code": PythonCode(code_string="print('Hello World')"),
+            "notes": Markdown("**Important**: This ran successfully")
+        },
+        style_theme="info"
+    )
+    ```
+
+    Parameters
+    ----------
+    title : str, optional
+        Title for the events timeline.
+    max_events : int, default 100
+        Maximum number of events to display. Older events are removed from display
+        but total count is still tracked. Stats and relative time display are always enabled.
+    """
+
+    type = "eventsTimeline"
+
+    REALTIME_UPDATABLE = True
+
+    # Valid style themes
+    VALID_THEMES = {
+        "default",
+        "success",
+        "warning",
+        "error",
+        "info",
+        "primary",
+        "secondary",
+        "tool_call",
+        "ai_response",
+    }
+
+    def __init__(
+        self,
+        title: Optional[str] = None,
+        max_events: int = 100,
+    ):
+        self._title = title
+        self._max_events = max_events
+        self._events = []
+
+        # Metadata tracking
+        self._total_events_count = 0
+        self._first_event_time = None
+        self._last_update_time = None
+        self._finished = False
+
+    def update(
+        self,
+        event_data: dict,
+        style_theme: Optional[str] = None,
+        priority: Optional[str] = None,
+        payloads: Optional[dict] = None,
+        finished: Optional[bool] = None,
+    ):
+        """
+        Add a new event to the timeline.
+
+        Parameters
+        ----------
+        event_data : dict
+            Basic event metadata (strings, numbers, simple values only).
+            This appears in the main event display area.
+        style_theme : str, optional
+            Visual theme for this event. Valid values: 'default', 'success', 'warning',
+            'error', 'info', 'primary', 'secondary', 'tool_call', 'ai_response'.
+        priority : str, optional
+            Priority level for the event ('low', 'normal', 'high', 'critical').
+            Affects visual prominence.
+        payloads : dict, optional
+            Rich payload components that will be displayed in collapsible sections.
+            Values must be UserComponent instances: ValueBox, Image, Markdown,
+            Artifact, JSONViewer, YAMLViewer. VegaChart is not supported inside EventsTimeline.
+        finished : bool, optional
+            Mark the timeline as finished. When True, the status indicator will show
+            "Finished" in the header.
+        """
+        import time
+
+        # Validate style_theme
+        if style_theme is not None and style_theme not in self.VALID_THEMES:
+            import re
+
+            if not re.match(r"^[a-zA-Z][a-zA-Z0-9_-]*$", style_theme):
+                raise ValueError(
+                    f"Invalid style_theme '{style_theme}'. Must be a valid CSS class name."
+                )
+
+        # Validate payloads contain only allowed UserComponents
+        if payloads is not None:
+            allowed_components = (
+                ValueBox,
+                Image,
+                Markdown,
+                Artifact,
+                PythonCode,
+                _JSONViewer,
+                _YAMLViewer,
+            )
+            for key, payload in payloads.items():
+                if not isinstance(payload, allowed_components):
+                    raise TypeError(
+                        f"Payload '{key}' must be one of: ValueBox, Image, Markdown, "
+                        f"Artifact, JSONViewer, YAMLViewer. Got {type(payload).__name__}"
+                    )
+
+        # Add timestamp if not provided
+        if "timestamp" not in event_data:
+            event_data["timestamp"] = time.time()
+
+        # Create event object with metadata and payloads
+        event = {
+            "metadata": event_data,
+            "payloads": payloads or {},
+            "event_id": f"event_{self._total_events_count}",
+            "received_at": time.time(),
+        }
+
+        # Add styling metadata if provided
+        if style_theme is not None:
+            event["style_theme"] = style_theme
+        if priority is not None:
+            event["priority"] = priority
+
+        # Update metadata
+        self._total_events_count += 1
+        self._last_update_time = time.time()
+        if self._first_event_time is None:
+            self._first_event_time = time.time()
+
+        # Update finished status if provided
+        if finished is not None:
+            self._finished = finished
+
+        # Add the event to the beginning of the list (latest first)
+        self._events.insert(0, event)
+
+        # Trim displayed events if we exceed max_events
+        if len(self._events) > self._max_events:
+            self._events = self._events[: self._max_events]
+
+    def get_stats(self) -> dict:
+        """
+        Get timeline statistics.
+
+        Returns
+        -------
+        dict
+            Statistics including total events, display count, timing info, etc.
+        """
+        import time
+
+        current_time = time.time()
+
+        stats = {
+            "total_events": self._total_events_count,
+            "displayed_events": len(self._events),
+            "last_update": self._last_update_time,
+            "first_event": self._first_event_time,
+        }
+
+        # seconds_since_last_update removed; UI derives recency from last event timestamp
+
+        # Add finished status
+        stats["finished"] = self._finished
+
+        if self._first_event_time and self._total_events_count > 1:
+            runtime = self._last_update_time - self._first_event_time
+            if runtime > 0:
+                stats["events_per_minute"] = round(
+                    (self._total_events_count / runtime) * 60, 1
+                )
+                stats["total_runtime_seconds"] = round(runtime, 1)
+
+        return stats
+
+    def _render_subcomponents(self):
+        """
+        Render any UserComponents within event payloads.
+        """
+        rendered_events = []
+
+        for event in self._events:
+            rendered_event = dict(event)  # Copy event metadata
+
+            # Event metadata should only contain simple values (no components)
+            rendered_event["metadata"] = event["metadata"]
+
+            # Render payload components
+            rendered_payloads = {}
+            for key, payload in event["payloads"].items():
+                if isinstance(payload, MetaflowCardComponent):
+                    # Render the component
+                    rendered_payloads[key] = payload.render()
+                else:
+                    # This shouldn't happen due to validation, but handle gracefully
+                    rendered_payloads[key] = str(payload)
+
+            rendered_event["payloads"] = rendered_payloads
+            rendered_events.append(rendered_event)
+
+        return rendered_events
+
+    @with_default_component_id
+    @render_safely
+    def render(self):
+        data = {
+            "type": self.type,
+            "id": self.component_id,
+            "events": self._render_subcomponents(),
+            "config": {
+                "show_stats": True,
+                "show_relative_time": True,
+                "max_events": self._max_events,
+            },
+        }
+
+        if self._title is not None:
+            data["title"] = self._title
+
+        # Always include stats
+        data["stats"] = self.get_stats()
+
+        return data
+
+
+# Rich viewer components
+class JSONViewer(_JSONViewer, UserComponent):
+    """
+    A component for displaying JSON data with syntax highlighting and collapsible sections.
+
+    This component provides a rich view of JSON data with proper formatting, syntax highlighting,
+    and the ability to collapse/expand sections for better readability.
+
+    Example:
+    ```python
+    from metaflow.cards import JSONViewer, EventsTimeline
+    from metaflow import current
+
+    # Use in events timeline
+    events = EventsTimeline(title="API Calls")
+    events.update({
+        "action": "api_request",
+        "endpoint": "/users",
+        "payload": JSONViewer({"user_id": 123, "fields": ["name", "email"]})
+    })
+
+    # Use standalone
+    data = {"config": {"debug": True, "timeout": 30}}
+    current.card.append(JSONViewer(data, collapsible=True))
+    ```
+    """
+
+    pass
+
+
+class YAMLViewer(_YAMLViewer, UserComponent):
+    """
+    A component for displaying YAML data with syntax highlighting and collapsible sections.
+
+    This component provides a rich view of YAML data with proper formatting and syntax highlighting.
+
+    Example:
+    ```python
+    from metaflow.cards import YAMLViewer, EventsTimeline
+    from metaflow import current
+
+    # Use in events timeline
+    events = EventsTimeline(title="Configuration Changes")
+    events.update({
+        "action": "config_update",
+        "config": YAMLViewer({
+            "database": {"host": "localhost", "port": 5432},
+            "features": ["auth", "logging"]
+        })
+    })
+    ```
+    """
+
+    pass