Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

16.9 KB
Raw Blame
"""Arrow-key interactive pickers for CLI prompts."""

from __future__ import annotations

from contextlib import suppress
import shutil
import sys
from typing import overload

import click


# CrewAI brand: primary=#FF5A50 (coral), teal=#1F7982
_CORAL = "\033[38;2;255;90;80m"  # #FF5A50
_TEAL = "\033[38;2;31;121;130m"  # #1F7982
_BOLD = "\033[1m"
_DIM = "\033[2m"
_GREEN = "\033[1;32m"
_RESET = "\033[0m"
_HIDE_CURSOR = "\033[?25l"
_SHOW_CURSOR = "\033[?25h"


def _is_interactive() -> bool:
    try:
        return sys.stdin.isatty() and sys.stdout.isatty()
    except Exception:
        return False


def _read_key() -> str:
    if sys.platform == "win32":
        import msvcrt

        ch = msvcrt.getwch()
        if ch in ("\x00", "\xe0"):
            ch2 = msvcrt.getwch()
            return {"H": "up", "P": "down"}.get(ch2, "")
        if ch == "\r":
            return "enter"
        if ch == " ":
            return "space"
        if ch == "\x03":
            raise KeyboardInterrupt
        return ch

    import termios
    import tty

    fd = sys.stdin.fileno()
    old = termios.tcgetattr(fd)
    try:
        tty.setcbreak(fd)
        ch = sys.stdin.read(1)
        if ch == "\x1b":
            seq = sys.stdin.read(2)
            if seq == "[A":
                return "up"
            if seq == "[B":
                return "down"
            return "esc"
        if ch in ("\r", "\n"):
            return "enter"
        if ch == " ":
            return "space"
        if ch == "\x03":
            raise KeyboardInterrupt
        return ch
    finally:
        termios.tcsetattr(fd, termios.TCSADRAIN, old)


def _clear_lines(n: int) -> None:
    sys.stdout.write(f"\033[{n}A")
    for _ in range(n):
        sys.stdout.write("\033[2K\n")
    sys.stdout.write(f"\033[{n}A")
    sys.stdout.flush()


def _draw_single(labels: list[str], cursor: int, *, clear: bool = False) -> None:
    total = len(labels)
    if clear:
        sys.stdout.write(f"\033[{total}A")
    for i, label in enumerate(labels):
        if i == cursor:
            sys.stdout.write(f"\033[2K  {_CORAL}→{_RESET} {_BOLD}{label}{_RESET}\n")
        else:
            sys.stdout.write(f"\033[2K    {label}\n")
    sys.stdout.flush()


def _draw_multi(
    labels: list[str],
    cursor: int,
    selected: set[int],
    *,
    action_indices: set[int] | None = None,
    separator_indices: set[int] | None = None,
    clear: bool = False,
    previous_line_count: int | None = None,
    row_indices: list[int] | None = None,
    query: str = "",
    searchable: bool = False,
) -> int:
    action_indices = action_indices or set()
    separator_indices = separator_indices or set()
    rows = row_indices if row_indices is not None else list(range(len(labels)))
    try:
        cursor_pos = rows.index(cursor)
    except ValueError:
        cursor_pos = 0
    start, end = _visible_row_range(len(rows), cursor_pos)
    hint_text = "↑↓ navigate, space toggle, enter confirm"
    if action_indices:
        hint_text = "↑↓ navigate, space toggle, enter confirm, ▸ rows expand/collapse"
    if searchable:
        hint_text += " · type to filter"
    if end - start < len(rows):
        hint_text += f" · showing {start + 1}-{end} of {len(rows)}"
    hint = f"  {_DIM}{hint_text}{_RESET}"
    if clear:
        # Erase the previous block first. A shorter search result would
        # otherwise leave the old rows visible underneath the matches.
        _clear_lines(previous_line_count or 1)
    extra_lines = 0
    sys.stdout.write(f"\033[2K{hint}\n")
    if searchable:
        match_count = ""
        if query:
            count = len(rows)
            noun = "match" if count == 1 else "matches"
            match_count = f"  ·  {count} {noun}"
        sys.stdout.write(f"\033[2K  {_GREEN}Search: {query}{match_count}{_RESET}\n")
        extra_lines += 1
    if searchable and query and not rows:
        sys.stdout.write(f"\033[2K    {_DIM}No matching actions{_RESET}\n")
        extra_lines += 1
    for pos in range(start, end):
        i = rows[pos]
        label = labels[i]
        if i in separator_indices:
            sys.stdout.write(f"\033[2K      {_TEAL}{label}{_RESET}\n")
            continue
        if i in action_indices:
            check = "  "
        elif i in selected:
            check = f"{_CORAL}[x]{_RESET}"
        else:
            check = "[ ]"
        arrow = f"{_CORAL}→{_RESET} " if i == cursor else "  "
        bold = f"{_BOLD}{label}{_RESET}" if i == cursor else label
        sys.stdout.write(f"\033[2K    {arrow}{check} {bold}\n")
    sys.stdout.flush()
    return end - start + 1 + extra_lines


def _visible_row_range(total: int, cursor: int) -> tuple[int, int]:
    """Return the portion of a multi-select list that fits in the terminal."""
    max_rows = max(5, shutil.get_terminal_size(fallback=(80, 24)).lines - 5)
    if total <= max_rows:
        return 0, total

    start = min(max(cursor - max_rows // 2, 0), total - max_rows)
    return start, start + max_rows


def _arrow_select_one(labels: list[str]) -> int:
    cursor = 0
    total = len(labels)
    sys.stdout.write(_HIDE_CURSOR)
    sys.stdout.flush()
    try:
        _draw_single(labels, cursor)
        while True:
            key = _read_key()
            if key == "up" and cursor > 0:
                cursor -= 1
                _draw_single(labels, cursor, clear=True)
            elif key == "down" and cursor < total - 1:
                cursor += 1
                _draw_single(labels, cursor, clear=True)
            elif key == "enter":
                _clear_lines(total)
                return cursor
            elif key in ("esc", "q"):
                _clear_lines(total)
                return -1
    finally:
        sys.stdout.write(_SHOW_CURSOR)
        sys.stdout.flush()


def _is_search_character(key: str) -> bool:
    return len(key) == 1 and key.isprintable() and key != " "


def _visible_label_indices(
    labels: list[str],
    query: str,
    separator_indices: set[int],
    *,
    searchable: bool,
) -> list[int]:
    if not searchable or not query:
        return list(range(len(labels)))
    return [
        index
        for index in matching_label_indices(labels, query)
        if index not in separator_indices
    ]


def _cursor_on_visible(
    cursor: int,
    labels: list[str],
    query: str,
    separator_indices: set[int],
    searchable: bool,
) -> int:
    visible = _visible_label_indices(
        labels, query, separator_indices, searchable=searchable
    )
    if cursor in visible or not visible:
        return cursor
    return visible[0]


def _move_visible_cursor(
    cursor: int,
    direction: int,
    labels: list[str],
    query: str,
    separator_indices: set[int],
    searchable: bool,
) -> int:
    visible = [
        index
        for index in _visible_label_indices(
            labels, query, separator_indices, searchable=searchable
        )
        if index not in separator_indices
    ]
    if cursor not in visible:
        return visible[0] if visible else cursor
    position = visible.index(cursor) + direction
    if 0 <= position < len(visible):
        return visible[position]
    return cursor


def _arrow_select_multi(
    labels: list[str],
    *,
    action_indices: set[int] | None = None,
    separator_indices: set[int] | None = None,
    preselected: set[int] | None = None,
    initial_cursor: int | None = None,
    searchable: bool = False,
) -> tuple[list[int], int | None]:
    total = len(labels)
    selected: set[int] = set(preselected or ())
    action_indices = action_indices or set()
    separator_indices = separator_indices or set()
    query = ""
    if initial_cursor is not None and 0 <= initial_cursor < total:
        cursor = initial_cursor
    else:
        cursor = _first_selectable_index(total, separator_indices)
    sys.stdout.write(_HIDE_CURSOR)
    sys.stdout.flush()

    def redraw(clear: bool) -> int:
        return _draw_multi(
            labels,
            cursor,
            selected,
            action_indices=action_indices,
            separator_indices=separator_indices,
            clear=clear,
            previous_line_count=rendered_lines if clear else None,
            row_indices=_visible_label_indices(
                labels, query, separator_indices, searchable=searchable
            ),
            query=query,
            searchable=searchable,
        )

    try:
        rendered_lines = redraw(False)
        while True:
            key = _read_key()
            if key == "up":
                cursor = _move_visible_cursor(
                    cursor, -1, labels, query, separator_indices, searchable
                )
            elif key == "down":
                cursor = _move_visible_cursor(
                    cursor, 1, labels, query, separator_indices, searchable
                )
            elif key == "space":
                if cursor in action_indices:
                    _clear_lines(rendered_lines)
                    return sorted(selected), cursor
                if cursor in _visible_label_indices(
                    labels, query, separator_indices, searchable=searchable
                ):
                    selected ^= {cursor}
            elif key == "enter":
                _clear_lines(rendered_lines)
                if cursor in action_indices:
                    return sorted(selected), cursor
                return sorted(selected), None
            elif searchable and key in ("\x7f", "\b") and query:
                query = query[:-1]
                cursor = _cursor_on_visible(
                    cursor, labels, query, separator_indices, searchable
                )
            elif searchable and key == "esc" and query:
                query = ""
                cursor = _cursor_on_visible(
                    cursor, labels, query, separator_indices, searchable
                )
            elif searchable and _is_search_character(key):
                query += key
                cursor = _cursor_on_visible(
                    cursor, labels, query, separator_indices, searchable
                )
            elif key in ("esc", "q"):
                _clear_lines(rendered_lines)
                return sorted(selected), None
            else:
                continue
            rendered_lines = redraw(True)
    finally:
        sys.stdout.write(_SHOW_CURSOR)
        sys.stdout.flush()


def _numbered_select(labels: list[str]) -> int:
    for idx, label in enumerate(labels, 1):
        click.echo(f"    {idx}. {label}")
    click.echo()
    while True:
        choice = click.prompt("  Select", type=str, default="1")
        if choice.lower() == "q":
            return -1
        try:
            num = int(choice)
            if 1 <= num <= len(labels):
                return num - 1
        except ValueError:
            # Non-numeric input falls through to the shared error message.
            pass
        click.secho(f"  Invalid choice. Enter 1-{len(labels)}.", fg="red")


def _numbered_select_multi(
    labels: list[str],
    *,
    action_indices: set[int] | None = None,
    separator_indices: set[int] | None = None,
    preselected: set[int] | None = None,
    searchable: bool = False,
) -> tuple[list[int], int | None]:
    action_indices = action_indices or set()
    separator_indices = separator_indices or set()
    query = ""
    if searchable:
        query = str(click.prompt("  Filter", default="", show_default=False)).strip()
    visible = _visible_label_indices(
        labels, query, separator_indices, searchable=searchable
    )
    numbered_indices: list[int] = []
    if searchable and query and not visible:
        click.echo("    No matching actions")
    for idx in visible:
        label = labels[idx]
        if idx in separator_indices:
            click.secho(f"    {label}", fg="cyan")
            continue
        numbered_indices.append(idx)
        click.echo(f"    {len(numbered_indices)}. {label}")
    click.echo()
    raw = click.prompt(
        "  Select (comma-separated numbers, or empty to skip)",
        default="",
        show_default=False,
    )
    if not raw.strip():
        return sorted(preselected or ()), None
    indices: list[int] = list(preselected or ())
    for part in raw.split(","):
        with suppress(ValueError):
            num = int(part.strip())
            if 1 <= num <= len(numbered_indices):
                idx = numbered_indices[num - 1]
                if idx in action_indices:
                    return sorted(set(indices)), idx
                indices.append(idx)
    return sorted(set(indices)), None


def _first_selectable_index(total: int, separator_indices: set[int]) -> int:
    for idx in range(total):
        if idx not in separator_indices:
            return idx
    return 0


def _next_selectable_index(
    cursor: int,
    direction: int,
    total: int,
    separator_indices: set[int],
) -> int:
    next_cursor = cursor + direction
    while 0 <= next_cursor < total:
        if next_cursor not in separator_indices:
            return next_cursor
        next_cursor += direction
    return cursor


def matching_label_indices(labels: list[str], query: str) -> list[int]:
    """Original indexes whose label contains ``query``, ignoring case.

    An empty query matches every label. The returned indexes stay in label
    order so a filtered view can keep the selection tied to the full list.
    """
    needle = query.casefold()
    if not needle:
        return list(range(len(labels)))
    return [index for index, label in enumerate(labels) if needle in label.casefold()]


# ── Public API ──────────────────────────────────────────────────


def pick(title: str, options: list[tuple[str, str]]) -> str | None:
    """Arrow-key single-select picker.

    Args:
        title: Header text.
        options: List of ``(value, description)`` tuples.

    Returns:
        The *value* of the selected option, or ``None`` if cancelled.
    """
    labels = [f"{value:<12s} {desc}" for value, desc in options]

    click.echo()
    click.secho(f"  {title}", fg="cyan", bold=True)
    click.echo()

    if _is_interactive():
        try:
            idx = _arrow_select_one(labels)
        except Exception:
            idx = _numbered_select(labels)
    else:
        idx = _numbered_select(labels)

    if idx < 0:
        return None

    value, _desc = options[idx]
    click.secho(f"  ✔ {value}", fg="green")
    return value


def pick_one(title: str, labels: list[str]) -> int:
    """Arrow-key single-select from plain labels.

    Returns:
        Selected index, or ``-1`` if cancelled.
    """
    click.echo()
    click.secho(f"  {title}", fg="cyan")

    if _is_interactive():
        try:
            return _arrow_select_one(labels)
        except Exception:
            return _numbered_select(labels)
    return _numbered_select(labels)


@overload
def pick_many(
    title: str,
    labels: list[str],
    *,
    separator_indices: set[int] | None = None,
    preselected: set[int] | None = None,
    initial_cursor: int | None = None,
    searchable: bool = False,
) -> list[int]: ...


@overload
def pick_many(
    title: str,
    labels: list[str],
    *,
    action_indices: set[int],
    separator_indices: set[int] | None = None,
    preselected: set[int] | None = None,
    initial_cursor: int | None = None,
    searchable: bool = False,
) -> tuple[list[int], int | None]: ...


def pick_many(
    title: str,
    labels: list[str],
    *,
    action_indices: set[int] | None = None,
    separator_indices: set[int] | None = None,
    preselected: set[int] | None = None,
    initial_cursor: int | None = None,
    searchable: bool = False,
) -> list[int] | tuple[list[int], int | None]:
    """Arrow-key multi-select with checkboxes.

    ``searchable`` lets the user type a query. Matching rows stay tied to
    their original indexes, and checked rows stay checked when filtered out.

    Returns:
        Sorted list of selected indices, or ``(indices, action_index)`` when
        ``action_indices`` is provided.
    """
    if title:
        click.echo()
        click.secho(f"  {title}", fg="cyan")

    if _is_interactive():
        try:
            selected, action = _arrow_select_multi(
                labels,
                action_indices=action_indices,
                separator_indices=separator_indices,
                preselected=preselected,
                initial_cursor=initial_cursor,
                searchable=searchable,
            )
        except Exception:
            selected, action = _numbered_select_multi(
                labels,
                action_indices=action_indices,
                separator_indices=separator_indices,
                preselected=preselected,
                searchable=searchable,
            )
    else:
        selected, action = _numbered_select_multi(
            labels,
            action_indices=action_indices,
            separator_indices=separator_indices,
            preselected=preselected,
            searchable=searchable,
        )
    if action_indices is None:
        return selected
    return selected, action