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

glaip_sdk/branding.py

@@ -60,7 +60,8 @@ GDP Labs AI Agents Package
         version: str | None = None,
         package_name: str | None = None,
     ) -> None:
-        """
+        """Initialize AIPBranding instance.
+
         Args:
             version: Explicit SDK version (overrides auto-detection).
             package_name: If set, attempt to read version from installed package.
@@ -105,6 +106,11 @@ GDP Labs AI Agents Package
         return banner
 
     def get_version_info(self) -> dict:
+        """Get comprehensive version information for the SDK.
+
+        Returns:
+            Dictionary containing version, Python version, platform, and architecture info
+        """
         return {
             "version": self.version,
             "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
@@ -113,6 +119,11 @@ GDP Labs AI Agents Package
         }
 
     def display_welcome_panel(self, title: str = "Welcome to AIP") -> None:
+        """Display a welcome panel with branding.
+
+        Args:
+            title: Custom title for the welcome panel
+        """
         banner = self.get_welcome_banner()
         panel = AIPPanel(
             banner,
@@ -123,6 +134,7 @@ GDP Labs AI Agents Package
         self.console.print(panel)
 
     def display_version_panel(self) -> None:
+        """Display a panel with comprehensive version information."""
         v = self.get_version_info()
         version_text = (
             f"[{TITLE_STYLE}]AIP SDK Version Information[/{TITLE_STYLE}]\n\n"
@@ -140,6 +152,11 @@ GDP Labs AI Agents Package
         self.console.print(panel)
 
     def display_status_banner(self, status: str = "ready") -> None:
+        """Display a status banner for the current state.
+
+        Args:
+            status: Current status to display
+        """
         # Keep it simple (no emoji); easy to parse in logs/CI
         banner = f"[{LABEL}]AIP[/{LABEL}] - {status.title()}"
         self.console.print(banner)
@@ -148,4 +165,13 @@ GDP Labs AI Agents Package
     def create_from_sdk(
         cls, sdk_version: str | None = None, package_name: str | None = None
     ) -> AIPBranding:
+        """Create AIPBranding instance from SDK package information.
+
+        Args:
+            sdk_version: Explicit SDK version override
+            package_name: Package name to read version from
+
+        Returns:
+            AIPBranding instance
+        """
         return cls(version=sdk_version, package_name=package_name)

glaip_sdk/cli/commands/agents.py

@@ -78,7 +78,6 @@ AGENT_NOT_FOUND_ERROR = "Agent not found"
 
 def _safe_agent_attribute(agent: Any, name: str) -> Any:
     """Return attribute value for ``name`` while filtering Mock sentinels."""
-
     try:
         value = getattr(agent, name)
     except Exception:
@@ -91,7 +90,6 @@ def _safe_agent_attribute(agent: Any, name: str) -> Any:
 
 def _coerce_mapping_candidate(candidate: Any) -> dict[str, Any] | None:
     """Convert a mapping-like candidate to a plain dict when possible."""
-
     if candidate is None:
         return None
     if isinstance(candidate, Mapping):
@@ -101,7 +99,6 @@ def _coerce_mapping_candidate(candidate: Any) -> dict[str, Any] | None:
 
 def _call_agent_method(agent: Any, method_name: str) -> dict[str, Any] | None:
     """Attempt to call the named method and coerce its output to a dict."""
-
     method = getattr(agent, method_name, None)
     if not callable(method):
         return None
@@ -114,7 +111,6 @@ def _call_agent_method(agent: Any, method_name: str) -> dict[str, Any] | None:
 
 def _coerce_agent_via_methods(agent: Any) -> dict[str, Any] | None:
     """Try standard serialisation helpers to produce a mapping."""
-
     for attr in ("model_dump", "dict", "to_dict"):
         mapping = _call_agent_method(agent, attr)
         if mapping is not None:
@@ -124,7 +120,6 @@ def _coerce_agent_via_methods(agent: Any) -> dict[str, Any] | None:
 
 def _build_fallback_agent_mapping(agent: Any) -> dict[str, Any]:
     """Construct a minimal mapping from well-known agent attributes."""
-
     fallback_fields = (
         "id",
         "name",
@@ -136,6 +131,7 @@ def _build_fallback_agent_mapping(agent: Any) -> dict[str, Any]:
         "agents",
         "mcps",
         "timeout",
+        "tool_configs",
     )
 
     fallback: dict[str, Any] = {}
@@ -149,7 +145,6 @@ def _build_fallback_agent_mapping(agent: Any) -> dict[str, Any]:
 
 def _prepare_agent_output(agent: Any) -> dict[str, Any]:
     """Build a JSON-serialisable mapping for CLI output."""
-
     method_mapping = _coerce_agent_via_methods(agent)
     if method_mapping is not None:
         return method_mapping
@@ -256,11 +251,11 @@ def _format_fallback_agent_data(client: Any, agent: Any) -> dict:
         "metadata",
         "language_model_id",
         "agent_config",
-        "tool_configs",
         "tools",
         "agents",
         "mcps",
         "a2a_profile",
+        "tool_configs",
     ]
 
     result_data = build_resource_result_data(full_agent, fields)
@@ -297,8 +292,7 @@ def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
         output_result(
             ctx,
             formatted_data,
-            title="Agent Details",
-            panel_title=panel_title,
+            title=panel_title,
         )
     else:
         # Fall back to Pydantic model data if raw fetch fails
@@ -318,7 +312,6 @@ def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
             ctx,
             result_data,
             title="Agent Details",
-            panel_title=f"🤖 {result_data.get('name', 'Unknown')}",
         )
 
 
@@ -338,7 +331,14 @@ def _resolve_agent(
     """Resolve agent reference (ID or name) with ambiguity handling.
 
     Args:
-        interface_preference: "fuzzy" for fuzzy picker, "questionary" for up/down list
+        ctx: Click context object for CLI operations.
+        client: AIP client instance for API operations.
+        ref: Agent reference (ID or name) to resolve.
+        select: Pre-selected agent index for non-interactive mode.
+        interface_preference: "fuzzy" for fuzzy picker, "questionary" for up/down list.
+
+    Returns:
+        Resolved agent object or None if not found.
     """
     return resolve_resource_reference(
         ctx,
@@ -878,7 +878,6 @@ def _add_import_file_attributes(
         "type",
         "framework",
         "version",
-        "tool_configs",
         "mcps",
         "a2a_profile",
     }
@@ -1050,6 +1049,7 @@ def _handle_update_import_file(
     instruction: str | None,
     tools: tuple[str, ...] | None,
     agents: tuple[str, ...] | None,
+    mcps: tuple[str, ...] | None,
     timeout: float | None,
 ) -> tuple[
     Any | None,
@@ -1057,11 +1057,12 @@ def _handle_update_import_file(
     str | None,
     tuple[str, ...] | None,
     tuple[str, ...] | None,
+    tuple[str, ...] | None,
     float | None,
 ]:
     """Handle import file processing for agent update."""
     if not import_file:
-        return None, name, instruction, tools, agents, timeout
+        return None, name, instruction, tools, agents, mcps, timeout
 
     import_data = load_resource_from_file(Path(import_file), "agent")
     import_data = convert_export_to_import_format(import_data)
@@ -1072,6 +1073,7 @@ def _handle_update_import_file(
         "instruction": instruction,
         "tools": tools or (),
         "agents": agents or (),
+        "mcps": mcps or (),
         "timeout": timeout,
     }
 
@@ -1083,6 +1085,7 @@ def _handle_update_import_file(
         merged_data.get("instruction"),
         tuple(merged_data.get("tools", ())),
         tuple(merged_data.get("agents", ())),
+        tuple(merged_data.get("mcps", ())),
         coerce_timeout(merged_data.get("timeout")),
     )
 
@@ -1092,6 +1095,7 @@ def _build_update_data(
     instruction: str | None,
     tools: tuple[str, ...] | None,
     agents: tuple[str, ...] | None,
+    mcps: tuple[str, ...] | None,
     timeout: float | None,
 ) -> dict[str, Any]:
     """Build the update data dictionary from provided parameters."""
@@ -1104,6 +1108,8 @@ def _build_update_data(
         update_data["tools"] = list(tools)
     if agents:
         update_data["agents"] = list(agents)
+    if mcps:
+        update_data["mcps"] = list(mcps)
     if timeout is not None:
         update_data["timeout"] = timeout
     return update_data
@@ -1141,8 +1147,6 @@ def _handle_update_import_config(
         "type",
         "framework",
         "version",
-        "tool_configs",
-        "mcps",
         "a2a_profile",
     }
     for key, value in merged_data.items():
@@ -1156,6 +1160,7 @@ def _handle_update_import_config(
 @click.option("--instruction", help="New instruction")
 @click.option("--tools", multiple=True, help="New tool names or IDs")
 @click.option("--agents", multiple=True, help="New sub-agent names")
+@click.option("--mcps", multiple=True, help="New MCP names or IDs")
 @click.option("--timeout", type=int, help="New timeout value")
 @click.option(
     "--import",
@@ -1172,6 +1177,7 @@ def update(
     instruction: str | None,
     tools: tuple[str, ...] | None,
     agents: tuple[str, ...] | None,
+    mcps: tuple[str, ...] | None,
     timeout: float | None,
     import_file: str | None,
 ) -> None:
@@ -1192,12 +1198,15 @@ def update(
             instruction,
             tools,
             agents,
+            mcps,
             timeout,
         ) = _handle_update_import_file(
-            import_file, name, instruction, tools, agents, timeout
+            import_file, name, instruction, tools, agents, mcps, timeout
         )
 
-        update_data = _build_update_data(name, instruction, tools, agents, timeout)
+        update_data = _build_update_data(
+            name, instruction, tools, agents, mcps, timeout
+        )
 
         if merged_data:
             _handle_update_import_config(import_file, merged_data, update_data)

glaip_sdk/cli/commands/configure.py

@@ -5,51 +5,20 @@ Authors:
 """
 
 import getpass
-import os
-from pathlib import Path
-from typing import Any
 
 import click
-import yaml
 from rich.console import Console
 from rich.text import Text
 
 from glaip_sdk import Client
 from glaip_sdk._version import __version__ as _SDK_VERSION
 from glaip_sdk.branding import AIPBranding
+from glaip_sdk.cli.config import CONFIG_FILE, load_config, save_config
+from glaip_sdk.cli.utils import command_hint
 from glaip_sdk.rich_components import AIPTable
 
 console = Console()
 
-CONFIG_DIR = Path.home() / ".aip"
-CONFIG_FILE = CONFIG_DIR / "config.yaml"
-
-
-def load_config() -> dict[str, Any]:
-    """Load configuration from file."""
-    if not CONFIG_FILE.exists():
-        return {}
-
-    try:
-        with open(CONFIG_FILE) as f:
-            return yaml.safe_load(f) or {}
-    except yaml.YAMLError:
-        return {}
-
-
-def save_config(config: dict[str, Any]) -> None:
-    """Save configuration to file."""
-    CONFIG_DIR.mkdir(exist_ok=True)
-
-    with open(CONFIG_FILE, "w") as f:
-        yaml.dump(config, f, default_flow_style=False)
-
-    # Set secure file permissions
-    try:
-        os.chmod(CONFIG_FILE, 0o600)
-    except Exception:  # pragma: no cover - platform dependent best effort
-        pass
-
 
 @click.group()
 def config_group() -> None:
@@ -60,13 +29,16 @@ def config_group() -> None:
 @config_group.command("list")
 def list_config() -> None:
     """List current configuration."""
-
     config = load_config()
 
     if not config:
-        console.print(
-            "[yellow]No configuration found. Run 'aip config configure' to set up.[/yellow]"
-        )
+        hint = command_hint("config configure", slash_command="login")
+        if hint:
+            console.print(
+                f"[yellow]No configuration found. Run '{hint}' to set up.[/yellow]"
+            )
+        else:
+            console.print("[yellow]No configuration found.[/yellow]")
         return
 
     table = AIPTable(title="🔧 AIP Configuration")
@@ -90,7 +62,6 @@ def list_config() -> None:
 @click.argument("value")
 def set_config(key: str, value: str) -> None:
     """Set a configuration value."""
-
     valid_keys = ["api_url", "api_key"]
 
     if key not in valid_keys:
@@ -114,7 +85,6 @@ def set_config(key: str, value: str) -> None:
 @click.argument("key")
 def get_config(key: str) -> None:
     """Get a configuration value."""
-
     config = load_config()
 
     if key not in config:
@@ -135,7 +105,6 @@ def get_config(key: str) -> None:
 @click.argument("key")
 def unset_config(key: str) -> None:
     """Remove a configuration value."""
-
     config = load_config()
 
     if key not in config:
@@ -152,7 +121,6 @@ def unset_config(key: str) -> None:
 @click.option("--force", is_flag=True, help="Skip confirmation prompt")
 def reset_config(force: bool) -> None:
     """Reset all configuration to defaults."""
-
     if not force:
         console.print("[yellow]This will remove all AIP configuration.[/yellow]")
         confirm = input("Are you sure? (y/N): ").strip().lower()
@@ -160,13 +128,28 @@ def reset_config(force: bool) -> None:
             console.print("Cancelled.")
             return
 
-    if CONFIG_FILE.exists():
-        CONFIG_FILE.unlink()
-        console.print(
-            "✅ Configuration reset. Run 'aip config configure' to set up again."
-        )
-    else:
+    config_data = load_config()
+    file_exists = CONFIG_FILE.exists()
+
+    if not file_exists and not config_data:
         console.print("[yellow]No configuration found to reset.[/yellow]")
+        console.print("✅ Configuration reset (nothing to remove).")
+        return
+
+    if file_exists:
+        try:
+            CONFIG_FILE.unlink()
+        except FileNotFoundError:  # pragma: no cover - defensive cleanup
+            pass
+    else:
+        # In-memory configuration (e.g., tests) needs explicit clearing
+        save_config({})
+
+    hint = command_hint("config configure", slash_command="login")
+    message = "✅ Configuration reset."
+    if hint:
+        message += f" Run '{hint}' to set up again."
+    console.print(message)
 
 
 def _configure_interactive() -> None:
@@ -232,11 +215,17 @@ def _configure_interactive() -> None:
     except Exception as e:
         console.print(Text(f"❌ Connection failed: {e}"))
         console.print("   Please check your API URL and key")
-        console.print("   You can run 'aip status' later to test again")
+        hint_status = command_hint("status", slash_command="status")
+        if hint_status:
+            console.print(f"   You can run '{hint_status}' later to test again")
 
     console.print("\n💡 You can now use AIP CLI commands!")
-    console.print("   • Run 'aip status' to check connection")
-    console.print("   • Run 'aip agents list' to see your agents")
+    hint_status = command_hint("status", slash_command="status")
+    if hint_status:
+        console.print(f"   • Run '{hint_status}' to check connection")
+    hint_agents = command_hint("agents list", slash_command="agents")
+    if hint_agents:
+        console.print(f"   • Run '{hint_agents}' to see your agents")
 
 
 @config_group.command()

glaip_sdk/cli/commands/mcps.py

@@ -582,9 +582,7 @@ def _display_mcp_details(ctx: Any, client: Any, mcp: Any) -> None:
             "status": getattr(mcp, "status", "N/A"),
             "connection_status": getattr(mcp, "connection_status", "N/A"),
         }
-        output_result(
-            ctx, result_data, title="MCP Details", panel_title=f"🔌 {mcp.name}"
-        )
+        output_result(ctx, result_data, title=f"🔌 {mcp.name}")
 
 
 @mcps_group.command()

glaip_sdk/cli/config.py

@@ -0,0 +1,42 @@
+"""Configuration management utilities.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONFIG_DIR = Path.home() / ".aip"
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+
+
+def load_config() -> dict[str, Any]:
+    """Load configuration from file."""
+    if not CONFIG_FILE.exists():
+        return {}
+
+    try:
+        with open(CONFIG_FILE) as f:
+            return yaml.safe_load(f) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def save_config(config: dict[str, Any]) -> None:
+    """Save configuration to file."""
+    CONFIG_DIR.mkdir(exist_ok=True)
+
+    with open(CONFIG_FILE, "w") as f:
+        yaml.dump(config, f, default_flow_style=False)
+
+    # Set secure file permissions
+    try:
+        os.chmod(CONFIG_FILE, 0o600)
+    except (
+        OSError
+    ):  # pragma: no cover - permission errors are expected in some environments
+        pass

glaip_sdk/cli/display.py

@@ -15,6 +15,7 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
 
+from glaip_sdk.cli.utils import command_hint
 from glaip_sdk.rich_components import AIPPanel
 
 console = Console()
@@ -102,30 +103,80 @@ def print_api_error(e: Exception) -> None:
         - Extracts status_code, error_type, and payload from APIError exceptions
         - Provides consistent error reporting across CLI commands
         - Handles both JSON and Rich output formats
+        - Special handling for validation errors with detailed field-level errors
     """
-    if hasattr(e, "__dict__"):  # Check if it's an APIError-like object
-        error_info = {
-            "error": str(e),
-            "status_code": getattr(e, "status_code", None),
-            "error_type": getattr(e, "error_type", None),
-            "details": getattr(e, "payload", None),
-        }
-
-        # Filter out None values
-        error_info = {k: v for k, v in error_info.items() if v is not None}
-
-        # For JSON view, just return the structured error
-        # (CLI commands handle the JSON formatting)
-        if hasattr(e, "status_code"):
-            console.print(f"[red]API Error: {e}[/red]")
-            if hasattr(e, "status_code"):
-                console.print(f"[yellow]Status: {e.status_code}[/yellow]")
-            if hasattr(e, "payload"):
-                console.print(f"[yellow]Details: {e.payload}[/yellow]")
+    if not hasattr(e, "__dict__"):
+        console.print(f"[red]Error: {e}[/red]")
+        return
+
+    if not hasattr(e, "status_code"):
+        console.print(f"[red]Error: {e}[/red]")
+        return
+
+    console.print(f"[red]API Error: {e}[/red]")
+    status_code = getattr(e, "status_code", None)
+    if status_code is not None:
+        console.print(f"[yellow]Status: {status_code}[/yellow]")
+
+    payload = getattr(e, "payload", _MISSING)
+    if payload is _MISSING:
+        return
+
+    if payload:
+        if not _print_structured_payload(payload):
+            console.print(f"[yellow]Details: {payload}[/yellow]")
+    else:
+        console.print(f"[yellow]Details: {payload}[/yellow]")
+
+
+def _print_structured_payload(payload: Any) -> bool:
+    """Print structured payloads with enhanced formatting. Returns True if handled."""
+    if not isinstance(payload, dict):
+        return False
+
+    if "detail" in payload and _print_validation_details(payload["detail"]):
+        return True
+
+    if "details" in payload and _print_details_field(payload["details"]):
+        return True
+
+    return False
+
+
+def _print_validation_details(detail: Any) -> bool:
+    """Render FastAPI-style validation errors."""
+    if not isinstance(detail, list) or not detail:
+        return False
+
+    console.print("[red]Validation Errors:[/red]")
+    for error in detail:
+        if isinstance(error, dict):
+            loc = " -> ".join(str(x) for x in error.get("loc", []))
+            msg = error.get("msg", "Unknown error")
+            error_type = error.get("type", "unknown")
+            location = loc if loc else "field"
+            console.print(f"  [yellow]• {location}:[/yellow] {msg}")
+            if error_type != "unknown":
+                console.print(f"    [dim]({error_type})[/dim]")
         else:
-            console.print(f"[red]Error: {e}[/red]")
+            console.print(f"  [yellow]•[/yellow] {error}")
+    return True
+
+
+def _print_details_field(details: Any) -> bool:
+    """Render custom error details from API payloads."""
+    if not details:
+        return False
+
+    console.print("[red]Error Details:[/red]")
+    if isinstance(details, str):
+        console.print(f"  [yellow]•[/yellow] {details}")
+    elif isinstance(details, list):
+        for detail in details:
+            console.print(f"  [yellow]•[/yellow] {detail}")
     else:
-        console.print(f"[red]Error: {e}[/red]")
+        console.print(f"  [yellow]•[/yellow] {details}")
+    return True
 
 
 _MISSING = object()
@@ -133,7 +184,6 @@ _MISSING = object()
 
 def build_resource_result_data(resource: Any, fields: list[str]) -> dict[str, Any]:
     """Return a normalized mapping of ``fields`` extracted from ``resource``."""
-
     result: dict[str, Any] = {}
     for field in fields:
         try:
@@ -244,14 +294,30 @@ def display_confirmation_prompt(resource_type: str, resource_name: str) -> bool:
 
 def display_agent_run_suggestions(agent: Any) -> Panel:
     """Return a panel with post-creation suggestions for an agent."""
+    agent_id = getattr(agent, "id", "")
+    agent_name = getattr(agent, "name", "")
+    run_hint_id = command_hint(
+        f'agents run {agent_id} "Your message here"',
+        slash_command=None,
+    )
+    run_hint_name = command_hint(
+        f'agents run "{agent_name}" "Your message here"',
+        slash_command=None,
+    )
+
+    cli_section = ""
+    if run_hint_id and run_hint_name:
+        cli_section = (
+            "📋 Prefer the CLI instead?\n"
+            f"   [green]{run_hint_id}[/green]\n"
+            f"   [green]{run_hint_name}[/green]\n\n"
+        )
 
     return AIPPanel(
         f"[bold blue]💡 Next Steps:[/bold blue]\n\n"
-        f"🚀 Start chatting with [bold]{agent.name}[/bold] right here:\n"
+        f"🚀 Start chatting with [bold]{agent_name}[/bold] right here:\n"
         f"   Type your message below and press Enter to run it immediately.\n\n"
-        f"📋 Prefer the CLI instead?\n"
-        f'   [green]aip agents run {agent.id} "Your message here"[/green]\n'
-        f'   [green]aip agents run "{agent.name}" "Your message here"[/green]\n\n'
+        f"{cli_section}"
         f"🔧 Available options:\n"
         f"   [dim]--chat-history[/dim]  Include previous conversation\n"
         f"   [dim]--file[/dim]          Attach files\n"