agi-gui API

agi_gui provides the Streamlit-facing page helper package for AGILAB. It lives under src/agilab/lib/agi-gui so UI dependencies stay separate from the core runtime packages used by worker-only environments.

Use agi-gui when building or running AGILAB pages, apps-pages bundles, or local web UI sessions. Use agi-env directly for headless worker/runtime contexts that do not render Streamlit UI.

Reference

AGILAB Streamlit UI package.

class agi_gui.ActionSpec(label, key, kind=None, help=None, disabled=False, width=None, type=None, icon=None, on_click=None, args=None, kwargs=None)[source]

Bases: object

Declarative action metadata for normalized button rows and empty states.

__init__(label, key, kind=None, help=None, disabled=False, width=None, type=None, icon=None, on_click=None, args=None, kwargs=None)

args = None

disabled = False

help = None

icon = None

key

kind = None

kwargs = None

label

on_click = None

type = None

width = None

class agi_gui.ActionStyle(kind, button_type='secondary', width='stretch', status_state='info')[source]

Bases: object

Normalized Streamlit button defaults for a class of UI actions.

__init__(kind, button_type='secondary', width='stretch', status_state='info')

button_type = 'secondary'

kind

status_state = 'info'

width = 'stretch'

class agi_gui.FilePickerEntry(name, type, relative_path, path, size, modified)[source]

Bases: object

A file or directory row rendered by the file picker.

__init__(name, type, relative_path, path, size, modified)

as_row()[source]

Return type:: dict[str, str]

modified

name

path

relative_path

size

type

class agi_gui.FilePickerRoot(label, path)[source]

Bases: object

Named filesystem root exposed by the file picker.

__init__(label, path)

label

path

class agi_gui.WidgetRegistry(widgets=())[source]

Bases: object

Immutable registry for resolving AGILAB UI widgets by key or alias.

__init__(widgets=())[source]

as_rows()[source]

Return registry rows suitable for rendering as a table.

Return type:: list[dict[str, str]]

by_category(category)[source]

Return widgets matching category in deterministic display order.

Return type:: tuple[WidgetSpec, ...]

categories()[source]

Return known widget categories in deterministic display order.

Return type:: tuple[str, ...]

get(key_or_alias, default=None)[source]

Return a widget spec by key or alias, or default when absent.

Return type:: WidgetSpec | Any

keys()[source]

Return primary widget keys in deterministic display order.

Return type:: tuple[str, ...]

register(spec)[source]

Return a new registry with spec added.

Return type:: WidgetRegistry

require(key_or_alias)[source]

Return a widget spec by key or alias, raising a useful error when absent.

Return type:: WidgetSpec

property widgets: Return registered widgets in deterministic display order.

class agi_gui.WidgetSpec(key, label, widget, module, category, description='', aliases=(), tags=())[source]

Bases: object

Metadata for a reusable agi-gui widget.

__init__(key, label, widget, module, category, description='', aliases=(), tags=())

aliases

as_row()[source]

Return a compact row suitable for docs and diagnostics.

Return type:: dict[str, str]

category

description

key

label

module

property qualified_name: Return the import-style name of the registered widget callable.

tags

widget

agi_gui.action_button(streamlit, label, *, key, kind=None, help=None, disabled=False, width=None, type=None, icon=None, on_click=None, args=None, kwargs=None)[source]

Render a button using normalized AGILAB action defaults.

Return type:: bool

agi_gui.action_row(streamlit, actions, *, columns=None, gap='small')[source]

Render a normalized row of action buttons and return clicks keyed by action key.

Return type:: dict[str, bool]

agi_gui.action_style(kind=None)[source]

Return normalized button defaults for an AGILAB action kind.

Return type:: ActionStyle

agi_gui.agi_file_picker(label, *, roots, key, patterns=None, default=None, selection_mode='single', allow_files=True, allow_dirs=False, recursive=True, include_hidden=False, allow_upload=False, upload_dir=None, upload_types=None, max_entries=1000, help=None, container=None)[source]

Render a Streamlit popover file picker and return selected absolute paths.

Return type:: str | list[str] | None

agi_gui.compact_choice(streamlit, label, options, *, key=None, default=None, index=0, format_func=<class 'str'>, help=None, on_change=None, args=None, kwargs=None, label_visibility='visible', width='stretch', disabled=False, inline_limit=8, fallback='selectbox')[source]

Render a compact single-choice control with backwards-compatible fallbacks.

Return type:: Any

agi_gui.confirm_button(streamlit, label, *, key, message, confirm_label='Confirm', cancel_label='Cancel', help=None, type='secondary', confirm_type='primary', width='stretch', use_dialog=True)[source]

Render a button that requires explicit confirmation before returning True.

Return type:: bool

agi_gui.default_widget_registry()[source]

Return the default agi-gui widget registry.

Return type:: WidgetRegistry

agi_gui.empty_state(streamlit, title, *, body=None, state='info', icon=None, action=None)[source]

Render a normalized empty-state notice with an optional single action.

Return type:: bool

agi_gui.get_widget(key_or_alias)[source]

Return a registered widget callable by key or alias.

Return type:: Callable[..., Any]

agi_gui.is_path_under_root(path, root)[source]

Return whether path resolves inside root.

Return type:: bool

agi_gui.list_file_picker_entries(root, *, patterns=None, allow_files=True, allow_dirs=False, recursive=True, include_hidden=False, max_entries=1000)[source]

List picker entries below root in deterministic display order.

Return type:: list[FilePickerEntry]

agi_gui.normalize_action_kind(kind)[source]

Return the canonical AGILAB action kind for button styling.

Return type:: str

agi_gui.normalize_file_patterns(patterns)[source]

Normalize file patterns to non-empty glob-style strings.

Return type:: tuple[str, ...]

agi_gui.normalize_file_picker_roots(roots)[source]

Normalize a root mapping or path sequence into deterministic picker roots.

Return type:: tuple[FilePickerRoot, ...]

agi_gui.normalize_message_state(state)[source]

Return the canonical message state used by notices and toast fallbacks.

Return type:: str

agi_gui.normalize_status_state(state)[source]

Return a Streamlit-compatible status state.

Return type:: str

agi_gui.notice(streamlit, message, *, state='info', icon=None)[source]

Show a normalized inline message with compatibility for legacy Streamlit.

Return type:: None

agi_gui.resolve_under_roots(path, roots, *, must_exist=True)[source]

Resolve path and require it to stay inside one of roots.

Return type:: Path

agi_gui.safe_upload_target(upload_dir, uploaded_name, roots)[source]

Return a safe upload destination below upload_dir and configured roots.

Return type:: Path

agi_gui.selected_paths_from_dataframe_state(state, rows)[source]

Extract selected absolute paths from a Streamlit dataframe selection state.

Return type:: list[str]

agi_gui.status_container(streamlit, label, *, state='running', expanded=True)[source]

Return a status context using st.status when available.

Return type:: AbstractContextManager

agi_gui.toast(streamlit, message, *, icon=None, state='info')[source]

Show a toast when supported, otherwise fall back to a regular message.

Return type:: None

agi_gui.widget_registry_rows()[source]

Return default registry rows for diagnostics or documentation.

Return type:: list[dict[str, str]]