glaip-sdk 0.2.1__py3-none-any.whl → 0.2.2__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,6 +64,7 @@ from glaip_sdk.cli.utils import (
     build_renderer,
     coerce_to_row,
     get_client,
+    in_slash_mode,
     output_list,
     output_result,
     spinner_context,
@@ -88,6 +92,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."""
@@ -307,12 +313,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 +410,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 +434,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:
@@ -439,6 +539,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 +596,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
@@ -519,7 +640,12 @@ def get(ctx: Any, agent_ref: str, select: int | None, export: str | None) -> Non
             )
 
         # Display full agent details using the standardized helper
-        _display_agent_details(ctx, client, agent)
+        _display_agent_details(
+            ctx,
+            client,
+            agent,
+            instruction_preview_limit=instruction_preview,
+        )
 
         # Show run suggestions via centralized display helper
         handle_rich_output(ctx, display_agent_run_suggestions(agent))

glaip_sdk/cli/commands/mcps.py

@@ -529,6 +529,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"])
@@ -897,6 +905,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

@@ -50,6 +50,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"),

glaip_sdk/cli/commands/tools.py

@@ -211,6 +211,14 @@ def list_tools(ctx: Any, tool_type: str | None) -> None:
 
         # Transform function for safe dictionary access
         def transform_tool(tool: Any) -> dict[str, Any]:
+            """Transform a tool object to a display row dictionary.
+
+            Args:
+                tool: Tool object to transform.
+
+            Returns:
+                Dictionary with id, name, and framework fields.
+            """
             row = coerce_to_row(tool, ["id", "name", "framework"])
             # Ensure id is always a string
             row["id"] = str(row["id"])

glaip_sdk/cli/commands/transcripts.py

@@ -156,6 +156,14 @@ def _launch_transcript_viewer(
     viewer_ctx = _build_viewer_context(entry, meta, events)
 
     def _export(destination: Path) -> Path:
+        """Export cached transcript to destination.
+
+        Args:
+            destination: Path to export transcript to.
+
+        Returns:
+            Path to exported transcript file.
+        """
         return export_cached_transcript(destination=destination, run_id=entry.run_id)
 
     run_viewer_session(target_console, viewer_ctx, _export, initial_view=initial_view)

glaip_sdk/cli/constants.py

@@ -0,0 +1,35 @@
+"""CLI-specific constants for glaip-sdk.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+# Minimum length that forces multiline YAML strings to be rendered using the literal
+# block style. This prevents long prompts and instructions from being inlined.
+LITERAL_STRING_THRESHOLD = 200
+
+# Masking configuration
+MASKING_ENABLED = True
+MASK_SENSITIVE_FIELDS = {
+    "api_key",
+    "apikey",
+    "token",
+    "access_token",
+    "secret",
+    "client_secret",
+    "password",
+    "private_key",
+    "bearer",
+}
+
+# Table + pager behaviour
+TABLE_SORT_ENABLED = True
+PAGER_MODE = "auto"  # valid values: "auto", "on", "off"
+PAGER_WRAP_LINES = False
+PAGER_HEADER_ENABLED = True
+
+# Update notification toggle
+UPDATE_CHECK_ENABLED = True
+
+# Agent instruction preview defaults
+DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT = 800

glaip_sdk/cli/context.py

@@ -106,6 +106,14 @@ def output_flags() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """
 
     def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply output flags to a click command.
+
+        Args:
+            f: Click command function to decorate.
+
+        Returns:
+            Decorated command function.
+        """
         f = click.option(
             "--json",
             "json_mode",

glaip_sdk/cli/display.py

@@ -17,7 +17,7 @@ from rich.text import Text
 
 from glaip_sdk.branding import ERROR_STYLE, SUCCESS, SUCCESS_STYLE, WARNING_STYLE
 from glaip_sdk.cli.rich_helpers import markup_text
-from glaip_sdk.cli.utils import command_hint, format_command_hint
+from glaip_sdk.cli.utils import command_hint, format_command_hint, in_slash_mode
 from glaip_sdk.icons import ICON_AGENT, ICON_TOOL
 from glaip_sdk.rich_components import AIPPanel
 
@@ -304,6 +304,7 @@ 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", "")
+    slash_mode = in_slash_mode()
     run_hint_id = command_hint(
         f'agents run {agent_id} "Your message here"',
         slash_command=None,
@@ -313,27 +314,41 @@ def display_agent_run_suggestions(agent: Any) -> Panel:
         slash_command=None,
     )
 
-    cli_section = ""
-    if run_hint_id and run_hint_name:
-        cli_section = (
-            "📋 Prefer the CLI instead?\n"
-            f"   {format_command_hint(run_hint_id) or run_hint_id}\n"
-            f"   {format_command_hint(run_hint_name) or run_hint_name}\n\n"
+    content_parts: list[str] = ["[bold blue]💡 Next Steps:[/bold blue]\n\n"]
+
+    if slash_mode:
+        slash_shortcuts = "\n".join(
+            f"   {format_command_hint(command, description) or command}"
+            for command, description in (
+                ("/details", "Show configuration (toggle preview)"),
+                ("/help", "Show command palette menu"),
+                ("/exit", "Return to the palette"),
+            )
+        )
+        content_parts.append(
+            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"{ICON_TOOL} Slash shortcuts:\n"
+            f"{slash_shortcuts}"
+        )
+    else:
+        cli_hint_lines = [format_command_hint(hint) or hint for hint in (run_hint_id, run_hint_name) if hint]
+        if cli_hint_lines:
+            joined_hints = "\n".join(f"   {hint}" for hint in cli_hint_lines)
+            content_parts.append(f"🚀 Run this agent from the CLI:\n{joined_hints}\n\n")
+        content_parts.append(
+            f"{ICON_TOOL} Available options:\n"
+            f"   [dim]--chat-history[/dim]  Include previous conversation\n"
+            f"   [dim]--file[/dim]          Attach files\n"
+            f"   [dim]--input[/dim]         Alternative input method\n"
+            f"   [dim]--timeout[/dim]       Set execution timeout\n"
+            f"   [dim]--save[/dim]          Save transcript to file\n"
+            f"   [dim]--verbose[/dim]       Show detailed execution\n\n"
+            f"💡 [dim]Input text can be positional OR use --input flag (both work!)[/dim]"
         )
 
     return AIPPanel(
-        f"[bold blue]💡 Next Steps:[/bold blue]\n\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"{cli_section}"
-        f"{ICON_TOOL} Available options:\n"
-        f"   [dim]--chat-history[/dim]  Include previous conversation\n"
-        f"   [dim]--file[/dim]          Attach files\n"
-        f"   [dim]--input[/dim]         Alternative input method\n"
-        f"   [dim]--timeout[/dim]       Set execution timeout\n"
-        f"   [dim]--save[/dim]          Save transcript to file\n"
-        f"   [dim]--verbose[/dim]       Show detailed execution\n\n"
-        f"💡 [dim]Input text can be positional OR use --input flag (both work!)[/dim]",
+        "".join(content_parts),
         title=f"{ICON_AGENT} Ready to Run Agent",
         border_style="blue",
         padding=(0, 1),

glaip_sdk/cli/main.py

@@ -387,6 +387,7 @@ def version() -> None:
 )
 def update(check_only: bool, force: bool) -> None:
     """Update AIP SDK to the latest version from PyPI."""
+    slash_mode = in_slash_mode()
     try:
         console = Console()
 
@@ -400,11 +401,15 @@ def update(check_only: bool, force: bool) -> None:
             )
             return
 
+        update_hint = ""
+        if not slash_mode:
+            update_hint = "\n💡 Use --check-only to just check for updates"
+
         console.print(
             AIPPanel(
                 "[bold blue]🔄 Updating AIP SDK...[/bold blue]\n\n"
-                "📦 This will update the package from PyPI\n"
-                "💡 Use --check-only to just check for updates",
+                "📦 This will update the package from PyPI"
+                f"{update_hint}",
                 title="Update Process",
                 border_style="blue",
                 padding=(0, 1),
@@ -422,11 +427,15 @@ def update(check_only: bool, force: bool) -> None:
                 cmd.insert(5, "--force-reinstall")
             subprocess.run(cmd, capture_output=True, text=True, check=True)
 
+            verify_hint = ""
+            if not slash_mode:
+                verify_hint = "\n💡 Restart your terminal or run 'aip --version' to verify"
+
             console.print(
                 AIPPanel(
                     f"[{SUCCESS_STYLE}]✅ Update successful![/]\n\n"
-                    "🔄 AIP SDK has been updated to the latest version\n"
-                    "💡 Restart your terminal or run 'aip --version' to verify",
+                    "🔄 AIP SDK has been updated to the latest version"
+                    f"{verify_hint}",
                     title="🎉 Update Complete",
                     border_style=SUCCESS,
                     padding=(0, 1),

glaip_sdk/cli/masking.py

@@ -6,9 +6,10 @@ Authors:
 
 from __future__ import annotations
 
-import os
 from typing import Any
 
+from glaip_sdk.cli.constants import MASKING_ENABLED, MASK_SENSITIVE_FIELDS
+
 __all__ = [
     "mask_payload",
     "mask_rows",
@@ -18,18 +19,6 @@ __all__ = [
     "_resolve_mask_fields",
 ]
 
-_DEFAULT_MASK_FIELDS = {
-    "api_key",
-    "apikey",
-    "token",
-    "access_token",
-    "secret",
-    "client_secret",
-    "password",
-    "private_key",
-    "bearer",
-}
-
 
 def _mask_value(raw: Any) -> str:
     """Return a masked representation of the provided value.
@@ -90,22 +79,10 @@ def _maybe_mask_row(row: dict[str, Any], mask_fields: set[str]) -> dict[str, Any
 
 
 def _resolve_mask_fields() -> set[str]:
-    """Resolve the set of sensitive fields to mask based on environment.
-
-    Returns:
-        set[str]: Set of field names to mask. Empty set if masking is disabled
-                 via AIP_MASK_OFF environment variable, custom fields from
-                 AIP_MASK_FIELDS, or default fields if neither is set.
-    """
-    if os.getenv("AIP_MASK_OFF", "0") in {"1", "true", "on", "yes"}:
+    """Return the configured set of fields that should be masked."""
+    if not MASKING_ENABLED:
         return set()
-
-    env_fields = (os.getenv("AIP_MASK_FIELDS") or "").strip()
-    if env_fields:
-        parts = [part.strip().lower() for part in env_fields.split(",") if part.strip()]
-        return set(parts)
-
-    return set(_DEFAULT_MASK_FIELDS)
+    return set(MASK_SENSITIVE_FIELDS)
 
 
 def mask_payload(payload: Any) -> Any:
@@ -115,9 +92,7 @@ def mask_payload(payload: Any) -> Any:
         payload: Any data structure (dict, list, or primitive) to mask.
 
     Returns:
-        Any: The payload with sensitive fields masked based on environment
-             configuration. Returns original payload if masking is disabled
-             or if an error occurs during masking.
+        Any: The payload with sensitive fields masked based on configuration.
     """
     mask_fields = _resolve_mask_fields()
     if not mask_fields:
@@ -136,8 +111,8 @@ def mask_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
 
     Returns:
         list[dict[str, Any]]: List of rows with sensitive fields masked based
-                              on environment configuration. Returns original
-                              rows if masking is disabled or if an error occurs.
+                              on configuration. Returns original rows if
+                              masking is disabled or if an error occurs.
     """
     mask_fields = _resolve_mask_fields()
     if not mask_fields:

glaip_sdk/cli/pager.py

@@ -19,6 +19,8 @@ from typing import Any
 
 from rich.console import Console
 
+from glaip_sdk.cli.constants import PAGER_HEADER_ENABLED, PAGER_MODE, PAGER_WRAP_LINES
+
 __all__ = [
     "console",
     "_prepare_pager_env",
@@ -64,8 +66,7 @@ def _prepare_pager_env(clear_on_exit: bool = True) -> None:
       -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.
-    Toggle wrapping with AIP_PAGER_WRAP=1 to drop -S.
-    Power users can override via AIP_LESS_FLAGS.
+    Toggle wrapping via `PAGER_WRAP_LINES` (True drops -S).
 
     Args:
         clear_on_exit: Whether to clear the pager on exit (default: True)
@@ -75,10 +76,9 @@ def _prepare_pager_env(clear_on_exit: bool = True) -> None:
     """
     os.environ.pop("LESSSECURE", None)
     if os.getenv("LESS") is None:
-        want_wrap = os.getenv("AIP_PAGER_WRAP", "0") == "1"
-        base = "-R" if want_wrap else "-RS"
+        base = "-R" if PAGER_WRAP_LINES else "-RS"
         default_flags = base if clear_on_exit else (base + "FX")
-        os.environ["LESS"] = os.getenv("AIP_LESS_FLAGS", default_flags)
+        os.environ["LESS"] = default_flags
 
 
 def _render_ansi(renderable: Any) -> str:
@@ -111,8 +111,7 @@ def _pager_header() -> str:
     Returns:
         str: Header text containing navigation help, or empty string if disabled
     """
-    v = (os.getenv("AIP_PAGER_HEADER", "1") or "1").strip().lower()
-    if v in {"0", "false", "off"}:
+    if not PAGER_HEADER_ENABLED:
         return ""
     return "\n".join(
         [
@@ -254,10 +253,10 @@ def _should_page_output(row_count: int, is_tty: bool) -> bool:
         bool: True if output should be paginated, False otherwise
     """
     active_console = _get_console()
-    pager_env = (os.getenv("AIP_PAGER", "auto") or "auto").lower()
-    if pager_env in ("0", "off", "false"):
+    pager_mode = (PAGER_MODE or "auto").lower()
+    if pager_mode in ("0", "off", "false"):
         return False
-    if pager_env in ("1", "on", "true"):
+    if pager_mode in ("1", "on", "true"):
         return is_tty
     try:
         term_h = active_console.size.height or 24