glaip-sdk 0.0.14__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

@@ -23,6 +23,7 @@ from glaip_sdk.cli.agent_config import (
 from glaip_sdk.cli.agent_config import (
     sanitize_agent_config_for_cli as sanitize_agent_config,
 )
+from glaip_sdk.cli.context import detect_export_format, get_ctx_value, output_flags
 from glaip_sdk.cli.display import (
     build_resource_result_data,
     display_agent_run_suggestions,
@@ -48,10 +49,7 @@ from glaip_sdk.cli.utils import (
     _fuzzy_pick_for_resources,
     build_renderer,
     coerce_to_row,
-    detect_export_format,
     get_client,
-    get_ctx_value,
-    output_flags,
     output_list,
     output_result,
     spinner_context,
@@ -80,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:
@@ -93,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):
@@ -103,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
@@ -116,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:
@@ -126,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",
@@ -138,6 +131,7 @@ def _build_fallback_agent_mapping(agent: Any) -> dict[str, Any]:
         "agents",
         "mcps",
         "timeout",
+        "tool_configs",
     )
 
     fallback: dict[str, Any] = {}
@@ -151,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
@@ -258,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)
@@ -299,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
@@ -320,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')}",
         )
 
 
@@ -340,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,
@@ -880,7 +878,6 @@ def _add_import_file_attributes(
         "type",
         "framework",
         "version",
-        "tool_configs",
         "mcps",
         "a2a_profile",
     }
@@ -1052,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,
@@ -1059,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)
@@ -1074,6 +1073,7 @@ def _handle_update_import_file(
         "instruction": instruction,
         "tools": tools or (),
         "agents": agents or (),
+        "mcps": mcps or (),
         "timeout": timeout,
     }
 
@@ -1085,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")),
     )
 
@@ -1094,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."""
@@ -1106,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
@@ -1143,8 +1147,6 @@ def _handle_update_import_config(
         "type",
         "framework",
         "version",
-        "tool_configs",
-        "mcps",
         "a2a_profile",
     }
     for key, value in merged_data.items():
@@ -1158,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",
@@ -1174,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:
@@ -1194,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

@@ -13,6 +13,7 @@ import click
 from rich.console import Console
 from rich.text import Text
 
+from glaip_sdk.cli.context import detect_export_format, get_ctx_value, output_flags
 from glaip_sdk.cli.display import (
     display_api_error,
     display_confirmation_prompt,
@@ -34,10 +35,7 @@ from glaip_sdk.cli.parsers.json_input import parse_json_input
 from glaip_sdk.cli.resolution import resolve_resource_reference
 from glaip_sdk.cli.utils import (
     coerce_to_row,
-    detect_export_format,
     get_client,
-    get_ctx_value,
-    output_flags,
     output_list,
     output_result,
     spinner_context,
@@ -584,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/commands/models.py

@@ -9,9 +9,9 @@ from typing import Any
 import click
 from rich.console import Console
 
+from glaip_sdk.cli.context import output_flags
 from glaip_sdk.cli.utils import (
     get_client,
-    output_flags,
     output_list,
     spinner_context,
 )

glaip_sdk/cli/commands/tools.py

@@ -13,6 +13,7 @@ import click
 from rich.console import Console
 from rich.text import Text
 
+from glaip_sdk.cli.context import detect_export_format, get_ctx_value, output_flags
 from glaip_sdk.cli.display import (
     display_api_error,
     display_confirmation_prompt,
@@ -34,10 +35,7 @@ from glaip_sdk.cli.io import (
 from glaip_sdk.cli.resolution import resolve_resource_reference
 from glaip_sdk.cli.utils import (
     coerce_to_row,
-    detect_export_format,
     get_client,
-    get_ctx_value,
-    output_flags,
     output_list,
     output_result,
     spinner_context,

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/context.py

@@ -0,0 +1,142 @@
+"""Context-related helpers for the glaip CLI.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import click
+
+__all__ = [
+    "get_ctx_value",
+    "_get_view",
+    "_set_view",
+    "_set_json",
+    "output_flags",
+    "detect_export_format",
+]
+
+
+def get_ctx_value(ctx: Any, key: str, default: Any = None) -> Any:
+    """Safely resolve a value from a click context object.
+
+    Args:
+        ctx: Click context object to extract value from
+        key: Key to retrieve from the context
+        default: Default value if key is not found
+
+    Returns:
+        The value associated with the key, or the default if not found
+    """
+    if ctx is None:
+        return default
+
+    obj = getattr(ctx, "obj", None)
+    if obj is None:
+        return default
+
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+
+    getter = getattr(obj, "get", None)
+    if callable(getter):
+        try:
+            return getter(key, default)
+        except TypeError:
+            return default
+
+    return getattr(obj, key, default) if hasattr(obj, key) else default
+
+
+def _get_view(ctx: Any) -> str:
+    """Resolve the active view preference from context.
+
+    Args:
+        ctx: Click context object containing view preferences
+
+    Returns:
+        The view format string (rich, plain, json, md), defaults to 'rich'
+    """
+    view = get_ctx_value(ctx, "view")
+    if view:
+        return view
+
+    fallback = get_ctx_value(ctx, "format")
+    return fallback or "rich"
+
+
+def _set_view(ctx: Any, _param: Any, value: str) -> None:
+    """Click callback to persist the `--view/--output` option.
+
+    Args:
+        ctx: Click context object to store the view preference
+        _param: Click parameter object (unused)
+        value: The view format string to store
+    """
+    if not value:
+        return
+    ctx.ensure_object(dict)
+    ctx.obj["view"] = value
+
+
+def _set_json(ctx: Any, _param: Any, value: bool) -> None:
+    """Click callback for the `--json` shorthand flag.
+
+    Args:
+        ctx: Click context object to store the view preference
+        _param: Click parameter object (unused)
+        value: Boolean flag indicating json mode
+    """
+    if not value:
+        return
+    ctx.ensure_object(dict)
+    ctx.obj["view"] = "json"
+
+
+def output_flags() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator to add shared output flags (`--view`, `--json`) to commands.
+
+    Returns:
+        A decorator function that adds output format options to click commands
+    """
+
+    def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
+        f = click.option(
+            "--json",
+            "json_mode",
+            is_flag=True,
+            expose_value=False,
+            help="Shortcut for --view json",
+            callback=_set_json,
+        )(f)
+        f = click.option(
+            "-o",
+            "--output",
+            "--view",
+            "view_opt",
+            type=click.Choice(["rich", "plain", "json", "md"]),
+            expose_value=False,
+            help="Output format",
+            callback=_set_view,
+        )(f)
+        return f
+
+    return decorator
+
+
+def detect_export_format(file_path: str | Path) -> str:
+    """Detect the export format from the file extension.
+
+    Args:
+        file_path: Path to the file to analyze
+
+    Returns:
+        The format string ('yaml' or 'json') based on file extension
+    """
+    path = Path(file_path)
+    return "yaml" if path.suffix.lower() in {".yaml", ".yml"} else "json"