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

yera/events/blocks/base/layout.py

@@ -0,0 +1,111 @@
+"""Shared layout block implementation."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from typing import Any
+
+from yera.events.blocks.base.base import (
+    _StreamHandle,
+    create_event,
+    get_parent_block_id,
+)
+from yera.events.models import (
+    ColumnsData,
+    ContainerData,
+    LayoutEndData,
+)
+from yera.events.stream import await_input, push_output
+
+
+@dataclass
+class LayoutContext:
+    """Context for tracking active layout blocks."""
+
+    block_id: str
+    block_type: str  # "container", "columns", or "form"
+    column_index: int = 0  # For columns, tracks current column index
+    input_count: int = (
+        0  # Number of await_user blocks emitted in this layout; drained on exit
+    )
+    result_parsers: list[Callable[[str], Any]] = field(default_factory=list)
+
+
+# Context variable to track the current layout
+_current_layout: ContextVar[LayoutContext | None] = ContextVar(
+    "current_layout", default=None
+)
+
+
+class LayoutHandle(_StreamHandle):
+    """Stream handle for layout blocks (container, columns)."""
+
+    def __init__(
+        self,
+        block_id: str,
+        block_type: str,
+        data: ContainerData | ColumnsData,
+    ):
+        super().__init__(block_id, block_type)
+        self.data = data
+        self._token: Token[LayoutContext | None] | None = None
+
+    def __enter__(self):
+        # Get parent block ID before setting new layout context
+        parent_block_id = get_parent_block_id()
+
+        # Create layout context (keep reference so __exit__ can drain input_count)
+        layout_context = LayoutContext(
+            block_id=self.block_id, block_type=self.block_type
+        )
+        self._layout_context = layout_context
+        self._token = _current_layout.set(layout_context)
+
+        # Emit layout event with pre-built data from factory
+        event = self._create_chunk_event(
+            data=self.data,
+            message_type="layout",
+            parent_block_id=parent_block_id,
+        )
+        push_output(event)
+
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        # Clear layout context
+        if self._token is not None:
+            _current_layout.reset(self._token)
+        # Emit layout_end so the stream can pause after all layout children have been sent
+        layout_end_event = create_event(
+            block_type="layout_end",
+            block_id=self.block_id,
+            data=LayoutEndData(),
+            message_type="informational",
+            chunk_id=1,
+        )
+        push_output(layout_end_event)
+        # For container/columns, drain inputs so the agent does not block. Form drains in result().
+        if self.block_type != "form":
+            for _ in range(self._layout_context.input_count):
+                await_input()
+        return False
+
+    def result(self) -> tuple[Any, ...]:
+        """Return parsed form values. Only supported for form blocks."""
+        if self.block_type != "form":
+            raise TypeError("result() is only supported for form blocks")
+        n = self._layout_context.input_count
+        parsers = self._layout_context.result_parsers
+        out: list[Any] = []
+        for i in range(n):
+            ev = await_input()
+            if i < len(parsers):
+                out.append(parsers[i](ev.data))
+            else:
+                out.append(ev.data)
+        return tuple(out)
+
+
+__all__ = ["LayoutContext", "LayoutHandle", "_current_layout"]

yera/events/blocks/buttons.py

@@ -0,0 +1,37 @@
+"""Buttons block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import _BlockFactory
+from yera.events.models import ButtonsData
+from yera.events.stream import push_output
+
+
+class _ButtonsBlockFactory(_BlockFactory):
+    """Factory for creating button blocks."""
+
+    def __init__(self):
+        super().__init__("buttons")
+
+    def __call__(
+        self,
+        options: list[str],
+        label: str | None = None,
+    ):
+        event = self._create_block_output_event(
+            data=ButtonsData(options=options, label=label),
+            message_type="await_user",
+        )
+        push_output(event)
+
+
+# Create a single shared factory instance
+_buttons_factory = _ButtonsBlockFactory()
+
+
+def request_input_buttons(options: list[str], label: str | None = None):
+    """Request buttons input from the user."""
+    return _buttons_factory(options, label)
+
+
+__all__ = ["request_input_buttons"]

yera/events/blocks/columns.py

@@ -0,0 +1,26 @@
+"""Columns block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import LayoutHandle, _BlockFactory
+from yera.events.models import ColumnsData
+
+
+class _ColumnsBlockFactory(_BlockFactory):
+    """Factory for columns blocks."""
+
+    def __init__(self):
+        super().__init__("columns")
+
+    def __call__(self, n: int, border: bool = False) -> LayoutHandle:
+        """Return a context manager for creating column layouts with n columns."""
+        block_id = self._generate_block_id()
+        return LayoutHandle(
+            block_id, "columns", ColumnsData(showBorder=border, column_count=n)
+        )
+
+
+# Create the columns callable/context manager
+columns = _ColumnsBlockFactory()
+
+__all__ = ["columns"]

yera/events/blocks/container.py

@@ -0,0 +1,24 @@
+"""Container block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import LayoutHandle, _BlockFactory
+from yera.events.models import ContainerData
+
+
+class _ContainerBlockFactory(_BlockFactory):
+    """Factory for container blocks."""
+
+    def __init__(self):
+        super().__init__("container")
+
+    def __call__(self, border: bool = False) -> LayoutHandle:
+        """Return a context manager for creating container layouts."""
+        block_id = self._generate_block_id()
+        return LayoutHandle(block_id, "container", ContainerData(showBorder=border))
+
+
+# Create the container callable/context manager
+container = _ContainerBlockFactory()
+
+__all__ = ["container"]

yera/events/blocks/date_picker.py

@@ -0,0 +1,50 @@
+"""Date picker block implementation."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from yera.events.blocks.base import _BlockFactory
+from yera.events.models import DatePickerData
+from yera.events.stream import push_output
+
+
+class _DatePickerBlockFactory(_BlockFactory):
+    """Factory for creating date picker blocks."""
+
+    def __init__(self):
+        super().__init__("date")
+
+    def __call__(
+        self,
+        label: str,
+        default_date: date | str | None = None,
+    ):
+        """Create a date picker block."""
+        # Default to today's date if not provided
+        if default_date is None:
+            default_date = date.today()
+        elif isinstance(default_date, str):
+            # Parse string to date if provided as string
+            default_date = date.fromisoformat(default_date)
+
+        data = DatePickerData(value=default_date, label=label)
+
+        # Use shared method with await_user message_type
+        event = self._create_block_output_event(data, message_type="await_user")
+        push_output(event)
+
+
+# Create a single shared factory instance
+_date_picker_factory = _DatePickerBlockFactory()
+
+
+def request_input_date_picker(
+    label: str,
+    default_date: date | str | None = None,
+):
+    """Request date picker input from the user."""
+    return _date_picker_factory(label, default_date)
+
+
+__all__ = ["request_input_date_picker"]

yera/events/blocks/exit.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from yera.events.blocks.base import _BlockFactory
+from yera.events.models import ExitEventData
+from yera.events.stream import push_output
+
+
+class _ExitBlockFactory(_BlockFactory):
+    def __init__(self):
+        super().__init__("exit")
+
+    def __call__(self, exit_code: int, reason: str | None, return_value: str | None):
+        return_type = type(return_value).__name__
+
+        if isinstance(return_value, BaseModel):
+            return_value = return_value.model_dump_json()
+
+        event = self._create_block_output_event(
+            data=ExitEventData(
+                exit_code=exit_code,
+                reason=reason,
+                return_type=return_type,
+                return_value=str(return_value),
+            ),
+            message_type="informational",
+        )
+        push_output(event)
+
+
+exit_event = _ExitBlockFactory()
+
+
+def quit_event():
+    exit_event(exit_code=0, reason="User quit", return_value=None)
+
+
+__all__ = ["exit_event", "quit_event"]

yera/events/blocks/form.py

@@ -0,0 +1,24 @@
+"""Form block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import LayoutHandle, _BlockFactory
+from yera.events.models import ContainerData
+
+
+class _FormBlockFactory(_BlockFactory):
+    """Factory for form blocks (layout with await_user children and submit)."""
+
+    def __init__(self):
+        super().__init__("form")
+
+    def __call__(self, border: bool = False) -> LayoutHandle:
+        """Return a context manager for creating form layouts."""
+        block_id = self._generate_block_id()
+        return LayoutHandle(block_id, "form", ContainerData(showBorder=border))
+
+
+# Create the form callable/context manager
+form = _FormBlockFactory()
+
+__all__ = ["form"]

yera/events/blocks/input_echo.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from yera.events.blocks.base import _BlockFactory
+from yera.events.models import MarkdownData
+from yera.events.stream import push_output
+
+
+class _InputEchoBlockFactory(_BlockFactory):
+    def __init__(self):
+        super().__init__("input_echo")
+
+    def __call__(self, content):
+        event = self._create_block_output_event(
+            data=MarkdownData(content=content),
+            message_type="informational",
+        )
+        push_output(event)
+
+
+input_echo = _InputEchoBlockFactory()
+
+__all__ = ["input_echo"]

yera/events/blocks/input_request.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from yera.events.blocks.base import _BlockFactory
+from yera.events.models import InputRequestData
+from yera.events.stream import push_output
+
+
+class _InputRequestBlockFactory(_BlockFactory):
+    def __init__(self):
+        super().__init__("input_request")
+
+    def __call__(self, message: str | None, input_type: Literal["text"]):
+        event = self._create_block_output_event(
+            data=InputRequestData(message=message, type=input_type),
+            message_type="await_user",
+        )
+        push_output(event)
+
+
+# Create a single shared factory instance
+_input_request_factory = _InputRequestBlockFactory()
+
+
+def request_input_text(message: str | None = None):
+    """Request text input from the user."""
+    return _input_request_factory(message or "", "text")
+
+
+__all__ = ["request_input_text"]

yera/events/blocks/line_chart.py

@@ -0,0 +1,97 @@
+"""Line 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 LineChartData
+from yera.events.stream import push_output
+
+
+class _LineChartBlockFactory(_ChartBlockFactory):
+    """Factory for creating line chart blocks, matching Streamlit's st.line_chart API."""
+
+    def __init__(self):
+        super().__init__("line_chart")
+
+    def _create_chart_data_from_conversion(
+        self,
+        conversion_data: _ChartConversionData,
+        chart_specific_params: dict,
+    ) -> LineChartData:
+        """Convert intermediate data to LineChartData."""
+        if len(chart_specific_params) > 0:
+            raise ValueError("Line charts don't have specific parameters")
+
+        # LineChartData omits x_ticks and x_label when x parameter was not provided
+        x_ticks = (
+            conversion_data.x_categories
+            if conversion_data.x_label is not None
+            else None
+        )
+        x_label = conversion_data.x_label
+
+        return LineChartData(
+            x_label=x_label,
+            x_ticks=x_ticks,
+            y_label=conversion_data.y_label,
+            y_values=conversion_data.y_values,
+            colour_label=conversion_data.colour_label,
+            colour_series=conversion_data.colour_categories,
+            colour_values=conversion_data.colour_values,
+        )
+
+    def __call__(
+        self,
+        data: pd.DataFrame,
+        *,
+        x: str | None = None,
+        y: str | Sequence[str] | None = None,
+        colour: str | Sequence[str] | None = None,
+    ) -> None:
+        """Create a line chart block, matching Streamlit's st.line_chart() signature.
+
+        Args:
+            data: DataFrame to plot
+            x: Column name for x-axis (None = use index, or omit x_ticks if y is specified)
+            y: Column name(s) for y-axis (None = use all columns)
+            colour: Column name for colour grouping, or list of colors
+
+        Returns:
+            None (informational block)
+
+        """
+        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 isinstance(y, Sequence) and not isinstance(y, str):
+            # Wide format: y is a sequence, x may be None or a string
+            conversion_data = self._convert_wide_format(data, x, y, colour)
+        else:
+            raise ValueError(
+                f"Unsupported line_chart parameter combination: x={x}, y={y}"
+            )
+
+        chart_data = self._create_chart_data_from_conversion(
+            conversion_data,
+            {},  # Line charts don't have chart-specific params
+        )
+
+        event = self._create_block_output_event(
+            chart_data, message_type="informational"
+        )
+        push_output(event)
+        return
+
+
+# Create the line_chart callable
+line_chart = _LineChartBlockFactory()
+
+__all__ = ["line_chart"]

yera/events/blocks/markdown.py

@@ -0,0 +1,67 @@
+"""Markdown block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import _BlockFactory, _StreamHandle
+from yera.events.models import MarkdownData
+from yera.events.stream import push_output
+
+
+class MarkdownStream(_StreamHandle):
+    """Stream handle for creating multiple chunks of the same markdown block."""
+
+    def __init__(self, block_id: str):
+        super().__init__(block_id, "markdown")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        return False
+
+    def append(self, content: str) -> None:
+        """Append a new chunk to this markdown block."""
+        event = self._create_chunk_event(
+            data=MarkdownData(content=content),
+        )
+        push_output(event)
+
+    def new_line(self, content: str) -> None:
+        """Append a new line to this markdown block."""
+        new_line_content = "\n\n" + content
+        self.append(new_line_content)
+
+
+class _MarkdownBlockFactory(_BlockFactory):
+    """Factory for markdown blocks."""
+
+    def __init__(self):
+        super().__init__("markdown")
+
+    def __call__(self, content: str | None = None) -> MarkdownStream:
+        """Create a markdown block or return a stream for context manager usage.
+
+        Args:
+            content: If provided, immediately emits a single markdown chunk.
+
+        Returns:
+            A MarkdownStream that can be used as a context manager for streaming
+            additional chunks.
+
+        """
+        block_id = self._generate_block_id()
+
+        stream = MarkdownStream(block_id)
+
+        if content is not None:
+            # Direct call or initial content for a stream: emit first chunk immediately
+            stream.append(content)
+
+        # Always return the stream, even if used only for a single chunk
+        return stream
+
+
+# Create the markdown callable/context manager
+markdown = _MarkdownBlockFactory()
+
+__all__ = ["markdown"]

yera/events/blocks/slider.py

@@ -0,0 +1,54 @@
+"""Slider block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import _BlockFactory
+from yera.events.models import SliderData
+from yera.events.stream import push_output
+
+
+class _SliderBlockFactory(_BlockFactory):
+    """Factory for creating slider blocks."""
+
+    def __init__(self):
+        super().__init__("slider")
+
+    def __call__(
+        self,
+        min_value: float,
+        max_value: float,
+        label: str,
+        default_value: float | None = None,
+    ):
+        """Create a slider block."""
+        # Default to midpoint if not provided
+        if default_value is None:
+            default_value = (min_value + max_value) / 2
+
+        data = SliderData(
+            min_value=min_value,
+            max_value=max_value,
+            initial_value=default_value,
+            label=label,
+        )
+
+        # Use shared method with await_user message_type
+        event = self._create_block_output_event(data, message_type="await_user")
+        push_output(event)
+
+
+# Create a single shared factory instance
+_slider_factory = _SliderBlockFactory()
+
+
+def request_input_slider(
+    min_value: float,
+    max_value: float,
+    label: str,
+    default_value: float | None = None,
+):
+    """Request slider input from the user."""
+    return _slider_factory(min_value, max_value, label, default_value)
+
+
+__all__ = ["request_input_slider"]

yera/events/blocks/spinner.py

@@ -0,0 +1,55 @@
+"""Spinner block implementation."""
+
+from __future__ import annotations
+
+from yera.events.blocks.base import _BlockFactory, _StreamHandle
+from yera.events.models import SpinnerData
+from yera.events.stream import push_output
+
+
+class SpinnerStream(_StreamHandle):
+    """Stream handle for creating multiple chunks of the same spinner block."""
+
+    def __init__(self, block_id: str, initial_message: str):
+        super().__init__(block_id, "spinner")
+        self.initial_message = initial_message
+
+    def __enter__(self):
+        event = self._create_chunk_event(
+            data=SpinnerData(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=SpinnerData(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=SpinnerData(status="active", message=message),
+        )
+        push_output(event)
+
+
+class _SpinnerBlockFactory(_BlockFactory):
+    """Factory for spinner blocks. Returns a context manager when called with message."""
+
+    def __init__(self):
+        super().__init__("spinner")
+
+    def __call__(self, message: str) -> SpinnerStream:
+        """Return a context manager for creating multiple spinner chunks."""
+        block_id = self._generate_block_id()
+        return SpinnerStream(block_id, message)
+
+
+# Create the spinner callable/context manager
+spinner = _SpinnerBlockFactory()
+
+
+__all__ = ["spinner"]

yera/events/blocks/system_prompt.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from yera.events.blocks.base import _BlockFactory
+from yera.events.models import MarkdownData
+from yera.events.stream import push_output
+
+
+class _SystemPromptBlockFactory(_BlockFactory):
+    def __init__(self):
+        super().__init__("system_prompt")
+
+    def __call__(self, content):
+        event = self._create_block_output_event(
+            data=MarkdownData(content=content),
+            message_type="informational",
+        )
+        push_output(event)
+
+
+system_prompt = _SystemPromptBlockFactory()
+
+__all__ = ["system_prompt"]