yera.dsl.functions

Prompting, input, output, layout, and lifecycle functions.

The building blocks an app function uses to interact with the LLM, present output, and collect input from the user.

Prompting

  • chat: send a prompt and get a text response
  • sys_prompt: append a line to the active system prompt

Input widgets

Output blocks

  • markdown: render markdown content
  • table: render tabular data
  • action: mark a unit of work in progress
  • spinner: show a spinner while work runs

Layout

  • columns: lay blocks out in side-by-side columns
  • container: group blocks into a single visual unit
  • form: group input blocks and submit them together

Lifecycle

  • exit: end the app run
  • quit: end the app run as a user-initiated quit

Symbols

def action — Mark a unit of app work in progress.
def bar_chart — Render a bar chart.
def buttons — Present the user with a set of buttons and return their selection.
def chat — Yield user prompts until one starts with ``stop_str``.
def columns — Lay child blocks out in ``n`` side-by-side columns.
def container — Group child blocks into a single container.
def date_picker — Present the user with a date picker.
def exit — End the current app run.
def form — Group input blocks into a form, submitted together.
def line_chart — Render a line chart.
def markdown — Render a markdown block.
def quit — End the current app run as a user-initiated quit.
def response — Send a prompt to the active LLM and return its text response.
def slider — Present the user with a slider over a numeric range.
def spinner — Show a spinner with a message while a block of work runs.
def sys_prompt — Append a line to the active LLM context's system prompt.
def table — Render a table.
def text_input — Prompt the user for free-form text input.

action

action(
    message: str,
) → ActionStream

Mark a unit of app work in progress.

Use as a context manager: the action is shown as active while the block runs and marked complete on exit. The update method on the returned stream can change the message mid-flight.

Parameters

message
type: str

Initial description of the work in progress.

Returns

type: ActionStream

An ActionStream context manager.

bar_chart

bar_chart(
    data: object,
    x: str | None = None,
    y: str | Sequence[str] | None = None,
    colour: str | Sequence[str] | None = None,
    horizontal: bool = False,
    stack: bool = True,
) → None

Render a bar chart.

Parameters

data
type: object

Chart data; typically a pandas DataFrame.

x
type: str | None = None

Column name to use for the x-axis.

y
type: str | Sequence[str] | None = None

Column name (or names) to plot on the y-axis.

colour
type: str | Sequence[str] | None = None

Column name (or names) used to colour the bars.

horizontal
type: bool = False

Orient bars horizontally rather than vertically.

stack
type: bool = True

Stack multiple series rather than grouping side-by-side.

buttons

buttons(
    options: list[str],
    label: str | None = None,
) → str

Present the user with a set of buttons and return their selection.

Parameters

options
type: list[str]

Labels for the buttons to display.

label
type: str | None = None

Optional prompt shown above the buttons.

Returns

type: str

The label of the button the user clicked.

chat

chat(
    stop_str: str = '/quit',
) → Generator[str]

Yield user prompts until one starts with stop_str.

Repeatedly prompts the user for text input, yielding each prompt. When the user submits a prompt starting with stop_str, the run quits and iteration stops.

Parameters

stop_str
type: str = '/quit'

Prefix that, when matched, ends the chat loop. Default = "/quit"

columns

columns(
    n: int,
    border: bool = False,
) → LayoutHandle

Lay child blocks out in n side-by-side columns.

Use as a context manager. Blocks emitted inside the with body are distributed across the columns in order.

Parameters

n
type: int

Number of columns.

border
type: bool = False

Whether to draw a border around the layout.

Returns

type: LayoutHandle

A LayoutHandle context manager.

container

container(
    border: bool = False,
) → LayoutHandle

Group child blocks into a single container.

Use as a context manager. Blocks emitted inside the with body are grouped together as a visual unit.

Parameters

border
type: bool = False

Whether to draw a border around the container.

Returns

type: LayoutHandle

A LayoutHandle context manager.

date_picker

date_picker(
    label: str,
    default_date: date | str | None = None,
) → date

Present the user with a date picker.

Parameters

label
type: str

Prompt shown alongside the picker.

default_date
type: date | str | None = None

Optional initial date, as a date or ISO-format string.

Returns

type: date

The date the user chose.

exit

exit(
    exit_code: int,
    reason: str,
    return_value: object,
    error_cause: ErrorCause | None = None,
) → None

End the current app run.

Parameters

exit_code
type: int

Process-style exit code; 0 for success, non-zero for failure.

reason
type: str

Human-readable summary of why the run ended.

return_value
type: object

Value to return to the caller, or None.

error_cause
type: ErrorCause | None = None

Optional structured cause metadata for failure exits. See ErrorCause.

form

form(
    border: bool = False,
) → LayoutHandle

Group input blocks into a form, submitted together.

Use as a context manager. Input blocks (text_input, buttons, date_picker, slider) emitted inside the with body are presented together and submitted as a single batch when the user completes the form.

Parameters

border
type: bool = False

Whether to draw a border around the form.

Returns

type: LayoutHandle

A LayoutHandle context manager.

line_chart

line_chart(
    data: object,
    x: str | None = None,
    y: str | Sequence[str] | None = None,
    colour: str | Sequence[str] | None = None,
) → None

Render a line chart.

Parameters

data
type: object

Chart data; typically a pandas DataFrame.

x
type: str | None = None

Column name to use for the x-axis.

y
type: str | Sequence[str] | None = None

Column name (or names) to plot on the y-axis.

colour
type: str | Sequence[str] | None = None

Column name (or names) used to colour the lines.

markdown

markdown(
    content: str | None = None,
) → MarkdownStream

Render a markdown block.

Can be called directly to emit a single block, or used as a stream handle to append further chunks over time.

Parameters

content
type: str | None = None

If provided, immediately emits this markdown content.

Returns

type: MarkdownStream

A MarkdownStream handle whose append and new_line methods add further chunks to the same block.

quit

quit() → None

End the current app run as a user-initiated quit.

Distinct from exit: signals that the user chose to stop rather than the app completing or failing.

response

response(
    prompt: str,
    **kwargs,
) → str

Send a prompt to the active LLM and return its text response.

Tokens will simultaneously be pushed onto the event stream for display in your UI or printed to stdout.

Parameters

prompt
type: str

The user-message prompt to send.

**kwargs
type: str | int | float | bool

Additional options forwarded to the underlying LLM (e.g. provider-specific generation parameters).

Returns

type: str

The LLM's text response.

slider

slider(
    min_value: float,
    max_value: float,
    label: str,
    default_value: float | None = None,
) → float

Present the user with a slider over a numeric range.

Parameters

min_value
type: float

Lower bound of the slider.

max_value
type: float

Upper bound of the slider.

label
type: str

Prompt shown alongside the slider.

default_value
type: float | None = None

Optional initial position. Defaults to min_value if not provided.

Returns

type: float

The value the user selected.

spinner

spinner(
    message: str,
) → SpinnerStream

Show a spinner with a message while a block of work runs.

Use as a context manager: the spinner shows while the block runs and is removed on exit. The update method on the returned stream can change the message mid-flight.

Parameters

message
type: str

Initial message shown alongside the spinner.

Returns

type: SpinnerStream

A SpinnerStream context manager.

sys_prompt

sys_prompt(
    prompt: str,
) → None

Append a line to the active LLM context's system prompt.

Parameters

prompt
type: str

Text to add to the system prompt for subsequent chat and struct calls in the current LLM context.

table

table(
    data: object = None,
    border: bool | Literal['horizontal'] = True,
) → TableStream

Render a table.

Parameters

data
type: object = None

Table data. Accepts pandas DataFrames, dicts of column lists, lists of dicts, lists of lists, or any iterable that can be converted to rows. Pass None for an empty table.

border
type: bool | Literal['horizontal'] = True

True for full borders, False for none, or "horizontal" for horizontal lines only.

Returns

type: TableStream

A TableStream handle whose add_rows method appends rows to the same table.

text_input

text_input(
    message: str | None = None,
) → str

Prompt the user for free-form text input.

Parameters

message
type: str | None = None

Optional label shown alongside the input field.

Returns

type: str

The text the user submitted.