glaip-sdk 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

glaip_sdk/_version.py

@@ -14,6 +14,14 @@ except Exception:  # pragma: no cover - extremely unlikely
     PackageNotFoundError = Exception  # type: ignore
 
     def version(_: str) -> str:  # type: ignore
+        """Fallback version function when importlib.metadata is unavailable.
+
+        Args:
+            _: Package name (ignored in fallback).
+
+        Returns:
+            Default dev version string.
+        """
         return "0.0.0.dev0"
 
 

glaip_sdk/branding.py

@@ -90,6 +90,14 @@ GDP Labs AI Agents Package
     # ---- small helpers --------------------------------------------------------
     @staticmethod
     def _auto_version(package_name: str | None) -> str:
+        """Auto-detect version from environment, package metadata, or fallback.
+
+        Args:
+            package_name: Optional package name to read version from installed metadata.
+
+        Returns:
+            Version string from AIP_VERSION env var, package metadata, or SDK_VERSION fallback.
+        """
         # Priority: env → package metadata → fallback
         env_version = os.getenv("AIP_VERSION")
         if env_version:
@@ -103,6 +111,11 @@ GDP Labs AI Agents Package
 
     @staticmethod
     def _make_console() -> Console:
+        """Create a Rich Console instance respecting NO_COLOR environment variables.
+
+        Returns:
+            Console instance with color system configured based on environment.
+        """
         # Respect NO_COLOR/AIP_NO_COLOR environment variables
         no_color_env = os.getenv("NO_COLOR") is not None or os.getenv("AIP_NO_COLOR") is not None
         if no_color_env:

glaip_sdk/cli/commands/agents.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import json
 import os
 from collections.abc import Mapping
+from copy import deepcopy
 from pathlib import Path
 from typing import Any
 
@@ -18,6 +19,7 @@ from rich.console import Console
 from glaip_sdk.branding import (
     ACCENT_STYLE,
     ERROR_STYLE,
+    HINT_PREFIX_STYLE,
     INFO,
     SUCCESS,
     SUCCESS_STYLE,
@@ -33,6 +35,7 @@ from glaip_sdk.cli.agent_config import (
     sanitize_agent_config_for_cli as sanitize_agent_config,
 )
 from glaip_sdk.cli.context import get_ctx_value, output_flags
+from glaip_sdk.cli.constants import DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
 from glaip_sdk.cli.display import (
     build_resource_result_data,
     display_agent_run_suggestions,
@@ -61,9 +64,12 @@ from glaip_sdk.cli.utils import (
     build_renderer,
     coerce_to_row,
     get_client,
+    handle_resource_export,
+    in_slash_mode,
     output_list,
     output_result,
     spinner_context,
+    with_client_and_spinner,
 )
 from glaip_sdk.cli.validators import (
     validate_agent_instruction_cli as validate_agent_instruction,
@@ -74,7 +80,7 @@ from glaip_sdk.cli.validators import (
 from glaip_sdk.cli.validators import (
     validate_timeout_cli as validate_timeout,
 )
-from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT, DEFAULT_MODEL
+from glaip_sdk.config.constants import AGENT_CONFIG_FIELDS, DEFAULT_AGENT_RUN_TIMEOUT, DEFAULT_MODEL
 from glaip_sdk.exceptions import AgentTimeoutError
 from glaip_sdk.icons import ICON_AGENT
 from glaip_sdk.utils import format_datetime, is_uuid
@@ -88,6 +94,8 @@ console = Console()
 # Error message constants
 AGENT_NOT_FOUND_ERROR = "Agent not found"
 
+# Instruction preview controls
+
 
 def _safe_agent_attribute(agent: Any, name: str) -> Any:
     """Return attribute value for ``name`` while filtering Mock sentinels."""
@@ -140,10 +148,7 @@ def _build_fallback_agent_mapping(agent: Any) -> dict[str, Any]:
         "description",
         "model",
         "agent_config",
-        "tools",
-        "agents",
-        "mcps",
-        "timeout",
+        *[field for field in AGENT_CONFIG_FIELDS if field not in ("name", "instruction", "model")],
         "tool_configs",
     )
 
@@ -307,12 +312,92 @@ def _format_fallback_agent_data(client: Any, agent: Any) -> dict:
     return result_data
 
 
-def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
+def _clamp_instruction_preview_limit(limit: int | None) -> int:
+    """Normalise preview limit; 0 disables trimming."""
+    default = DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
+    if limit is None:  # pragma: no cover
+        return default
+    try:
+        limit_value = int(limit)
+    except (TypeError, ValueError):  # pragma: no cover - defensive parsing
+        return default
+
+    if limit_value <= 0:
+        return 0
+
+    return limit_value
+
+
+def _build_instruction_preview(value: Any, limit: int) -> tuple[Any, bool]:
+    """Return a trimmed preview for long instruction strings."""
+    if not isinstance(value, str) or limit <= 0:  # pragma: no cover
+        return value, False
+
+    if len(value) <= limit:
+        return value, False
+
+    trimmed_value = value[:limit].rstrip()
+    preview = f"{trimmed_value}\n\n... (preview trimmed)"
+    return preview, True
+
+
+def _prepare_agent_details_payload(
+    data: dict[str, Any],
+    *,
+    instruction_preview_limit: int,
+) -> tuple[dict[str, Any], bool]:
+    """Return payload ready for rendering plus trim indicator."""
+    payload = deepcopy(data)
+    trimmed = False
+    if instruction_preview_limit > 0:
+        preview, trimmed = _build_instruction_preview(payload.get("instruction"), instruction_preview_limit)
+        if trimmed:
+            payload["instruction"] = preview
+    return payload, trimmed
+
+
+def _show_instruction_trim_hint(
+    ctx: Any,
+    *,
+    trimmed: bool,
+    preview_limit: int,
+) -> None:
+    """Render hint describing how to expand or collapse the instruction preview."""
+    if not trimmed or preview_limit <= 0:
+        return
+
+    view = get_ctx_value(ctx, "view", "rich") if ctx is not None else "rich"
+    if view != "rich":  # pragma: no cover - non-rich view handling
+        return
+
+    suffix = f"[dim](preview: {preview_limit:,} chars)[/]"
+    if in_slash_mode(ctx):
+        console.print(
+            f"[{HINT_PREFIX_STYLE}]Tip:[/] Use '/details' again to toggle between trimmed and full prompts {suffix}"
+        )
+        return
+
+    console.print(  # pragma: no cover - fallback hint rendering
+        f"[{HINT_PREFIX_STYLE}]Tip:[/] Run 'aip agents get <agent> --instruction-preview <n>' "
+        f"to control prompt preview length {suffix}"
+    )
+
+
+def _display_agent_details(
+    ctx: Any,
+    client: Any,
+    agent: Any,
+    *,
+    instruction_preview_limit: int | None = None,
+) -> None:
     """Display full agent details using raw API data to preserve ALL fields."""
     if agent is None:
         handle_rich_output(ctx, markup_text(f"[{ERROR_STYLE}]❌ No agent provided[/]"))
         return
 
+    preview_limit = _clamp_instruction_preview_limit(instruction_preview_limit)
+    trimmed_instruction = False
+
     # Try to fetch and format raw agent data first
     with spinner_context(
         ctx,
@@ -324,9 +409,13 @@ def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
     if formatted_data:
         # Use raw API data - this preserves ALL fields including account_id
         panel_title = f"{ICON_AGENT} {formatted_data.get('name', 'Unknown')}"
+        payload, trimmed_instruction = _prepare_agent_details_payload(
+            formatted_data,
+            instruction_preview_limit=preview_limit,
+        )
         output_result(
             ctx,
-            formatted_data,
+            payload,
             title=panel_title,
         )
     else:
@@ -344,12 +433,22 @@ def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
             result_data = _format_fallback_agent_data(client, agent)
 
         # Display using output_result
+        payload, trimmed_instruction = _prepare_agent_details_payload(
+            result_data,
+            instruction_preview_limit=preview_limit,
+        )
         output_result(
             ctx,
-            result_data,
+            payload,
             title="Agent Details",
         )
 
+    _show_instruction_trim_hint(
+        ctx,
+        trimmed=trimmed_instruction,
+        preview_limit=preview_limit,
+    )
+
 
 @click.group(name="agents", no_args_is_help=True)
 def agents_group() -> None:
@@ -357,7 +456,6 @@ def agents_group() -> None:
     pass
 
 
-# pylint: disable=duplicate-code
 def _resolve_agent(
     ctx: Any,
     client: Any,
@@ -365,26 +463,38 @@ def _resolve_agent(
     select: int | None = None,
     interface_preference: str = "fuzzy",
 ) -> Any | None:
-    """Resolve agent reference (ID or name) with ambiguity handling.
+    """Resolve an agent by ID or name, supporting fuzzy and questionary interfaces.
+
+    This function provides agent-specific resolution with flexible UI options.
+    It wraps resolve_resource_reference with agent-specific configuration, allowing
+    users to choose between fuzzy search and traditional questionary selection.
 
     Args:
-        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.
+        ctx: Click context for CLI command execution.
+        client: AIP SDK client instance.
+        ref: Agent identifier (UUID or name string).
+        select: Pre-selected index for non-interactive resolution (1-based).
+        interface_preference: UI preference - "fuzzy" for search or "questionary" for list.
 
     Returns:
-        Resolved agent object or None if not found.
+        Agent object when found, None when resolution fails.
     """
+    # Configure agent-specific resolution parameters
+    resolution_config = {
+        "resource_type": "agent",
+        "get_by_id": client.agents.get_agent_by_id,
+        "find_by_name": client.agents.find_agents,
+        "label": "Agent",
+    }
+    # Use agent-specific resolution with flexible interface preference
     return resolve_resource_reference(
         ctx,
         client,
         ref,
-        "agent",
-        client.agents.get_agent_by_id,
-        client.agents.find_agents,
-        "Agent",
+        resolution_config["resource_type"],
+        resolution_config["get_by_id"],
+        resolution_config["find_by_name"],
+        resolution_config["label"],
         select=select,
         interface_preference=interface_preference,
     )
@@ -414,19 +524,20 @@ def list_agents(
 ) -> None:
     """List agents with optional filtering."""
     try:
-        client = get_client(ctx)
-        with spinner_context(
+        with with_client_and_spinner(
             ctx,
             "[bold blue]Fetching agents…[/bold blue]",
             console_override=console,
-        ):
-            agents = client.agents.list_agents(
-                agent_type=agent_type,
-                framework=framework,
-                name=name,
-                version=version,
-                sync_langflow_agents=sync_langflow,
-            )
+        ) as client:
+            # Query agents with specified filters
+            filter_params = {
+                "agent_type": agent_type,
+                "framework": framework,
+                "name": name,
+                "version": version,
+                "sync_langflow_agents": sync_langflow,
+            }
+            agents = client.agents.list_agents(**filter_params)
 
         # Define table columns: (data_key, header, style, width)
         columns = [
@@ -439,6 +550,14 @@ def list_agents(
 
         # Transform function for safe attribute access
         def transform_agent(agent: Any) -> dict[str, Any]:
+            """Transform an agent object to a display row dictionary.
+
+            Args:
+                agent: Agent object to transform.
+
+            Returns:
+                Dictionary with id, name, type, framework, and version fields.
+            """
             row = coerce_to_row(agent, ["id", "name", "type", "framework", "version"])
             # Ensure id is always a string
             row["id"] = str(row["id"])
@@ -488,9 +607,22 @@ def list_agents(
     type=click.Path(dir_okay=False, writable=True),
     help="Export complete agent configuration to file (format auto-detected from .json/.yaml extension)",
 )
+@click.option(
+    "--instruction-preview",
+    type=int,
+    default=0,
+    show_default=True,
+    help="Instruction preview length when printing instructions (0 shows full prompt).",
+)
 @output_flags()
 @click.pass_context
-def get(ctx: Any, agent_ref: str, select: int | None, export: str | None) -> None:
+def get(
+    ctx: Any,
+    agent_ref: str,
+    select: int | None,
+    export: str | None,
+    instruction_preview: int,
+) -> None:
     r"""Get agent details.
 
     \b
@@ -500,30 +632,39 @@ def get(ctx: Any, agent_ref: str, select: int | None, export: str | None) -> Non
         aip agents get my-agent --export agent.yaml    # Exports complete configuration as YAML
     """
     try:
-        client = get_client(ctx)
+        # Initialize API client for agent retrieval
+        api_client = get_client(ctx)
 
-        # Resolve agent with ambiguity handling - use questionary interface for traditional UX
-        agent = _resolve_agent(ctx, client, agent_ref, select, interface_preference="questionary")
+        # Resolve agent reference using questionary interface for better UX
+        agent = _resolve_agent(ctx, api_client, agent_ref, select, interface_preference="questionary")
 
-        # Handle export option
-        if export:
-            from glaip_sdk.cli.utils import handle_resource_export
+        if not agent:
+            raise click.ClickException(f"Agent '{agent_ref}' not found")
 
+        # Handle export option if requested
+        if export:
             handle_resource_export(
                 ctx,
                 agent,
                 Path(export),
                 resource_type="agent",
-                get_by_id_func=client.agents.get_agent_by_id,
+                get_by_id_func=api_client.agents.get_agent_by_id,
                 console_override=console,
             )
 
         # Display full agent details using the standardized helper
-        _display_agent_details(ctx, client, agent)
+        _display_agent_details(
+            ctx,
+            api_client,
+            agent,
+            instruction_preview_limit=instruction_preview,
+        )
 
         # Show run suggestions via centralized display helper
         handle_rich_output(ctx, display_agent_run_suggestions(agent))
 
+    except click.ClickException:
+        raise
     except Exception as e:
         raise click.ClickException(str(e)) from e
 

glaip_sdk/cli/commands/mcps.py

@@ -43,10 +43,13 @@ from glaip_sdk.cli.resolution import resolve_resource_reference
 from glaip_sdk.cli.rich_helpers import print_markup
 from glaip_sdk.cli.utils import (
     coerce_to_row,
+    fetch_resource_for_export,
+    format_datetime_fields,
     get_client,
     output_list,
     output_result,
     spinner_context,
+    with_client_and_spinner,
 )
 from glaip_sdk.config.constants import (
     DEFAULT_MCP_TYPE,
@@ -298,28 +301,37 @@ def mcps_group() -> None:
     pass
 
 
-def _resolve_mcp(ctx: Any, client: Any, ref: str, select: int | None = None) -> Any | None:  # pylint: disable=duplicate-code
-    """Resolve MCP reference (ID or name) with ambiguity handling.
+def _resolve_mcp(ctx: Any, client: Any, ref: str, select: int | None = None) -> Any | None:
+    """Resolve an MCP server by ID or name, with interactive selection support.
+
+    This function provides MCP-specific resolution logic. It delegates to
+    resolve_resource_reference for MCP-specific resolution, supporting UUID
+    lookups and name-based fuzzy matching.
 
     Args:
-        ctx: Click context object
-        client: API client instance
-        ref: MCP reference (ID or name)
-        select: Index to select when multiple matches found
+        ctx: Click context for command execution.
+        client: API client for backend operations.
+        ref: MCP identifier (UUID or name string).
+        select: Optional selection index when multiple MCPs match (1-based).
 
     Returns:
-        MCP object if found, None otherwise
+        MCP instance if resolution succeeds, None if not found.
 
     Raises:
-        ClickException: If MCP not found or selection invalid
+        click.ClickException: When resolution fails or selection is invalid.
     """
+    # Configure MCP-specific resolution functions
+    mcp_client = client.mcps
+    get_by_id_func = mcp_client.get_mcp_by_id
+    find_by_name_func = mcp_client.find_mcps
+    # Use MCP-specific resolution with standard fuzzy matching
     return resolve_resource_reference(
         ctx,
         client,
         ref,
         "mcp",
-        client.mcps.get_mcp_by_id,
-        client.mcps.find_mcps,
+        get_by_id_func,
+        find_by_name_func,
         "MCP",
         select=select,
     )
@@ -512,12 +524,11 @@ def list_mcps(ctx: Any) -> None:
         ClickException: If API request fails
     """
     try:
-        client = get_client(ctx)
-        with spinner_context(
+        with with_client_and_spinner(
             ctx,
             "[bold blue]Fetching MCPs…[/bold blue]",
             console_override=console,
-        ):
+        ) as client:
             mcps = client.mcps.list_mcps()
 
         # Define table columns: (data_key, header, style, width)
@@ -529,6 +540,14 @@ def list_mcps(ctx: Any) -> None:
 
         # Transform function for safe dictionary access
         def transform_mcp(mcp: Any) -> dict[str, Any]:
+            """Transform an MCP object to a display row dictionary.
+
+            Args:
+                mcp: MCP object to transform.
+
+            Returns:
+                Dictionary with id, name, and config fields.
+            """
             row = coerce_to_row(mcp, ["id", "name", "config"])
             # Ensure id is always a string
             row["id"] = str(row["id"])
@@ -604,8 +623,10 @@ def create(
             aip mcps create --import mcp-export.json --name new-name --transport sse
     """
     try:
-        client = get_client(ctx)
+        # Get API client instance for MCP operations
+        api_client = get_client(ctx)
 
+        # Process import file if specified, otherwise use None
         import_payload = _load_import_ready_payload(import_file) if import_file is not None else None
 
         merged_payload, missing_fields = _merge_import_payload(
@@ -649,7 +670,7 @@ def create(
             if mcp_metadata is not None:
                 create_kwargs["mcp_metadata"] = mcp_metadata
 
-            mcp = client.mcps.create_mcp(**create_kwargs)
+            mcp = api_client.mcps.create_mcp(**create_kwargs)
 
         # Handle JSON output
         handle_json_output(ctx, mcp.model_dump())
@@ -696,7 +717,6 @@ def _handle_mcp_export(
     detected_format = detect_export_format(export_path)
 
     # Always export comprehensive data - re-fetch with full details
-    from glaip_sdk.cli.utils import fetch_resource_for_export
 
     mcp = fetch_resource_for_export(
         ctx,
@@ -775,8 +795,6 @@ def _display_mcp_details(ctx: Any, client: Any, mcp: Any) -> None:
 
     if raw_mcp_data:
         # Use raw API data - this preserves ALL fields
-        from glaip_sdk.cli.utils import format_datetime_fields
-
         formatted_data = format_datetime_fields(raw_mcp_data)
 
         output_result(
@@ -897,6 +915,14 @@ def list_tools(ctx: Any, mcp_ref: str) -> None:
 
         # Transform function for safe dictionary access
         def transform_tool(tool: dict[str, Any]) -> dict[str, Any]:
+            """Transform a tool dictionary to a display row dictionary.
+
+            Args:
+                tool: Tool dictionary to transform.
+
+            Returns:
+                Dictionary with name and description fields.
+            """
             return {
                 "name": tool.get("name", "N/A"),
                 "description": tool.get("description", "N/A")[:47] + "..."

glaip_sdk/cli/commands/models.py

@@ -12,9 +12,8 @@ from rich.console import Console
 from glaip_sdk.branding import ACCENT_STYLE, INFO, SUCCESS
 from glaip_sdk.cli.context import output_flags
 from glaip_sdk.cli.utils import (
-    get_client,
     output_list,
-    spinner_context,
+    with_client_and_spinner,
 )
 
 console = Console()
@@ -32,12 +31,11 @@ def models_group() -> None:
 def list_models(ctx: Any) -> None:
     """List available language models."""
     try:
-        client = get_client(ctx)
-        with spinner_context(
+        with with_client_and_spinner(
             ctx,
             "[bold blue]Fetching language models…[/bold blue]",
             console_override=console,
-        ):
+        ) as client:
             models = client.list_language_models()
 
         # Define table columns: (data_key, header, style, width)
@@ -50,6 +48,14 @@ def list_models(ctx: Any) -> None:
 
         # Transform function for safe dictionary access
         def transform_model(model: dict[str, Any]) -> dict[str, Any]:
+            """Transform a model dictionary to a display row dictionary.
+
+            Args:
+                model: Model dictionary to transform.
+
+            Returns:
+                Dictionary with id, provider, name, and base_url fields.
+            """
             return {
                 "id": str(model.get("id", "N/A")),
                 "provider": model.get("provider", "N/A"),