glaip-sdk 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

glaip_sdk/cli/commands/accounts.py

@@ -6,7 +6,9 @@ Authors:
 
 import getpass
 import json
+import os
 import sys
+from pathlib import Path
 
 import click
 from rich.console import Console
@@ -110,6 +112,153 @@ def list_accounts(output_json: bool) -> None:
     console.print(f"\n[{INFO}]💡 Tip[/]: To update an account's URL or key, use: [bold]aip accounts edit <name>[/bold]")
 
 
+def _build_account_json_payload(
+    name: str,
+    api_url: str,
+    masked_key: str,
+    config_path: str,
+    is_active: bool,
+    env_lock: bool,
+    metadata: dict[str, str | None],
+) -> dict[str, str | bool | None]:
+    """Build JSON payload for account display.
+
+    Args:
+        name: Account name.
+        api_url: API URL.
+        masked_key: Masked API key.
+        config_path: Config file path.
+        is_active: Whether account is active.
+        env_lock: Whether env credentials are set.
+        metadata: Account metadata dict.
+
+    Returns:
+        JSON payload dict.
+    """
+    payload: dict[str, str | bool | None] = {
+        "name": name,
+        "api_url": api_url,
+        "api_key_masked": masked_key,
+        "config_path": config_path,
+        "active": is_active,
+        "env_lock": env_lock,
+    }
+    for key, value in metadata.items():
+        if value:
+            payload[key] = value
+    return payload
+
+
+def _format_config_path(config_path: str) -> str:
+    """Format config path for display, shortening under home."""
+    path_obj = Path(config_path).expanduser()
+    try:
+        home = Path.home().expanduser()
+        resolved = path_obj.resolve(strict=False)
+        relative = resolved.relative_to(home).as_posix()
+        return f"~/{relative}"
+    except ValueError:
+        # Not under home; return expanded path
+        return str(path_obj)
+    except OSError:
+        # Fall back to original string on resolution errors
+        return config_path
+
+
+def _build_account_display_lines(
+    name: str,
+    api_url: str,
+    masked_key: str,
+    config_path: str,
+    is_active: bool,
+    env_lock: bool,
+    metadata: dict[str, str | None],
+) -> list[str]:
+    """Build display lines for account information.
+
+    Args:
+        name: Account name.
+        api_url: API URL.
+        masked_key: Masked API key.
+        config_path: Config file path.
+        is_active: Whether account is active.
+        env_lock: Whether env credentials are set.
+        metadata: Account metadata dict.
+
+    Returns:
+        List of formatted display lines.
+    """
+    lines = [
+        f"[{SUCCESS_STYLE}]Name[/]: {name}{' (active)' if is_active else ''}",
+        f"[{SUCCESS_STYLE}]API URL[/]: {api_url or 'not set'}",
+        f"[{SUCCESS_STYLE}]Key[/]: {masked_key or 'not set'}",
+        f"[{SUCCESS_STYLE}]Config[/]: {config_path}",
+    ]
+
+    label_map = {
+        "notes": "Notes",
+        "last_used_at": "Last used",
+        "last_validated_at": "Last validated",
+        "created_with": "Created with",
+    }
+    for key, label in label_map.items():
+        value = metadata.get(key)
+        if value:
+            lines.append(f"[{SUCCESS_STYLE}]{label}[/]: {value}")
+
+    if env_lock:
+        lines.append(
+            f"[{WARNING_STYLE}]Env credentials detected (AIP_API_URL/AIP_API_KEY); stored profile may be ignored.[/]"
+        )
+
+    return lines
+
+
+@accounts_group.command("show")
+@click.argument("name")
+@click.option("--json", "output_json", is_flag=True, help="Output in JSON format")
+def show_account(name: str, output_json: bool) -> None:
+    """Show details for a single account profile."""
+    store = get_account_store()
+    account = store.get_account(name)
+
+    if not account:
+        console.print(f"[{ERROR_STYLE}]Error: Account '{name}' not found.[/]")
+        raise click.Abort()
+
+    api_url = account.get("api_url", "")
+    api_key = account.get("api_key")
+    masked_key = _mask_api_key(api_key or "")
+    active_account = store.get_active_account()
+    is_active = active_account == name
+    env_lock = bool(os.getenv("AIP_API_URL") or os.getenv("AIP_API_KEY"))
+    config_path_raw = str(store.config_file)
+    config_path_display = _format_config_path(config_path_raw)
+
+    metadata = {
+        "notes": account.get("notes"),
+        "last_used_at": account.get("last_used_at"),
+        "last_validated_at": account.get("last_validated_at"),
+        "created_with": account.get("created_with"),
+    }
+
+    if output_json:
+        payload = _build_account_json_payload(name, api_url, masked_key, config_path_raw, is_active, env_lock, metadata)
+        click.echo(json.dumps(payload, indent=2))
+        return
+
+    lines = _build_account_display_lines(name, api_url, masked_key, config_path_display, is_active, env_lock, metadata)
+
+    lock_badge = " 🔒 Env lock" if env_lock else ""
+    console.print(
+        AIPPanel(
+            "\n".join(lines),
+            title=f"AIP Account{lock_badge}",
+            border_style=ACCENT_STYLE,
+        ),
+    )
+
+
 def _check_account_overwrite(name: str, store: AccountStore, overwrite: bool) -> dict[str, str] | None:
     """Check if account exists and handle overwrite logic.
 
@@ -155,8 +304,8 @@ def _get_credentials_non_interactive(
         if not sys.stdin.isatty():
             return url, sys.stdin.read().strip()
         console.print(
-            f"[{ERROR_STYLE}]Error: --key requires stdin input. "
-            f"Use: cat key.txt | {command_name} {name} --url {url} --key[/]",
+            f"[{ERROR_STYLE}]Error: --key expects stdin or an explicit value. "
+            f"Use '--key <value>' or pipe: cat key.txt | {command_name} {name} --url {url} --key[/]",
         )
         raise click.Abort()
     # URL provided, prompt for key
@@ -179,7 +328,8 @@ def _get_credentials_interactive(read_key_from_stdin: bool, existing: dict[str,
     """
     if read_key_from_stdin:
         console.print(
-            f"[{ERROR_STYLE}]Error: --key requires --url. For non-interactive mode, provide both: --url <url> --key[/]",
+            f"[{ERROR_STYLE}]Error: --key requires --url. "
+            f"Provide --url with --key <value|-> for non-interactive use or omit --key to be prompted.[/]",
         )
         raise click.Abort()
     # Fully interactive
@@ -237,7 +387,7 @@ def _preserve_existing_values(
 
 def _collect_credentials_from_inputs(
     url: str | None,
-    read_key_from_stdin: bool,
+    api_key_input: str | None,
     name: str,
     existing: dict[str, str] | None,
     command_name: str,
@@ -247,7 +397,7 @@ def _collect_credentials_from_inputs(
 
     Args:
         url: Optional URL from flag.
-        read_key_from_stdin: Whether to read key from stdin.
+        api_key_input: API key value from flag (or "-" when stdin requested).
         name: Account name (for error messages).
         existing: Existing account data.
         command_name: Command name for error messages.
@@ -256,6 +406,29 @@ def _collect_credentials_from_inputs(
     Returns:
         Tuple of (api_url, api_key).
     """
+    provided_key = api_key_input if api_key_input not in (None, "-") else None
+    read_key_from_stdin = api_key_input == "-"
+
+    if provided_key and url:
+        # Fully non-interactive: URL and key provided via flags
+        return url, provided_key
+
+    if provided_key:
+        # Reuse stored URL if present; otherwise require --url
+        if existing_url:
+            return existing_url, provided_key
+        if existing:
+            console.print(
+                f"[{ERROR_STYLE}]Error: Account '{name}' is missing an API URL. "
+                f"Provide --url to set it when rotating the key.[/]"
+            )
+        else:
+            console.print(
+                f"[{ERROR_STYLE}]Error: --key requires --url for new accounts. "
+                f"Run without --key for prompts or pass both flags for non-interactive setup.[/]",
+            )
+        raise click.Abort()
+
     if url and read_key_from_stdin:
         # Non-interactive: URL from flag, key from stdin
         return _get_credentials_non_interactive(url, True, name, command_name)
@@ -271,15 +444,25 @@ def _collect_credentials_from_inputs(
 
 def _collect_account_credentials(
     url: str | None,
-    read_key_from_stdin: bool,
+    api_key_input: str | None,
     name: str,
     existing: dict[str, str] | None,
 ) -> tuple[str, str]:
     """Collect account credentials from various input methods.
 
+    Examples:
+        # Inline key
+        aip accounts add prod --url https://api.example.com --key sk-abc123
+
+        # Stdin (useful for scripts)
+        echo "sk-abc123" | aip accounts add prod --url https://api.example.com --key
+
+        # Fully interactive
+        aip accounts add prod
+
     Args:
         url: Optional URL from flag.
-        read_key_from_stdin: Whether to read key from stdin.
+        api_key_input: API key value from flag (or "-" when stdin requested).
         name: Account name (for error messages).
         existing: Existing account data.
 
@@ -293,9 +476,7 @@ def _collect_account_credentials(
     existing_url = existing.get("api_url", "") if existing else ""
     existing_key = existing.get("api_key", "") if existing else ""
 
-    api_url, api_key = _collect_credentials_from_inputs(
-        url, read_key_from_stdin, name, existing, command_name, existing_url
-    )
+    api_url, api_key = _collect_credentials_from_inputs(url, api_key_input, name, existing, command_name, existing_url)
 
     # Preserve stored values when blank input is provided during edit
     api_url, api_key = _preserve_existing_values(api_url, api_key, existing_url, existing_key)
@@ -311,9 +492,12 @@ def _collect_account_credentials(
 @click.option("--url", help="API URL (required for non-interactive mode)")
 @click.option(
     "--key",
-    "read_key_from_stdin",
-    is_flag=True,
-    help="Read API key from stdin (secure, for scripts). Requires --url.",
+    "api_key_input",
+    type=str,
+    is_flag=False,
+    flag_value="-",
+    default=None,
+    help="API key value. Pass without a value or '-' to read from stdin. Requires --url for non-interactive use.",
 )
 @click.option(
     "--yes",
@@ -324,7 +508,7 @@ def _collect_account_credentials(
 def add_account(
     name: str,
     url: str | None,
-    read_key_from_stdin: bool,
+    api_key_input: str | None,
     overwrite: bool,
 ) -> None:
     """Add a new account profile.
@@ -332,7 +516,7 @@ def add_account(
     NAME is the account name (1-32 chars, alphanumeric, dash, underscore).
 
     By default, this command runs interactively, prompting for API URL and key.
-    For non-interactive use, both --url and --key (stdin) are required.
+    For non-interactive use, provide --url with --key <value> or --key - (stdin).
 
     If the account already exists, use --yes to overwrite without prompting.
     To update an existing account, use [bold]aip accounts edit <name>[/bold] instead.
@@ -343,7 +527,7 @@ def add_account(
     existing = _check_account_overwrite(name, store, overwrite)
 
     # Collect credentials
-    api_url, api_key = _collect_account_credentials(url, read_key_from_stdin, name, existing)
+    api_url, api_key = _collect_account_credentials(url, api_key_input, name, existing)
 
     # Save account
     try:
@@ -363,14 +547,17 @@ def add_account(
 @click.option("--url", help="API URL (optional, leave blank to keep current)")
 @click.option(
     "--key",
-    "read_key_from_stdin",
-    is_flag=True,
-    help="Read API key from stdin (secure, for scripts). Uses stored URL unless --url is provided.",
+    "api_key_input",
+    type=str,
+    is_flag=False,
+    flag_value="-",
+    default=None,
+    help="API key value. Pass without a value or '-' to read from stdin. Uses stored URL unless --url is provided.",
 )
 def edit_account(
     name: str,
     url: str | None,
-    read_key_from_stdin: bool,
+    api_key_input: str | None,
 ) -> None:
     """Edit an existing account profile's URL or key.
 
@@ -379,8 +566,8 @@ def edit_account(
     By default, this command runs interactively, showing current values and
     prompting for new ones. Leave fields blank to keep current values.
 
-    For non-interactive use, provide --url to change the URL, --key (stdin) to rotate the key,
-    or both. Stored values are reused for any fields not provided.
+    For non-interactive use, provide --url to change the URL, --key <value> to rotate the key,
+    or --key - (stdin) for scripts. Stored values are reused for any fields not provided.
     """
     store = get_account_store()
 
@@ -392,7 +579,7 @@ def edit_account(
         raise click.Abort()
 
     # Collect credentials (will pre-fill existing values in interactive mode)
-    api_url, api_key = _collect_account_credentials(url, read_key_from_stdin, name, existing)
+    api_url, api_key = _collect_account_credentials(url, api_key_input, name, existing)
 
     # Save account
     try:

glaip_sdk/cli/commands/tools.py

@@ -10,8 +10,6 @@ from pathlib import Path
 from typing import Any
 
 import click
-from rich.console import Console
-
 from glaip_sdk.branding import (
     ACCENT_STYLE,
     ERROR_STYLE,
@@ -29,9 +27,7 @@ from glaip_sdk.cli.display import (
     handle_json_output,
     handle_rich_output,
 )
-from glaip_sdk.cli.io import (
-    fetch_raw_resource_details,
-)
+from glaip_sdk.cli.io import fetch_raw_resource_details
 from glaip_sdk.cli.io import (
     load_resource_from_file_with_validation as load_resource_from_file,
 )
@@ -49,6 +45,7 @@ from glaip_sdk.cli.utils import (
 )
 from glaip_sdk.icons import ICON_TOOL
 from glaip_sdk.utils.import_export import merge_import_with_cli_args
+from rich.console import Console
 
 console = Console()
 

glaip_sdk/client/_agent_payloads.py

@@ -15,10 +15,7 @@ from glaip_sdk.config.constants import (
     DEFAULT_AGENT_VERSION,
     DEFAULT_MODEL,
 )
-from glaip_sdk.payload_schemas.agent import (
-    AgentImportOperation,
-    get_import_field_plan,
-)
+from glaip_sdk.payload_schemas.agent import AgentImportOperation, get_import_field_plan
 from glaip_sdk.utils.client_utils import extract_ids
 
 _LM_CONFLICT_KEYS = {
@@ -437,12 +434,16 @@ __all__ = [
 
 def _build_base_update_payload(request: AgentUpdateRequest, current_agent: Any) -> dict[str, Any]:
     """Populate immutable agent update fields using request data or existing agent defaults."""
+    # Support both "agent_type" (runtime class) and "type" (API response) attributes
+    current_type = getattr(current_agent, "agent_type", None) or getattr(current_agent, "type", None)
     return {
-        "name": request.name.strip() if request.name is not None else getattr(current_agent, "name", None),
-        "instruction": request.instruction.strip()
-        if request.instruction is not None
-        else getattr(current_agent, "instruction", None),
-        "type": request.agent_type or getattr(current_agent, "type", None) or DEFAULT_AGENT_TYPE,
+        "name": (request.name.strip() if request.name is not None else getattr(current_agent, "name", None)),
+        "instruction": (
+            request.instruction.strip()
+            if request.instruction is not None
+            else getattr(current_agent, "instruction", None)
+        ),
+        "type": request.agent_type or current_type or DEFAULT_AGENT_TYPE,
         "framework": request.framework or getattr(current_agent, "framework", None) or DEFAULT_AGENT_FRAMEWORK,
         "version": request.version or getattr(current_agent, "version", None) or DEFAULT_AGENT_VERSION,
     }

glaip_sdk/client/agents.py

@@ -3,6 +3,7 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
 import asyncio
@@ -15,7 +16,7 @@ from pathlib import Path
 from typing import Any, BinaryIO
 
 import httpx
-
+from glaip_sdk.agents import Agent
 from glaip_sdk.client._agent_payloads import (
     AgentCreateRequest,
     AgentListParams,
@@ -40,7 +41,7 @@ from glaip_sdk.config.constants import (
     DEFAULT_MODEL,
 )
 from glaip_sdk.exceptions import NotFoundError, ValidationError
-from glaip_sdk.models import Agent
+from glaip_sdk.models import AgentResponse
 from glaip_sdk.payload_schemas.agent import list_server_only_fields
 from glaip_sdk.utils.agent_config import normalize_agent_config_for_import
 from glaip_sdk.utils.client_utils import (
@@ -73,7 +74,9 @@ _DEFAULT_METADATA_TYPE = "custom"
 
 
 @asynccontextmanager
-async def _async_timeout_guard(timeout_seconds: float | None) -> AsyncGenerator[None, None]:
+async def _async_timeout_guard(
+    timeout_seconds: float | None,
+) -> AsyncGenerator[None, None]:
     """Apply an asyncio timeout when a custom timeout is provided."""
     if timeout_seconds is None:
         yield
@@ -260,7 +263,7 @@ class AgentClient(BaseClient):
         self._renderer_manager = AgentRunRenderingManager(logger)
         self._tool_client: ToolClient | None = None
         self._mcp_client: MCPClient | None = None
-        self._runs_client: "AgentRunsClient | None" = None
+        self._runs_client: AgentRunsClient | None = None
 
     def list_agents(
         self,
@@ -359,7 +362,8 @@ class AgentClient(BaseClient):
                 status_code=404,
             )
 
-        return Agent(**data)._set_client(self)
+        response = AgentResponse(**data)
+        return Agent.from_response(response, client=self)
 
     def find_agents(self, name: str | None = None) -> list[Agent]:
         """Find agents by name."""
@@ -826,7 +830,8 @@ class AgentClient(BaseClient):
             get_endpoint_fmt=f"{AGENTS_ENDPOINT}{{id}}",
             json=payload_dict,
         )
-        return Agent(**full_agent_data)._set_client(self)
+        response = AgentResponse(**full_agent_data)
+        return Agent.from_response(response, client=self)
 
     def create_agent(
         self,
@@ -921,8 +926,9 @@ class AgentClient(BaseClient):
 
         payload_dict = request.to_payload(current_agent)
 
-        response = self._request("PUT", f"/agents/{agent_id}", json=payload_dict)
-        return Agent(**response)._set_client(self)
+        api_response = self._request("PUT", f"/agents/{agent_id}", json=payload_dict)
+        response = AgentResponse(**api_response)
+        return Agent.from_response(response, client=self)
 
     def update_agent(
         self,
@@ -969,6 +975,62 @@ class AgentClient(BaseClient):
         """Delete an agent."""
         self._request("DELETE", f"/agents/{agent_id}")
 
+    def upsert_agent(self, identifier: str | Agent, **kwargs) -> Agent:
+        """Create or update an agent by instance, ID, or name.
+
+        Args:
+            identifier: Agent instance, ID (UUID string), or name
+            **kwargs: Agent configuration (instruction, description, tools, etc.)
+
+        Returns:
+            The created or updated agent.
+
+        Example:
+            >>> # By name (creates if not exists)
+            >>> agent = client.agents.upsert_agent(
+            ...     "hello_agent",
+            ...     instruction="You are a helpful assistant.",
+            ...     description="A friendly agent",
+            ... )
+            >>> # By instance
+            >>> agent = client.agents.upsert_agent(existing_agent, description="Updated")
+            >>> # By ID
+            >>> agent = client.agents.upsert_agent("uuid-here", description="Updated")
+        """
+        # Handle Agent instance
+        if isinstance(identifier, Agent):
+            if identifier.id:
+                logger.info("Updating agent by instance: %s", identifier.name)
+                return self.update_agent(identifier.id, name=identifier.name, **kwargs)
+            identifier = identifier.name
+
+        # Handle string (ID or name)
+        if isinstance(identifier, str):
+            # Check if it's a UUID
+            if is_uuid(identifier):
+                logger.info("Updating agent by ID: %s", identifier)
+                return self.update_agent(identifier, **kwargs)
+
+            # It's a name - find or create
+            return self._upsert_agent_by_name(identifier, **kwargs)
+
+        raise ValueError(f"Invalid identifier type: {type(identifier)}")
+
+    def _upsert_agent_by_name(self, name: str, **kwargs) -> Agent:
+        """Find agent by name and update, or create if not found."""
+        existing = self.find_agents(name)
+
+        if len(existing) == 1:
+            logger.info("Updating existing agent: %s", name)
+            return self.update_agent(existing[0].id, name=name, **kwargs)
+
+        if len(existing) > 1:
+            raise ValueError(f"Multiple agents found with name '{name}'")
+
+        # Create new agent
+        logger.info("Creating new agent: %s", name)
+        return self.create_agent(name=name, **kwargs)
+
     def _prepare_sync_request_data(
         self,
         message: str,

glaip_sdk/client/base.py

@@ -3,6 +3,7 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
 import logging

glaip_sdk/client/main.py

@@ -3,16 +3,24 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
-from typing import Any
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.client.agents import AgentClient
 from glaip_sdk.client.base import BaseClient
 from glaip_sdk.client.mcps import MCPClient
 from glaip_sdk.client.shared import build_shared_config
 from glaip_sdk.client.tools import ToolClient
-from glaip_sdk.models import MCP, Agent, Tool
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents import Agent
+    from glaip_sdk.client._agent_payloads import AgentListResult
+    from glaip_sdk.mcps import MCP
+    from glaip_sdk.tools import Tool
 
 
 class Client(BaseClient):
@@ -49,7 +57,7 @@ class Client(BaseClient):
         name: str | None = None,
         version: str | None = None,
         sync_langflow_agents: bool = False,
-    ) -> list[Agent]:
+    ) -> AgentListResult:
         """List agents with optional filtering.
 
         Args:
@@ -60,7 +68,7 @@ class Client(BaseClient):
             sync_langflow_agents: Sync with LangFlow server before listing (only applies when agent_type=langflow)
 
         Returns:
-            List of agents matching the filters
+            AgentListResult with agents and pagination metadata. Supports iteration and indexing.
         """
         return self.agents.list_agents(
             agent_type=agent_type,