glaip-sdk 0.0.15__py3-none-any.whl → 0.0.17__py3-none-any.whl

glaip_sdk/cli/resolution.py

@@ -32,20 +32,22 @@ def resolve_resource_reference(
     This is a common pattern used across all resource types.
 
     Args:
-        ctx: Click context
-        client: API client
-        reference: Resource ID or name
-        resource_type: Type of resource
-        get_by_id_func: Function to get resource by ID
-        find_by_name_func: Function to find resources by name
-        label: Label for error messages
-        select: Selection index for ambiguous matches
+        ctx: Click context for CLI operations.
+        _client: API client instance for backend operations.
+        reference: Resource ID or name to resolve.
+        resource_type: Type of resource being resolved.
+        get_by_id_func: Function to get resource by ID.
+        find_by_name_func: Function to find resources by name.
+        label: Label for error messages and user feedback.
+        select: Selection index for ambiguous matches in non-interactive mode.
+        interface_preference: Interface preference for user interaction ("fuzzy" or "questionary").
+        spinner_message: Custom message to show during resolution process.
 
     Returns:
-        Resolved resource object
+        Resolved resource object or None if not found.
 
     Raises:
-        click.ClickException: If resolution fails
+        click.ClickException: If resolution fails.
     """
     try:
         message = (

glaip_sdk/cli/rich_helpers.py

@@ -0,0 +1,29 @@
+"""Shared helpers for creating and printing Rich markup content.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.markup import MarkupError
+from rich.text import Text
+
+
+def markup_text(message: str, **kwargs: Any) -> Text:
+    """Create a Rich Text instance from markup with graceful fallback."""
+    try:
+        return Text.from_markup(message, **kwargs)
+    except MarkupError:
+        return Text(message, **kwargs)
+
+
+def print_markup(
+    message: str, *, console: Console | None = None, **kwargs: Any
+) -> None:
+    """Print markup-aware text to the provided console (default: new Console)."""
+    target_console = console or Console()
+    target_console.print(markup_text(message, **kwargs))

glaip_sdk/cli/slash/agent_session.py

@@ -22,6 +22,12 @@ class AgentRunSession:
     """Per-agent execution context for the command palette."""
 
     def __init__(self, session: SlashSession, agent: Any) -> None:
+        """Initialize the agent run session.
+
+        Args:
+            session: The slash session context
+            agent: The agent to interact with
+        """
         self.session = session
         self.agent = agent
         self.console = session.console
@@ -39,6 +45,7 @@ class AgentRunSession:
         }
 
     def run(self) -> None:
+        """Run the interactive agent session loop."""
         self.session.set_contextual_commands(
             self._contextual_completion_help, include_global=False
         )

glaip_sdk/cli/slash/prompt.py

@@ -46,6 +46,11 @@ if _HAS_PROMPT_TOOLKIT:
         """Provide slash command completions inside the prompt."""
 
         def __init__(self, session: SlashSession) -> None:
+            """Initialize the slash completer.
+
+            Args:
+                session: The slash session context
+            """
             self._session = session
 
         def get_completions(
@@ -53,6 +58,15 @@ if _HAS_PROMPT_TOOLKIT:
             document: Any,
             _complete_event: Any,  # type: ignore[no-any-return]
         ) -> Iterable[Completion]:  # pragma: no cover - UI
+            """Get completions for slash commands.
+
+            Args:
+                document: The document being edited
+                _complete_event: The completion event
+
+            Yields:
+                Completion objects for matching commands
+            """
             if Completion is None:
                 return
 
@@ -66,7 +80,14 @@ if _HAS_PROMPT_TOOLKIT:
 else:  # pragma: no cover - fallback when prompt_toolkit is missing
 
     class SlashCompleter:  # type: ignore[too-many-ancestors]
+        """Fallback slash completer when prompt_toolkit is not available."""
+
         def __init__(self, session: SlashSession) -> None:  # noqa: D401 - stub
+            """Initialize the fallback slash completer.
+
+            Args:
+                session: The slash session context
+            """
             self._session = session
 
 
@@ -76,7 +97,6 @@ def setup_prompt_toolkit(
     interactive: bool,
 ) -> tuple[Any | None, Any | None]:
     """Configure prompt_toolkit session and style for interactive mode."""
-
     if not (interactive and _HAS_PROMPT_TOOLKIT):
         return None, None
 
@@ -105,7 +125,6 @@ def setup_prompt_toolkit(
 
 def _create_key_bindings(session: SlashSession) -> Any:
     """Create prompt_toolkit key bindings for the command palette."""
-
     if KeyBindings is None:
         return None
 

glaip_sdk/cli/slash/session.py

@@ -19,7 +19,7 @@ from rich.table import Table
 
 from glaip_sdk.branding import AIPBranding
 from glaip_sdk.cli.commands.configure import configure_command, load_config
-from glaip_sdk.cli.utils import _fuzzy_pick_for_resources, get_client
+from glaip_sdk.cli.utils import _fuzzy_pick_for_resources, command_hint, get_client
 from glaip_sdk.rich_components import AIPPanel
 
 from .agent_session import AgentRunSession
@@ -49,6 +49,12 @@ class SlashSession:
     """Interactive command palette controller."""
 
     def __init__(self, ctx: click.Context, *, console: Console | None = None) -> None:
+        """Initialize the slash session.
+
+        Args:
+            ctx: The Click context
+            console: Optional console instance, creates default if None
+        """
         self.ctx = ctx
         self.console = console or Console()
         self._commands: dict[str, SlashCommand] = {}
@@ -90,7 +96,6 @@ class SlashSession:
 
     def run(self, initial_commands: Iterable[str] | None = None) -> None:
         """Start the command palette session loop."""
-
         if not self._interactive:
             self._run_non_interactive(initial_commands)
             return
@@ -153,7 +158,6 @@ class SlashSession:
 
     def _ensure_configuration(self) -> bool:
         """Ensure the CLI has both API URL and credentials before continuing."""
-
         while not self._configuration_ready():
             self.console.print(
                 "[yellow]Configuration required.[/] Launching `/login` wizard..."
@@ -173,7 +177,6 @@ class SlashSession:
 
     def _configuration_ready(self) -> bool:
         """Check whether API URL and credentials are available."""
-
         config = self._load_config()
         api_url = self._get_api_url(config)
         if not api_url:
@@ -188,7 +191,6 @@ class SlashSession:
 
     def handle_command(self, raw: str, *, invoked_from_agent: bool = False) -> bool:
         """Parse and execute a single slash command string."""
-
         verb, args = self._parse(raw)
         if not verb:
             self.console.print("[red]Unrecognised command[/red]")
@@ -308,9 +310,13 @@ class SlashSession:
             return True
 
         if not agents:
-            self.console.print(
-                "[yellow]No agents available. Use `aip agents create` to add one.[/yellow]"
-            )
+            hint = command_hint("agents create", slash_command=None, ctx=self.ctx)
+            if hint:
+                self.console.print(
+                    f"[yellow]No agents available. Use `{hint}` to add one.[/yellow]"
+                )
+            else:
+                self.console.print("[yellow]No agents available.[/yellow]")
             return True
 
         if args:
@@ -373,7 +379,7 @@ class SlashSession:
         self._register(
             SlashCommand(
                 name="login",
-                help="Run `aip configure` to set credentials.",
+                help="Run `/login` (alias `/configure`) to set credentials.",
                 handler=SlashSession._cmd_login,
                 aliases=("configure",),
             )
@@ -419,12 +425,10 @@ class SlashSession:
     @property
     def verbose_enabled(self) -> bool:
         """Return whether verbose agent runs are enabled."""
-
         return self._verbose_enabled
 
     def set_verbose(self, enabled: bool, *, announce: bool = True) -> None:
         """Enable or disable verbose mode with optional announcement."""
-
         if self._verbose_enabled == enabled:
             if announce:
                 self._print_verbose_status(context="already")
@@ -437,12 +441,10 @@ class SlashSession:
 
     def toggle_verbose(self, *, announce: bool = True) -> None:
         """Flip verbose mode state."""
-
         self.set_verbose(not self._verbose_enabled, announce=announce)
 
     def _cmd_verbose(self, args: list[str], _invoked_from_agent: bool) -> bool:
         """Slash handler for `/verbose` command."""
-
         if args:
             self.console.print(
                 "Usage: `/verbose` toggles verbose streaming output. Press Ctrl+T as a shortcut."
@@ -470,30 +472,25 @@ class SlashSession:
     # ------------------------------------------------------------------
     def register_active_renderer(self, renderer: Any) -> None:
         """Register the renderer currently streaming an agent run."""
-
         self._active_renderer = renderer
         self._sync_active_renderer()
 
     def clear_active_renderer(self, renderer: Any | None = None) -> None:
         """Clear the active renderer if it matches the provided instance."""
-
         if renderer is not None and renderer is not self._active_renderer:
             return
         self._active_renderer = None
 
     def notify_agent_run_started(self) -> None:
         """Mark that an agent run is in progress."""
-
         self.clear_active_renderer()
 
     def notify_agent_run_finished(self) -> None:
         """Mark that the active agent run has completed."""
-
         self.clear_active_renderer()
 
     def _sync_active_renderer(self) -> None:
         """Ensure the active renderer reflects the current verbose state."""
-
         renderer = self._active_renderer
         if renderer is None:
             return
@@ -622,18 +619,15 @@ class SlashSession:
         self, commands: dict[str, str] | None, *, include_global: bool = True
     ) -> None:
         """Set context-specific commands that should appear in completions."""
-
         self._contextual_commands = dict(commands or {})
         self._contextual_include_global = include_global if commands else True
 
     def get_contextual_commands(self) -> dict[str, str]:  # type: ignore[no-any-return]
         """Return a copy of the currently active contextual commands."""
-
         return dict(self._contextual_commands)
 
     def should_include_global_commands(self) -> bool:
         """Return whether global slash commands should appear in completions."""
-
         return self._contextual_include_global
 
     def _remember_agent(self, agent: Any) -> None:  # type: ignore[no-any-return]

glaip_sdk/cli/update_notifier.py

@@ -13,6 +13,7 @@ import httpx
 from packaging.version import InvalidVersion, Version
 from rich.console import Console
 
+from glaip_sdk.cli.utils import command_hint
 from glaip_sdk.rich_components import AIPPanel
 
 FetchLatestVersion = Callable[[], str | None]
@@ -59,6 +60,7 @@ def _should_check_for_updates() -> bool:
 def _build_update_panel(
     current_version: str,
     latest_version: str,
+    command_text: str,
 ) -> AIPPanel:
     """Create a Rich panel that prompts the user to update."""
     message = (
@@ -66,7 +68,7 @@ def _build_update_panel(
         f"{current_version} → {latest_version}\n\n"
         "See the latest release notes:\n"
         f"https://pypi.org/project/glaip-sdk/{latest_version}/\n\n"
-        "[cyan]Run[/cyan] [bold]aip update[/bold] to install."
+        f"[cyan]Run[/cyan] [bold]{command_text}[/bold] to install."
     )
     return AIPPanel(
         message,
@@ -99,8 +101,12 @@ def maybe_notify_update(
     if current is None or latest is None or latest <= current:
         return
 
+    command_text = command_hint("update")
+    if command_text is None:
+        return
+
     active_console = console or Console()
-    panel = _build_update_panel(current_version, latest_version)
+    panel = _build_update_panel(current_version, latest_version, command_text)
     active_console.print(panel)
 
 

glaip_sdk/cli/utils.py

@@ -19,7 +19,9 @@ import click
 from rich.console import Console, Group
 from rich.markdown import Markdown
 from rich.pretty import Pretty
-from rich.text import Text
+
+from glaip_sdk.cli.rich_helpers import markup_text
+from glaip_sdk.rich_components import AIPPanel
 
 # Optional interactive deps (fuzzy palette)
 try:
@@ -38,9 +40,15 @@ except Exception:  # pragma: no cover - optional dependency
 if TYPE_CHECKING:  # pragma: no cover - import-only during type checking
     from glaip_sdk import Client
 from glaip_sdk.cli import masking, pager
-from glaip_sdk.cli.commands.configure import load_config
-from glaip_sdk.cli.context import _get_view, get_ctx_value
-from glaip_sdk.rich_components import AIPPanel, AIPTable
+from glaip_sdk.cli.config import load_config
+from glaip_sdk.cli.context import (
+    _get_view,
+    get_ctx_value,
+)
+from glaip_sdk.cli.context import (
+    detect_export_format as _detect_export_format,
+)
+from glaip_sdk.rich_components import AIPTable
 from glaip_sdk.utils import is_uuid
 from glaip_sdk.utils.rendering.renderer import (
     CapturingConsole,
@@ -53,6 +61,59 @@ pager.console = console
 logger = logging.getLogger("glaip_sdk.cli.utils")
 
 
+# ----------------------------- Context helpers ---------------------------- #
+
+
+def detect_export_format(file_path: str | os.PathLike[str]) -> str:
+    """Backward-compatible proxy to `glaip_sdk.cli.context.detect_export_format`."""
+    return _detect_export_format(file_path)
+
+
+def in_slash_mode(ctx: click.Context | None = None) -> bool:
+    """Return True when running inside the slash command palette."""
+    if ctx is None:
+        try:
+            ctx = click.get_current_context(silent=True)
+        except RuntimeError:
+            ctx = None
+
+    if ctx is None:
+        return False
+
+    obj = getattr(ctx, "obj", None)
+    if isinstance(obj, dict):
+        return bool(obj.get("_slash_session"))
+
+    return bool(getattr(obj, "_slash_session", False))
+
+
+def command_hint(
+    cli_command: str | None,
+    slash_command: str | None = None,
+    *,
+    ctx: click.Context | None = None,
+) -> str | None:
+    """Return the appropriate command string for the current mode.
+
+    Args:
+        cli_command: Command string without the ``aip`` prefix (e.g., ``"status"``).
+        slash_command: Slash command counterpart (e.g., ``"status"`` or ``"/status"``).
+        ctx: Optional Click context override.
+
+    Returns:
+        The formatted command string for the active mode, or ``None`` when no
+        equivalent command exists in that mode.
+    """
+    if in_slash_mode(ctx):
+        if not slash_command:
+            return None
+        return slash_command if slash_command.startswith("/") else f"/{slash_command}"
+
+    if not cli_command:
+        return None
+    return f"aip {cli_command}"
+
+
 def spinner_context(
     ctx: Any | None,
     message: str,
@@ -62,7 +123,6 @@ def spinner_context(
     spinner_style: str = "cyan",
 ) -> AbstractContextManager[Any]:
     """Return a context manager that renders a spinner when appropriate."""
-
     active_console = console_override or console
     if not _can_use_spinner(ctx, active_console):
         return nullcontext()
@@ -76,7 +136,6 @@ def spinner_context(
 
 def _can_use_spinner(ctx: Any | None, active_console: Console) -> bool:
     """Check if spinner output is allowed in the current environment."""
-
     if ctx is not None:
         tty_enabled = bool(get_ctx_value(ctx, "tty", True))
         view = (_get_view(ctx) or "rich").lower()
@@ -91,7 +150,6 @@ def _can_use_spinner(ctx: Any | None, active_console: Console) -> bool:
 
 def _stream_supports_tty(stream: Any) -> bool:
     """Return True if the provided stream can safely render a spinner."""
-
     target = stream if hasattr(stream, "isatty") else sys.stdout
     try:
         return bool(target.isatty())
@@ -101,7 +159,6 @@ def _stream_supports_tty(stream: Any) -> bool:
 
 def update_spinner(status_indicator: Any | None, message: str) -> None:
     """Update spinner text when a status indicator is active."""
-
     if status_indicator is None:
         return
 
@@ -113,7 +170,6 @@ def update_spinner(status_indicator: Any | None, message: str) -> None:
 
 def stop_spinner(status_indicator: Any | None) -> None:
     """Stop an active spinner safely."""
-
     if status_indicator is None:
         return
 
@@ -160,9 +216,12 @@ def get_client(ctx: Any) -> Client:  # pragma: no cover
     }
 
     if not config.get("api_url") or not config.get("api_key"):
-        raise click.ClickException(
-            "Missing api_url/api_key. Run `aip configure` or set AIP_* env vars."
-        )
+        configure_hint = command_hint("configure", slash_command="login", ctx=ctx)
+        actions = []
+        if configure_hint:
+            actions.append(f"Run `{configure_hint}`")
+        actions.append("set AIP_* env vars")
+        raise click.ClickException(f"Missing api_url/api_key. {' or '.join(actions)}.")
 
     return Client(
         api_url=config.get("api_url"),
@@ -171,6 +230,8 @@ def get_client(ctx: Any) -> Client:  # pragma: no cover
     )
 
 
+# ----------------------------- Secret masking ---------------------------- #
+
 # ----------------------------- Fuzzy palette ----------------------------- #
 
 
@@ -237,8 +298,8 @@ def _build_display_parts(
 
 
 def _row_display(row: dict[str, Any], columns: list[tuple]) -> str:
-    """
-    Build a compact text label for the palette.
+    """Build a compact text label for the palette.
+
     Prefers: name • type • framework • [id] (when available)
     Falls back to first 2 columns + [id].
     """
@@ -331,8 +392,8 @@ def _perform_fuzzy_search(
 def _fuzzy_pick(
     rows: list[dict[str, Any]], columns: list[tuple], title: str
 ) -> dict[str, Any] | None:  # pragma: no cover - requires interactive prompt toolkit
-    """
-    Open a minimal fuzzy palette using prompt_toolkit.
+    """Open a minimal fuzzy palette using prompt_toolkit.
+
     Returns the selected row (dict) or None if cancelled/missing deps.
     """
     if not _check_fuzzy_pick_requirements():
@@ -401,8 +462,8 @@ def _calculate_length_bonus(search: str, target: str) -> int:
 
 
 def _fuzzy_score(search: str, target: str) -> int:
-    """
-    Calculate fuzzy match score.
+    """Calculate fuzzy match score.
+
     Higher score = better match.
     Returns -1 if no match possible.
     """
@@ -465,8 +526,15 @@ def output_result(
     result: Any,
     title: str = "Result",
     panel_title: str | None = None,
-    success_message: str | None = None,
 ) -> None:
+    """Output a result to the console with optional title.
+
+    Args:
+        ctx: Click context
+        result: Result data to output
+        title: Optional title for the output
+        panel_title: Optional Rich panel title for structured output
+    """
     fmt = _get_view(ctx)
 
     data = _coerce_result_payload(result)
@@ -485,20 +553,12 @@ def output_result(
         _render_markdown_output(data)
         return
 
-    if success_message:
-        console.print(Text(f"[green]✅ {success_message}[/green]"))
-
+    renderable = Pretty(data)
     if panel_title:
-        console.print(
-            AIPPanel(
-                Pretty(data),
-                title=panel_title,
-                border_style="blue",
-            )
-        )
+        console.print(AIPPanel(renderable, title=panel_title))
     else:
-        console.print(Text(f"[cyan]{title}:[/cyan]"))
-        console.print(Pretty(data))
+        console.print(markup_text(f"[cyan]{title}:[/cyan]"))
+        console.print(renderable)
 
 
 # ----------------------------- List rendering ---------------------------- #
@@ -575,7 +635,7 @@ def _build_table_group(
     table = _create_table(columns, title)
     for row in rows:
         table.add_row(*[str(row.get(key, "N/A")) for key, _, _, _ in columns])
-    footer = Text.from_markup(f"\n[dim]Total {len(rows)} items[/dim]")
+    footer = markup_text(f"\n[dim]Total {len(rows)} items[/dim]")
     return Group(table, footer)
 
 
@@ -605,12 +665,11 @@ def _handle_markdown_output(
 
 def _handle_empty_items(title: str) -> None:
     """Handle case when no items are found."""
-    console.print(Text.from_markup(f"[yellow]No {title.lower()} found.[/yellow]"))
+    console.print(markup_text(f"[yellow]No {title.lower()} found.[/yellow]"))
 
 
 def _should_use_fuzzy_picker() -> bool:
     """Return True when the interactive fuzzy picker can be shown."""
-
     return console.is_terminal and os.isatty(1)
 
 
@@ -618,7 +677,6 @@ def _try_fuzzy_pick(
     rows: list[dict[str, Any]], columns: list[tuple], title: str
 ) -> dict[str, Any] | None:
     """Best-effort fuzzy selection; returns None if the picker fails."""
-
     if not _should_use_fuzzy_picker():
         return None
 
@@ -629,36 +687,34 @@ def _try_fuzzy_pick(
         return None
 
 
-def _resource_tip_command(title: str) -> str:
+def _resource_tip_command(title: str) -> str | None:
     """Resolve the follow-up command hint for the given table title."""
-
     title_lower = title.lower()
     mapping = {
-        "agent": "aip agents get",
-        "tool": "aip tools get",
-        "mcp": "aip mcps get",
-        "model": "aip models list",  # models only ship a list command
+        "agent": ("agents get", "agents"),
+        "tool": ("tools get", None),
+        "mcp": ("mcps get", None),
+        "model": ("models list", None),  # models only ship a list command
     }
-    for keyword, command in mapping.items():
+    for keyword, (cli_command, slash_command) in mapping.items():
         if keyword in title_lower:
-            return command
-    return "aip agents get"
+            return command_hint(cli_command, slash_command=slash_command)
+    return command_hint("agents get", slash_command="agents")
 
 
 def _print_selection_tip(title: str) -> None:
     """Print the contextual follow-up tip after a fuzzy selection."""
-
     tip_cmd = _resource_tip_command(title)
-    console.print(
-        Text.from_markup(f"\n[dim]Tip: use `{tip_cmd} <ID>` for details[/dim]")
-    )
+    if tip_cmd:
+        console.print(
+            markup_text(f"\n[dim]Tip: use `{tip_cmd} <ID>` for details[/dim]")
+        )
 
 
 def _handle_fuzzy_pick_selection(
     rows: list[dict[str, Any]], columns: list[tuple], title: str
 ) -> bool:
     """Handle fuzzy picker selection, returns True if selection was made."""
-
     picked = _try_fuzzy_pick(rows, columns, title)
     if picked is None:
         return False
@@ -773,14 +829,16 @@ def build_renderer(
     """Build renderer and capturing console for CLI commands.
 
     Args:
-        ctx: Click context
-        save_path: Path to save output to (enables capturing)
-        theme: Color theme ("dark" or "light")
-        verbose: Whether to enable verbose mode
-        tty_enabled: Whether TTY is available
+        _ctx: Click context object for CLI operations.
+        save_path: Path to save output to (enables capturing console).
+        theme: Color theme ("dark" or "light").
+        verbose: Whether to enable verbose mode.
+        _tty_enabled: Whether TTY is available for interactive features.
+        live: Whether to enable live rendering mode (overrides verbose default).
+        snapshots: Whether to capture and store snapshots.
 
     Returns:
-        Tuple of (renderer, capturing_console)
+        Tuple of (renderer, capturing_console) for streaming output.
     """
     # Use capturing console if saving output
     working_console = console
@@ -859,8 +917,7 @@ def _build_resource_labels(resources: list[Any]) -> tuple[list[str], dict[str, A
 def _fuzzy_pick_for_resources(
     resources: list[Any], resource_type: str, _search_term: str
 ) -> Any | None:  # pragma: no cover - interactive selection helper
-    """
-    Fuzzy picker for resource objects, similar to _fuzzy_pick but without column dependencies.
+    """Fuzzy picker for resource objects, similar to _fuzzy_pick but without column dependencies.
 
     Args:
         resources: List of resource objects to choose from
@@ -1035,7 +1092,7 @@ def _handle_fallback_numeric_ambiguity(
     safe_ref = ref.replace("{", "{{").replace("}", "}}")
 
     console.print(
-        Text(
+        markup_text(
             f"[yellow]Multiple {safe_resource_type}s found matching '{safe_ref}':[/yellow]"
         )
     )