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

glaip_sdk/cli/main.py

@@ -19,11 +19,11 @@ from glaip_sdk.cli.commands.agents import agents_group
 from glaip_sdk.cli.commands.configure import (
     config_group,
     configure_command,
-    load_config,
 )
 from glaip_sdk.cli.commands.mcps import mcps_group
 from glaip_sdk.cli.commands.models import models_group
 from glaip_sdk.cli.commands.tools import tools_group
+from glaip_sdk.cli.config import load_config
 from glaip_sdk.cli.update_notifier import maybe_notify_update
 from glaip_sdk.cli.utils import spinner_context, update_spinner
 from glaip_sdk.config.constants import (
@@ -73,7 +73,6 @@ def main(
         aip tools create my_tool.py      # Create a new tool
         aip agents run my-agent "Hello world"  # Run an agent
     """
-
     # Store configuration in context
     ctx.ensure_object(dict)
     ctx.obj["api_url"] = api_url
@@ -116,7 +115,6 @@ main.add_command(configure_command)
 
 def _should_launch_slash(ctx: click.Context) -> bool:
     """Determine whether to open the command palette automatically."""
-
     ctx_obj = ctx.obj or {}
     if not bool(ctx_obj.get("tty", True)):
         return False
@@ -127,6 +125,137 @@ def _should_launch_slash(ctx: click.Context) -> bool:
     return True
 
 
+def _load_and_merge_config(ctx: click.Context) -> dict:
+    """Load configuration from multiple sources and merge them."""
+    # Load config from file and merge with context
+    file_config = load_config()
+    context_config = ctx.obj or {}
+
+    # Load environment variables (middle priority)
+    env_config = {}
+    if os.getenv("AIP_API_URL"):
+        env_config["api_url"] = os.getenv("AIP_API_URL")
+    if os.getenv("AIP_API_KEY"):
+        env_config["api_key"] = os.getenv("AIP_API_KEY")
+
+    # Filter out None values from context config to avoid overriding other configs
+    filtered_context = {k: v for k, v in context_config.items() if v is not None}
+
+    # Merge configs: file (low) -> env (mid) -> CLI args (high)
+    return {**file_config, **env_config, **filtered_context}
+
+
+def _validate_config_and_show_error(config: dict, console: Console) -> None:
+    """Validate configuration and show error if incomplete."""
+    if not config.get("api_url") or not config.get("api_key"):
+        console.print(
+            AIPPanel(
+                "[bold red]❌ Configuration incomplete[/bold red]\n\n"
+                f"🔍 Current config:\n"
+                f"   • API URL: {config.get('api_url', 'Not set')}\n"
+                f"   • API Key: {'***' + config.get('api_key', '')[-4:] if config.get('api_key') else 'Not set'}\n\n"
+                f"💡 To fix this:\n"
+                f"   • Run 'aip configure' to set up credentials\n"
+                f"   • Or run 'aip config list' to see current config",
+                title="❌ Configuration Error",
+                border_style="red",
+            )
+        )
+        console.print(
+            f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION}) - Configure to connect"
+        )
+        sys.exit(1)
+
+
+def _create_and_test_client(config: dict, console: Console) -> Client:
+    """Create client and test connection by fetching resources."""
+    # Try to create client
+    client = Client(
+        api_url=config["api_url"],
+        api_key=config["api_key"],
+        timeout=config.get("timeout", 30.0),
+    )
+
+    # Test connection by listing resources
+    try:
+        with spinner_context(
+            None,  # We'll pass ctx later
+            "[bold blue]Checking GL AIP status…[/bold blue]",
+            console_override=console,
+            spinner_style="cyan",
+        ) as status_indicator:
+            update_spinner(status_indicator, "[bold blue]Fetching agents…[/bold blue]")
+            agents = client.list_agents()
+
+            update_spinner(status_indicator, "[bold blue]Fetching tools…[/bold blue]")
+            tools = client.list_tools()
+
+            update_spinner(status_indicator, "[bold blue]Fetching MCPs…[/bold blue]")
+            mcps = client.list_mcps()
+
+        # Create status table
+        table = AIPTable(title="🔗 GL AIP Status")
+        table.add_column("Resource", style="cyan", width=15)
+        table.add_column("Count", style="green", width=10)
+        table.add_column("Status", style="green", width=15)
+
+        table.add_row("Agents", str(len(agents)), "✅ Available")
+        table.add_row("Tools", str(len(tools)), "✅ Available")
+        table.add_row("MCPs", str(len(mcps)), "✅ Available")
+
+        console.print(
+            AIPPanel(
+                f"[bold green]✅ Connected to GL AIP[/bold green]\n"
+                f"🔗 API URL: {client.api_url}\n"
+                f"🤖 Agent Run Timeout: {DEFAULT_AGENT_RUN_TIMEOUT}s",
+                title="🚀 Connection Status",
+                border_style="green",
+            )
+        )
+
+        console.print(table)
+
+    except Exception as e:
+        # Show AIP Ready status even if connection fails
+        console.print(
+            f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION})"
+        )
+
+        console.print(
+            AIPPanel(
+                f"[bold yellow]⚠️  Connection established but API call failed[/bold yellow]\n"
+                f"🔗 API URL: {client.api_url}\n"
+                f"❌ Error: {e}\n\n"
+                f"💡 This usually means:\n"
+                f"   • Network connectivity issues\n"
+                f"   • API permissions problems\n"
+                f"   • Backend service issues",
+                title="⚠️  Partial Connection",
+                border_style="yellow",
+            )
+        )
+
+    return client
+
+
+def _handle_connection_error(config: dict, console: Console, error: Exception) -> None:
+    """Handle connection errors and show troubleshooting information."""
+    console.print(
+        AIPPanel(
+            f"[bold red]❌ Connection failed[/bold red]\n\n"
+            f"🔍 Error: {error}\n\n"
+            f"💡 Troubleshooting steps:\n"
+            f"   • Verify your API URL and key are correct\n"
+            f"   • Check network connectivity to {config.get('api_url', 'your API')}\n"
+            f"   • Run 'aip configure' to update credentials\n"
+            f"   • Run 'aip config list' to check configuration",
+            title="❌ Connection Error",
+            border_style="red",
+        )
+    )
+    sys.exit(1)
+
+
 @main.command()
 @click.pass_context
 def status(ctx: Any) -> None:
@@ -146,132 +275,20 @@ def status(ctx: Any) -> None:
             f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION})"
         )
 
-        # Load config from file and merge with context
-        file_config = load_config()
-        context_config = ctx.obj or {}
-
-        # Load environment variables (middle priority)
-
-        env_config = {}
-        if os.getenv("AIP_API_URL"):
-            env_config["api_url"] = os.getenv("AIP_API_URL")
-        if os.getenv("AIP_API_KEY"):
-            env_config["api_key"] = os.getenv("AIP_API_KEY")
-
-        # Filter out None values from context config to avoid overriding other configs
-        filtered_context = {k: v for k, v in context_config.items() if v is not None}
-
-        # Merge configs: file (low) -> env (mid) -> CLI args (high)
-        config = {**file_config, **env_config, **filtered_context}
-
-        if not config.get("api_url") or not config.get("api_key"):
-            console.print(
-                AIPPanel(
-                    "[bold red]❌ Configuration incomplete[/bold red]\n\n"
-                    f"🔍 Current config:\n"
-                    f"   • API URL: {config.get('api_url', 'Not set')}\n"
-                    f"   • API Key: {'***' + config.get('api_key', '')[-4:] if config.get('api_key') else 'Not set'}\n\n"
-                    f"💡 To fix this:\n"
-                    f"   • Run 'aip configure' to set up credentials\n"
-                    f"   • Or run 'aip config list' to see current config",
-                    title="❌ Configuration Error",
-                    border_style="red",
-                )
-            )
-            console.print(
-                f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION}) - Configure to connect"
-            )
-            sys.exit(1)
-
-        # Try to create client
-        client = Client(
-            api_url=config["api_url"],
-            api_key=config["api_key"],
-            timeout=config.get("timeout", 30.0),
-        )
-
-        # Test connection by listing resources
-        try:
-            with spinner_context(
-                ctx,
-                "[bold blue]Checking GL AIP status…[/bold blue]",
-                console_override=console,
-                spinner_style="cyan",
-            ) as status_indicator:
-                update_spinner(
-                    status_indicator, "[bold blue]Fetching agents…[/bold blue]"
-                )
-                agents = client.list_agents()
+        # Load and merge configuration
+        config = _load_and_merge_config(ctx)
 
-                update_spinner(
-                    status_indicator, "[bold blue]Fetching tools…[/bold blue]"
-                )
-                tools = client.list_tools()
-
-                update_spinner(
-                    status_indicator, "[bold blue]Fetching MCPs…[/bold blue]"
-                )
-                mcps = client.list_mcps()
-
-            # Create status table
-            table = AIPTable(title="🔗 GL AIP Status")
-            table.add_column("Resource", style="cyan", width=15)
-            table.add_column("Count", style="green", width=10)
-            table.add_column("Status", style="green", width=15)
-
-            table.add_row("Agents", str(len(agents)), "✅ Available")
-            table.add_row("Tools", str(len(tools)), "✅ Available")
-            table.add_row("MCPs", str(len(mcps)), "✅ Available")
-
-            console.print(
-                AIPPanel(
-                    f"[bold green]✅ Connected to GL AIP[/bold green]\n"
-                    f"🔗 API URL: {client.api_url}\n"
-                    f"🤖 Agent Run Timeout: {DEFAULT_AGENT_RUN_TIMEOUT}s",
-                    title="🚀 Connection Status",
-                    border_style="green",
-                )
-            )
-
-            console.print(table)
-
-        except Exception as e:
-            # Show AIP Ready status even if connection fails
-            console.print(
-                f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION})"
-            )
-
-            console.print(
-                AIPPanel(
-                    f"[bold yellow]⚠️  Connection established but API call failed[/bold yellow]\n"
-                    f"🔗 API URL: {client.api_url}\n"
-                    f"❌ Error: {e}\n\n"
-                    f"💡 This usually means:\n"
-                    f"   • Network connectivity issues\n"
-                    f"   • API permissions problems\n"
-                    f"   • Backend service issues",
-                    title="⚠️  Partial Connection",
-                    border_style="yellow",
-                )
-            )
+        # Validate configuration
+        _validate_config_and_show_error(config, console)
 
+        # Create and test client connection
+        client = _create_and_test_client(config, console)
         client.close()
 
     except Exception as e:
-        console.print(
-            AIPPanel(
-                f"[bold red]❌ Connection failed[/bold red]\n\n"
-                f"🔍 Error: {e}\n\n"
-                f"💡 Troubleshooting steps:\n"
-                f"   • Run 'aip config list' to check configuration\n"
-                f"   • Run 'aip configure' to update credentials\n"
-                f"   • Verify your API URL and key are correct\n"
-                f"   • Check network connectivity to {config.get('api_url', 'your API')}",
-                title="❌ Connection Error",
-                border_style="red",
-            )
-        )
-        sys.exit(1)
+        # Handle any unexpected errors during the process
+        console = Console()
+        _handle_connection_error(config if "config" in locals() else {}, console, e)
 
 
 @main.command()

glaip_sdk/cli/mcp_validators.py

@@ -15,7 +15,7 @@ import click
 
 
 def format_validation_error(prefix: str, detail: str | None = None) -> str:
-    """Format a validation error message with optional detail.
+    r"""Format a validation error message with optional detail.
 
     Args:
         prefix: Main error message
@@ -26,7 +26,7 @@ def format_validation_error(prefix: str, detail: str | None = None) -> str:
 
     Examples:
         >>> format_validation_error("Invalid config", "Missing 'url' field")
-        "Invalid config\\nMissing 'url' field"
+        "Invalid config\nMissing 'url' field"
     """
     parts = [prefix]
     if detail:

glaip_sdk/cli/pager.py

@@ -57,8 +57,9 @@ def _get_console() -> Console:
 
 
 def _prepare_pager_env(clear_on_exit: bool = True) -> None:
-    """
-    Configure LESS flags for a predictable, high-quality UX:
+    """Configure LESS flags for a predictable, high-quality UX.
+
+    Sets sensible defaults for the system pager:
       -R  : pass ANSI color escapes
       -S  : chop long lines (horizontal scroll with ←/→)
     (No -F, no -X) so we open a full-screen pager and clear on exit.

glaip_sdk/cli/parsers/json_input.py

@@ -17,7 +17,7 @@ import click
 def _format_file_error(
     prefix: str, file_path_str: str, resolved_path: Path, *, detail: str | None = None
 ) -> str:
-    """Format a file-related error message with path context.
+    r"""Format a file-related error message with path context.
 
     Args:
         prefix: Main error message
@@ -31,7 +31,7 @@ def _format_file_error(
     Examples:
         >>> from pathlib import Path
         >>> _format_file_error("File not found", "config.json", Path("/abs/config.json"))
-        'File not found: config.json\\nResolved path: /abs/config.json'
+        'File not found: config.json\nResolved path: /abs/config.json'
     """
     parts = [f"{prefix}: {file_path_str}", f"Resolved path: {resolved_path}"]
     if detail:

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/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)