yera 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

yera/events/blocks/__init__.py

@@ -0,0 +1,68 @@
+"""Chat-specific block construction helpers for the Yera library.
+
+This package provides block construction functions that can be used either via
+the events namespace:
+
+    import yera
+
+    yera.events.markdown(...)
+    yera.events.buttons(...)
+    ...
+
+or via the top-level re-exports:
+
+    import yera as yr
+
+    yr.markdown(...)
+    yr.buttons(...)
+    ...
+"""
+
+from __future__ import annotations
+
+from yera.events.blocks.action import action
+from yera.events.blocks.bar_chart import bar_chart
+from yera.events.blocks.base.base import _BlockFactory
+from yera.events.blocks.buttons import request_input_buttons as request_input_buttons
+from yera.events.blocks.columns import columns
+from yera.events.blocks.container import container
+from yera.events.blocks.date_picker import (
+    request_input_date_picker as request_input_date_picker,
+)
+from yera.events.blocks.exit import exit_event, quit_event
+from yera.events.blocks.form import form
+from yera.events.blocks.input_echo import input_echo as input_echo
+from yera.events.blocks.input_request import request_input_text as request_input_text
+from yera.events.blocks.line_chart import line_chart
+from yera.events.blocks.markdown import markdown
+from yera.events.blocks.slider import request_input_slider as request_input_slider
+from yera.events.blocks.spinner import spinner
+from yera.events.blocks.system_prompt import system_prompt as system_prompt
+from yera.events.blocks.table import table
+
+
+def reset_all_factories() -> None:
+    """Reset all block factory counters to 0."""
+    _BlockFactory.reset_all()
+
+
+__all__ = [
+    "action",
+    "bar_chart",
+    "columns",
+    "container",
+    "exit_event",
+    "form",
+    "input_echo",
+    "line_chart",
+    "markdown",
+    "quit_event",
+    "request_input_buttons",
+    "request_input_date_picker",
+    "request_input_slider",
+    "request_input_text",
+    "reset_all_factories",
+    "spinner",
+    "system_prompt",
+    "table",
+]

yera/events/blocks/action.py

@@ -0,0 +1,57 @@
+"""Action block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import _BlockFactory, _StreamHandle
+from yera.events.models import ActionData
+from yera.events.stream import push_output
+
+
+class ActionStream(_StreamHandle):
+    """Stream handle for creating multiple chunks of the same action block."""
+
+    def __init__(self, block_id: str, initial_message: str):
+        super().__init__(block_id, "action")
+        self.initial_message = initial_message
+
+    def __enter__(self):
+        event = self._create_chunk_event(
+            data=ActionData(status="active", message=self.initial_message),
+        )
+        push_output(event)
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        event = self._create_chunk_event(
+            data=ActionData(status="complete"),
+        )
+        push_output(event)
+        return False
+
+    def update(self, message: str) -> None:
+        """Create an update chunk with status 'active'."""
+        event = self._create_chunk_event(
+            data=ActionData(status="active", message=message),
+        )
+        push_output(event)
+
+
+class _ActionBlockFactory(_BlockFactory):
+    """Factory for action blocks. Returns a context manager when called with message."""
+
+    def __init__(self):
+        super().__init__("action")
+
+    def __call__(
+        self,
+        message: str,
+    ) -> ActionStream:
+        """Return a context manager for creating multiple action chunks."""
+        block_id = self._generate_block_id()
+        return ActionStream(block_id, message)
+
+
+# Create the action callable/context manager
+action = _ActionBlockFactory()
+
+__all__ = ["action"]

yera/events/blocks/bar_chart.py

@@ -0,0 +1,92 @@
+"""Bar chart block implementation."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+from yera.events.blocks.base import _ChartBlockFactory
+from yera.events.blocks.base.chart import _ChartConversionData
+from yera.events.models import BarChartData
+from yera.events.stream import push_output
+
+
+class _BarChartBlockFactory(_ChartBlockFactory):
+    """Factory for creating bar chart blocks, matching Streamlit's st.bar_chart API."""
+
+    def __init__(self):
+        super().__init__("bar_chart")
+
+    def _create_chart_data_from_conversion(
+        self,
+        conversion_data: _ChartConversionData,
+        chart_specific_params: dict,
+    ) -> BarChartData:
+        """Convert intermediate data to BarChartData."""
+        return BarChartData(
+            x_label=conversion_data.x_label,
+            x_categories=conversion_data.x_categories or [],
+            y_label=conversion_data.y_label,
+            y_values=conversion_data.y_values,
+            colour_label=conversion_data.colour_label,
+            colour_categories=conversion_data.colour_categories,
+            colour_values=conversion_data.colour_values,
+            horizontal=chart_specific_params.get("horizontal", False),
+            stack=chart_specific_params.get("stack", True),
+        )
+
+    def __call__(
+        self,
+        data: pd.DataFrame,
+        *,
+        x: str | None = None,
+        y: str | Sequence[str] | None = None,
+        colour: str | Sequence[str] | None = None,
+        horizontal: bool = False,
+        stack: bool = True,
+    ) -> None:
+        """Create a bar chart block, matching Streamlit's st.bar_chart() signature.
+
+        Args:
+            data: DataFrame to plot
+            x: Column name for x-axis (None = use index)
+            y: Column name(s) for y-axis (None = use all columns except x)
+            colour: Column name for colour grouping, or list of colors
+            horizontal: Whether bars are horizontal
+            stack: Whether bars are stacked
+
+        Returns:
+            None (informational block)
+
+        """
+        chart_specific_params = {"horizontal": horizontal, "stack": stack}
+
+        if x is None and y is None:
+            conversion_data = self._convert_default_format(data)
+        elif x is not None and isinstance(y, str):
+            conversion_data = self._convert_long_format(data, x, y, colour)
+        elif x is not None and isinstance(y, Sequence) and not isinstance(y, str):
+            conversion_data = self._convert_wide_format(data, x, y, colour)
+        else:
+            raise ValueError(
+                f"Unsupported bar_chart parameter combination: x={x}, y={y}"
+            )
+
+        chart_data = self._create_chart_data_from_conversion(
+            conversion_data, chart_specific_params
+        )
+
+        event = self._create_block_output_event(
+            chart_data, message_type="informational"
+        )
+        push_output(event)
+        return
+
+
+# Create the bar_chart callable
+bar_chart = _BarChartBlockFactory()
+
+__all__ = ["bar_chart"]

yera/events/blocks/base/__init__.py

@@ -0,0 +1,20 @@
+"""Base classes for block construction."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base.base import _BlockFactory, _StreamHandle
+from yera.events.blocks.base.chart import _ChartBlockFactory
+from yera.events.blocks.base.layout import (
+    LayoutContext,
+    LayoutHandle,
+    _current_layout,
+)
+
+__all__ = [
+    "LayoutContext",
+    "LayoutHandle",
+    "_BlockFactory",
+    "_ChartBlockFactory",
+    "_StreamHandle",
+    "_current_layout",
+]

yera/events/blocks/base/base.py

@@ -0,0 +1,166 @@
+"""Base classes for block construction."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from yera.agents import get_agent_context
+from yera.events.models import (
+    ActionData,
+    BarChartData,
+    ButtonsData,
+    ColumnsData,
+    ContainerData,
+    DatePickerData,
+    ExitEventData,
+    InputRequestData,
+    LayoutEndData,
+    LineChartData,
+    MarkdownData,
+    OutputEvent,
+    SliderData,
+    SpinnerData,
+    TableData,
+)
+from yera.events.models.in_event import InputEvent
+
+
+def get_parent_block_id(exclude_block_id: str | None = None) -> str | None:
+    """Get parent block ID from layout context if available."""
+    # Import here to avoid circular import
+    from yera.events.blocks.base.layout import _current_layout
+
+    layout_context = _current_layout.get()
+    if layout_context and layout_context.block_id != exclude_block_id:
+        return layout_context.block_id
+    return None
+
+
+def create_event(
+    block_type: str,
+    block_id: str,
+    data: (
+        MarkdownData
+        | ButtonsData
+        | ActionData
+        | SpinnerData
+        | DatePickerData
+        | SliderData
+        | TableData
+        | ContainerData
+        | ColumnsData
+        | BarChartData
+        | LineChartData
+        | LayoutEndData
+    ),
+    message_type: str,
+    chunk_id: int,
+    parent_block_id: str | None = None,
+) -> OutputEvent:
+    """Create an event with automatic layout context detection."""
+    agent_ctx = get_agent_context()
+
+    if parent_block_id is None:
+        parent_block_id = get_parent_block_id(exclude_block_id=block_id)
+    return OutputEvent(
+        message_type=message_type,
+        block_type=block_type,
+        block_id=block_id,
+        data=data,
+        chunk_id=chunk_id,
+        agent_instance=agent_ctx.metadata.make_instance_id(0),
+        parent_block_id=parent_block_id,
+    )
+
+
+class _StreamHandle:
+    """Base class for streamable block handles."""
+
+    def __init__(self, block_id: str, block_type: str):
+        self.block_id = block_id
+        self.block_type = block_type
+        self.chunk_counter = 0
+
+    def _create_chunk_event(
+        self,
+        data: (
+            MarkdownData
+            | ActionData
+            | SpinnerData
+            | TableData
+            | ContainerData
+            | ColumnsData
+        ),
+        message_type: str = "informational",
+        parent_block_id: str | None = None,
+    ) -> OutputEvent:
+        """Create a chunk event (for stream handles)."""
+        self.chunk_counter += 1
+        return create_event(
+            block_type=self.block_type,
+            block_id=self.block_id,
+            data=data,
+            message_type=message_type,
+            chunk_id=self.chunk_counter,
+            parent_block_id=parent_block_id,
+        )
+
+
+class _BlockFactory:
+    """Base class for block construction factories."""
+
+    _registry: ClassVar[list[_BlockFactory]] = []  # Track all factory instances
+
+    def __init__(self, block_type: str):
+        self.block_type = block_type
+        self._block_counter = 0
+        _BlockFactory._registry.append(self)  # Auto-register instance
+
+    def reset(self) -> None:
+        """Reset the block counter to 0."""
+        self._block_counter = 0
+
+    @classmethod
+    def reset_all(cls) -> None:
+        """Reset all registered factory instances."""
+        for factory in cls._registry:
+            factory.reset()
+
+    def _generate_block_id(self) -> str:
+        """Generate a block_id."""
+        self._block_counter += 1
+        return f"{self.block_type}-{self._block_counter}"
+
+    def _create_block_input_event(self) -> InputEvent:
+        pass
+
+    def _create_block_output_event(
+        self,
+        data: (
+            MarkdownData
+            | ButtonsData
+            | ActionData
+            | SpinnerData
+            | DatePickerData
+            | SliderData
+            | TableData
+            | ContainerData
+            | ColumnsData
+            | BarChartData
+            | LineChartData
+            | InputRequestData
+            | ExitEventData
+        ),
+        message_type: str,
+    ) -> OutputEvent:
+        """Create a block event (for factory methods)."""
+        return create_event(
+            block_type=self.block_type,
+            block_id=self._generate_block_id(),
+            data=data,
+            message_type=message_type,
+            chunk_id=1,  # Block events are always single chunks
+        )
+
+
+__all__ = ["_BlockFactory", "_StreamHandle"]

yera/events/blocks/base/chart.py

@@ -0,0 +1,288 @@
+"""Base chart block factory for shared chart functionality."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+from yera.events.blocks.base.base import _BlockFactory
+from yera.events.models import BarChartData, LineChartData
+
+
+def _is_hex_color(value: str) -> bool:
+    """Check if a string is a valid hex color (starts with # and has valid hex digits).
+
+    Raises ValueError if the value is not a valid hex color format.
+    """
+    if not value.startswith("#"):
+        raise ValueError(f"Hex color must start with '#', got: {value!r}")
+    if len(value) not in (4, 7):  # #rgb or #rrggbb format
+        raise ValueError(
+            f"Hex color must be 4 or 7 characters (#rgb or #rrggbb), got {len(value)} characters: {value!r}"
+        )
+    # Check that all characters after # are valid hex digits (0-9, a-f, A-F)
+    hex_digits = set("0123456789abcdefABCDEF")
+    invalid_chars = [c for c in value[1:] if c not in hex_digits]
+    if invalid_chars:
+        raise ValueError(
+            f"Hex color contains invalid characters: {invalid_chars}. "
+            f"Only 0-9, a-f, A-F are allowed after '#'. Got: {value!r}"
+        )
+    return True
+
+
+def _get_default_colors(count: int) -> list[str]:
+    """Get default colors for the given number of series."""
+    default_palette = ["#FF0000", "#00FF00", "#0000FF", "#FFFF00", "#FF00FF", "#00FFFF"]
+    return [default_palette[i % len(default_palette)] for i in range(count)]
+
+
+def _check_if_colour_column_contains_hex_colors(colour_values: pd.Series) -> bool:
+    """Check if all values in a colour column are valid hex colors."""
+    try:
+        all(_is_hex_color(str(val)) for val in colour_values)
+        return True
+    except ValueError:
+        return False
+
+
+def _build_x_colour_to_y_value_map(
+    df: pd.DataFrame, x_column: str, colour_column: str, y_column: str
+) -> dict[tuple[str, str], float | None]:
+    """Build a mapping from (x_category, colour) to y_value."""
+    value_map = {}
+    for _, row in df.iterrows():
+        x_val = str(row[x_column])
+        colour_val = str(row[colour_column])
+        y_val = row[y_column]
+        value_map[(x_val, colour_val)] = float(y_val) if y_val is not None else None
+    return value_map
+
+
+def _extract_y_values_for_x_and_colour_categories(
+    x_categories: list[str],
+    colour_categories: list[str],
+    value_map: dict[tuple[str, str], float | None],
+) -> list[list[float | None]]:
+    """Extract y_values matrix from value map for given x and colour categories."""
+    y_values = []
+    for x_cat in x_categories:
+        row_values = [
+            value_map.get((x_cat, colour_cat)) for colour_cat in colour_categories
+        ]
+        y_values.append(row_values)
+    return y_values
+
+
+def _simplify_to_single_value_per_x_category(
+    y_values: list[list[float | None]],
+) -> list[list[float | None]]:
+    """Simplify y_values when each x-category has only one non-None value."""
+    has_single_value_per_x = all(
+        sum(1 for v in row if v is not None) == 1 for row in y_values
+    )
+    if has_single_value_per_x:
+        return [[next(v for v in row if v is not None)] for row in y_values]
+    return y_values
+
+
+def _get_y_value_for_x_category(
+    df: pd.DataFrame, x_column: str, x_category: str, y_column: str
+) -> float | None:
+    """Get the y value for a specific x category (assumes single match)."""
+    mask = df[x_column] == x_category
+    matching_rows = df[mask]
+    if len(matching_rows) > 0:
+        val = matching_rows[y_column].iloc[0]
+        return float(val) if val is not None else None
+    return None
+
+
+def _get_y_values_for_x_categories_with_colour_grouping(
+    df: pd.DataFrame,
+    x_column: str,
+    y_column: str,
+    colour_column: str,
+    x_categories: list[str],
+    colour_categories: list[str],
+) -> list[list[float | None]]:
+    """Get y_values matrix grouped by x and colour categories."""
+    y_values = []
+    for x_cat in x_categories:
+        row_values = []
+        for colour_cat in colour_categories:
+            mask = (df[x_column] == x_cat) & (df[colour_column] == colour_cat)
+            matching_rows = df[mask]
+            if len(matching_rows) > 0:
+                val = matching_rows[y_column].iloc[0]
+                row_values.append(float(val) if val is not None else None)
+            else:
+                row_values.append(None)
+        y_values.append(row_values)
+    return y_values
+
+
+@dataclass
+class _ChartConversionData:
+    """Intermediate data structure for chart conversion."""
+
+    x_label: str | None
+    x_categories: list[str] | None
+    y_label: str | None
+    y_values: list[list[float | None]]
+    colour_label: str | None
+    colour_categories: list[str]
+    colour_values: list[str]
+
+
+class _ChartBlockFactory(_BlockFactory, ABC):
+    """Base factory for chart blocks that process DataFrames."""
+
+    def _convert_default_format(
+        self,
+        df: pd.DataFrame,
+    ) -> _ChartConversionData:
+        """Convert DataFrame using default format: index as x, all columns as y series."""
+        x_categories = [str(idx) for idx in df.index]
+        y_columns = list(df.columns)
+        y_values = [
+            [
+                float(df.iloc[i][col]) if df.iloc[i][col] is not None else None
+                for col in y_columns
+            ]
+            for i in range(len(df))
+        ]
+        return _ChartConversionData(
+            x_label=None,
+            x_categories=x_categories,
+            y_label=None,
+            y_values=y_values,
+            colour_label=None,
+            colour_categories=y_columns,
+            colour_values=_get_default_colors(len(y_columns)),
+        )
+
+    def _convert_long_format(
+        self,
+        df: pd.DataFrame,
+        x_column: str,
+        y_column: str,
+        colour: str | Sequence[str] | None,
+    ) -> _ChartConversionData:
+        """Convert DataFrame in long format: x and y columns specified, optional colour grouping."""
+        x_categories = [str(val) for val in df[x_column].unique()]
+
+        if isinstance(colour, str):
+            colour_label = colour
+            unique_colour_values = df[colour].unique()
+
+            if _check_if_colour_column_contains_hex_colors(unique_colour_values):
+                colour_categories = [str(val) for val in unique_colour_values]
+                colour_values = colour_categories.copy()
+
+                value_map = _build_x_colour_to_y_value_map(
+                    df, x_column, colour, y_column
+                )
+                y_values = _extract_y_values_for_x_and_colour_categories(
+                    x_categories, colour_categories, value_map
+                )
+                y_values = _simplify_to_single_value_per_x_category(y_values)
+            else:
+                colour_categories = sorted([str(val) for val in unique_colour_values])
+                colour_values = _get_default_colors(len(colour_categories))
+                y_values = _get_y_values_for_x_categories_with_colour_grouping(
+                    df, x_column, y_column, colour, x_categories, colour_categories
+                )
+        else:
+            colour_label = None
+            colour_categories = [y_column]
+            colour_values = _get_default_colors(1)
+            y_values = [
+                [_get_y_value_for_x_category(df, x_column, x_cat, y_column)]
+                for x_cat in x_categories
+            ]
+
+        return _ChartConversionData(
+            x_label=x_column,
+            x_categories=x_categories,
+            y_label=y_column,
+            y_values=y_values,
+            colour_label=colour_label,
+            colour_categories=colour_categories,
+            colour_values=colour_values,
+        )
+
+    def _convert_wide_format(
+        self,
+        df: pd.DataFrame,
+        x_column: str | None,
+        y_columns: Sequence[str],
+        colour: str | Sequence[str] | None,
+    ) -> _ChartConversionData:
+        """Convert DataFrame in wide format: x column specified (or None), multiple y columns."""
+        if x_column is not None:
+            x_categories = [str(val) for val in df[x_column].unique()]
+            x_label = x_column
+        else:
+            # When x is None but y is specified, use index
+            x_categories = [str(idx) for idx in df.index]
+            x_label = None
+
+        if isinstance(colour, Sequence) and not isinstance(colour, str):
+            colour_values = list(colour)
+            colour_categories = list(y_columns)
+        else:
+            colour_values = _get_default_colors(len(y_columns))
+            colour_categories = list(y_columns)
+
+        y_values = []
+        if x_column is not None:
+            for x_cat in x_categories:
+                mask = df[x_column] == x_cat
+                matching_rows = df[mask]
+                if len(matching_rows) > 0:
+                    row = matching_rows.iloc[0]
+                    y_values.append(
+                        [
+                            float(row[col]) if row[col] is not None else None
+                            for col in y_columns
+                        ]
+                    )
+                else:
+                    y_values.append([None] * len(y_columns))
+        else:
+            # Use index for x
+            for i in range(len(df)):
+                row = df.iloc[i]
+                y_values.append(
+                    [
+                        float(row[col]) if row[col] is not None else None
+                        for col in y_columns
+                    ]
+                )
+
+        return _ChartConversionData(
+            x_label=x_label,
+            x_categories=x_categories,
+            y_label=None,
+            y_values=y_values,
+            colour_label=None,
+            colour_categories=colour_categories,
+            colour_values=colour_values,
+        )
+
+    @abstractmethod
+    def _create_chart_data_from_conversion(
+        self,
+        conversion_data: _ChartConversionData,
+        chart_specific_params: dict,
+    ) -> BarChartData | LineChartData:
+        """Convert intermediate data to specific chart data type. Override in subclasses."""
+
+
+__all__ = ["_ChartBlockFactory"]