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

glaip_sdk/client/base.py

@@ -14,7 +14,7 @@ from dotenv import load_dotenv
 
 import glaip_sdk
 from glaip_sdk._version import __version__ as SDK_VERSION
-from glaip_sdk.config.constants import SDK_NAME
+from glaip_sdk.config.constants import DEFAULT_ERROR_MESSAGE, SDK_NAME
 from glaip_sdk.exceptions import (
     AuthenticationError,
     ConflictError,
@@ -230,8 +230,13 @@ class BaseClient:
             else:
                 raise
 
-    def _request(self, method: str, endpoint: str, **kwargs) -> Any:
-        """Make HTTP request with error handling."""
+    def _perform_request(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Execute a raw HTTP request with retry handling."""
         # Ensure client is alive before making request
         self._ensure_client_alive()
 
@@ -239,7 +244,7 @@ class BaseClient:
         try:
             response = self.http_client.request(method, endpoint, **kwargs)
             client_log.debug(f"Response status: {response.status_code}")
-            return self._handle_response(response)
+            return response
         except httpx.ConnectError as e:
             client_log.warning(
                 f"Connection error on {method} {endpoint}, retrying once: {e}"
@@ -249,11 +254,26 @@ class BaseClient:
                 client_log.debug(
                     f"Retry successful, response status: {response.status_code}"
                 )
-                return self._handle_response(response)
+                return response
             except httpx.ConnectError:
                 client_log.error(f"Retry failed for {method} {endpoint}: {e}")
                 raise e
 
+    def _request(self, method: str, endpoint: str, **kwargs) -> Any:
+        """Make HTTP request with error handling and unwrap success envelopes."""
+        response = self._perform_request(method, endpoint, **kwargs)
+        return self._handle_response(response, unwrap=True)
+
+    def _request_with_envelope(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Make HTTP request but return the full success envelope."""
+        response = self._perform_request(method, endpoint, **kwargs)
+        return self._handle_response(response, unwrap=False)
+
     def _parse_response_content(self, response: httpx.Response) -> Any | None:
         """Parse response content based on content type."""
         if response.status_code == 204:
@@ -271,14 +291,14 @@ class BaseClient:
         else:
             return None  # Let _handle_response deal with error status codes
 
-    def _handle_success_response(self, parsed: Any) -> Any:
+    def _handle_success_response(self, parsed: Any, *, unwrap: bool) -> Any:
         """Handle successful response with success flag."""
         if isinstance(parsed, dict) and "success" in parsed:
             if parsed.get("success"):
-                return parsed.get("data", parsed)
+                return parsed.get("data", parsed) if unwrap else parsed
             else:
                 error_type = parsed.get("error", "UnknownError")
-                message = parsed.get("message", "Unknown error")
+                message = parsed.get("message", DEFAULT_ERROR_MESSAGE)
                 self._raise_api_error(
                     400,
                     message,
@@ -290,19 +310,67 @@ class BaseClient:
 
     def _get_error_message(self, response: httpx.Response) -> str:
         """Extract error message from response, preferring parsed content."""
-        # Try to get error message from parsed content if available
-        error_message = response.text
+        parsed = self._parse_error_json(response)
+        if parsed is None:
+            return response.text
+
+        formatted = self._format_parsed_error(parsed)
+        return formatted if formatted is not None else response.text
+
+    def _parse_error_json(self, response: httpx.Response) -> Any | None:
+        """Safely parse JSON from an error response."""
         try:
-            parsed = response.json()
-            if isinstance(parsed, dict) and "message" in parsed:
-                error_message = parsed["message"]
-            elif isinstance(parsed, str):
-                error_message = parsed
+            return response.json()
         except (ValueError, TypeError):
-            pass  # Use response.text as fallback
-        return error_message
+            return None
+
+    def _format_parsed_error(self, parsed: Any) -> str | None:
+        """Build a readable error message from parsed JSON payloads."""
+        if isinstance(parsed, dict):
+            return self._format_error_dict(parsed)
+        if isinstance(parsed, str):
+            return parsed
+        return str(parsed) if parsed else None
+
+    def _format_error_dict(self, parsed: dict[str, Any]) -> str:
+        """Format structured API error payloads."""
+        detail = parsed.get("detail")
+        if isinstance(detail, list):
+            validation_message = self._format_validation_errors(detail)
+            if validation_message:
+                return validation_message
+            return f"Validation error: {parsed}"
+
+        message = parsed.get("message")
+        if message:
+            return message
+
+        return str(parsed) if parsed else DEFAULT_ERROR_MESSAGE
+
+    def _format_validation_errors(self, errors: list[Any]) -> str | None:
+        """Render validation errors into a human-readable string."""
+        entries: list[str] = []
+        for error in errors:
+            if isinstance(error, dict):
+                loc = " -> ".join(str(x) for x in error.get("loc", []))
+                msg = error.get("msg", DEFAULT_ERROR_MESSAGE)
+                error_type = error.get("type", "unknown")
+                prefix = loc if loc else "Field"
+                entries.append(f"  {prefix}: {msg} ({error_type})")
+            else:
+                entries.append(f"  {error}")
+
+        if not entries:
+            return None
 
-    def _handle_response(self, response: httpx.Response) -> Any:
+        return "Validation errors:\n" + "\n".join(entries)
+
+    def _handle_response(
+        self,
+        response: httpx.Response,
+        *,
+        unwrap: bool = True,
+    ) -> Any:
         """Handle HTTP response with proper error handling."""
         # Handle no-content success before general error handling
         if response.status_code == 204:
@@ -311,14 +379,18 @@ class BaseClient:
         # Handle error status codes
         if not (200 <= response.status_code < 300):
             error_message = self._get_error_message(response)
-            self._raise_api_error(response.status_code, error_message)
+            # Try to parse response content for payload
+            parsed_content = self._parse_response_content(response)
+            self._raise_api_error(
+                response.status_code, error_message, payload=parsed_content
+            )
             return None  # Won't be reached but helps with type checking
 
         parsed = self._parse_response_content(response)
         if parsed is None:
             return None
 
-        return self._handle_success_response(parsed)
+        return self._handle_success_response(parsed, unwrap=unwrap)
 
     def _raise_api_error(
         self,

glaip_sdk/client/main.py

@@ -18,6 +18,11 @@ class Client(BaseClient):
     """Main client that composes all specialized clients and shares one HTTP session."""
 
     def __init__(self, **kwargs):
+        """Initialize the main client.
+
+        Args:
+            **kwargs: Client configuration arguments (api_url, api_key, timeout, etc.)
+        """
         super().__init__(**kwargs)
         # Share the single httpx.Client + config with sub-clients
         shared_config = {
@@ -37,6 +42,10 @@ class Client(BaseClient):
         """Create a new agent."""
         return self.agents.create_agent(**kwargs)
 
+    def create_agent_from_file(self, *args, **kwargs) -> Agent:
+        """Create a new agent from a JSON or YAML configuration file."""
+        return self.agents.create_agent_from_file(*args, **kwargs)
+
     def list_agents(
         self,
         agent_type: str | None = None,
@@ -81,6 +90,10 @@ class Client(BaseClient):
         """Update an existing agent."""
         return self.agents.update_agent(agent_id, **kwargs)
 
+    def update_agent_from_file(self, agent_id: str, *args, **kwargs) -> Agent:
+        """Update an existing agent using a JSON or YAML configuration file."""
+        return self.agents.update_agent_from_file(agent_id, *args, **kwargs)
+
     def delete_agent(self, agent_id: str) -> bool:
         """Delete an agent."""
         return self.agents.delete_agent(agent_id)
@@ -199,6 +212,7 @@ class Client(BaseClient):
     # ---- Timeout propagation ----
     @property
     def timeout(self) -> float:  # type: ignore[override]
+        """Get the client timeout value."""
         return super().timeout
 
     @timeout.setter

glaip_sdk/client/run_rendering.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""Rendering helpers for agent streaming flows.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import logging
+from time import monotonic
+from typing import Any
+
+import httpx
+from rich.console import Console as _Console
+
+from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
+from glaip_sdk.utils.client_utils import iter_sse_events
+from glaip_sdk.utils.rendering.models import RunStats
+from glaip_sdk.utils.rendering.renderer import RichStreamRenderer
+from glaip_sdk.utils.rendering.renderer.config import RendererConfig
+
+
+class AgentRunRenderingManager:
+    """Coordinate renderer creation and streaming event handling."""
+
+    def __init__(self, logger: logging.Logger | None = None) -> None:
+        """Initialize the rendering manager.
+
+        Args:
+            logger: Optional logger instance, creates default if None
+        """
+        self._logger = logger or logging.getLogger(__name__)
+
+    # --------------------------------------------------------------------- #
+    # Renderer setup helpers
+    # --------------------------------------------------------------------- #
+    def create_renderer(
+        self,
+        renderer_spec: RichStreamRenderer | str | None,
+        *,
+        verbose: bool = False,
+    ) -> RichStreamRenderer:
+        """Create an appropriate renderer based on the supplied spec."""
+        if isinstance(renderer_spec, RichStreamRenderer):
+            return renderer_spec
+
+        if isinstance(renderer_spec, str):
+            if renderer_spec == "silent":
+                return self._create_silent_renderer()
+            if renderer_spec == "minimal":
+                return self._create_minimal_renderer()
+            return self._create_default_renderer(verbose)
+
+        return self._create_default_renderer(verbose)
+
+    def build_initial_metadata(
+        self,
+        agent_id: str,
+        message: str,
+        kwargs: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Construct the initial renderer metadata payload."""
+        return {
+            "agent_name": kwargs.get("agent_name", agent_id),
+            "model": kwargs.get("model"),
+            "run_id": None,
+            "input_message": message,
+        }
+
+    @staticmethod
+    def start_renderer(renderer: RichStreamRenderer, meta: dict[str, Any]) -> None:
+        """Notify renderer that streaming is starting."""
+        renderer.on_start(meta)
+
+    def _create_silent_renderer(self) -> RichStreamRenderer:
+        silent_config = RendererConfig(
+            live=False,
+            persist_live=False,
+            show_delegate_tool_panels=False,
+            render_thinking=False,
+        )
+        return RichStreamRenderer(
+            console=_Console(file=io.StringIO(), force_terminal=False),
+            cfg=silent_config,
+            verbose=False,
+        )
+
+    def _create_minimal_renderer(self) -> RichStreamRenderer:
+        minimal_config = RendererConfig(
+            live=False,
+            persist_live=False,
+            show_delegate_tool_panels=False,
+            render_thinking=False,
+        )
+        return RichStreamRenderer(
+            console=_Console(),
+            cfg=minimal_config,
+            verbose=False,
+        )
+
+    def _create_verbose_renderer(self) -> RichStreamRenderer:
+        verbose_config = RendererConfig(
+            theme="dark",
+            style="debug",
+            live=False,
+            show_delegate_tool_panels=True,
+            append_finished_snapshots=False,
+        )
+        return RichStreamRenderer(
+            console=_Console(),
+            cfg=verbose_config,
+            verbose=True,
+        )
+
+    def _create_default_renderer(self, verbose: bool) -> RichStreamRenderer:
+        if verbose:
+            return self._create_verbose_renderer()
+        default_config = RendererConfig(show_delegate_tool_panels=True)
+        return RichStreamRenderer(console=_Console(), cfg=default_config)
+
+    # --------------------------------------------------------------------- #
+    # Streaming event handling
+    # --------------------------------------------------------------------- #
+    def process_stream_events(
+        self,
+        stream_response: httpx.Response,
+        renderer: RichStreamRenderer,
+        timeout_seconds: float,
+        agent_name: str | None,
+        meta: dict[str, Any],
+    ) -> tuple[str, dict[str, Any], float | None, float | None]:
+        """Process streaming events and accumulate response."""
+        final_text = ""
+        stats_usage: dict[str, Any] = {}
+        started_monotonic: float | None = None
+
+        self._capture_request_id(stream_response, meta, renderer)
+
+        for event in iter_sse_events(stream_response, timeout_seconds, agent_name):
+            if started_monotonic is None:
+                started_monotonic = self._maybe_start_timer(event)
+
+            final_text, stats_usage = self._process_single_event(
+                event,
+                renderer,
+                final_text,
+                stats_usage,
+                meta,
+            )
+
+        finished_monotonic = monotonic()
+        return final_text, stats_usage, started_monotonic, finished_monotonic
+
+    def _capture_request_id(
+        self,
+        stream_response: httpx.Response,
+        meta: dict[str, Any],
+        renderer: RichStreamRenderer,
+    ) -> None:
+        req_id = stream_response.headers.get(
+            "x-request-id"
+        ) or stream_response.headers.get("x-run-id")
+        if req_id:
+            meta["run_id"] = req_id
+            renderer.on_start(meta)
+
+    def _maybe_start_timer(self, event: dict[str, Any]) -> float | None:
+        try:
+            ev = json.loads(event["data"])
+        except json.JSONDecodeError:
+            return None
+
+        if "content" in ev or "status" in ev or ev.get("metadata"):
+            return monotonic()
+        return None
+
+    def _process_single_event(
+        self,
+        event: dict[str, Any],
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        meta: dict[str, Any],
+    ) -> tuple[str, dict[str, Any]]:
+        try:
+            ev = json.loads(event["data"])
+        except json.JSONDecodeError:
+            self._logger.debug("Non-JSON SSE fragment skipped")
+            return final_text, stats_usage
+
+        kind = (ev.get("metadata") or {}).get("kind")
+        renderer.on_event(ev)
+
+        if kind == "artifact":
+            return final_text, stats_usage
+
+        if kind == "final_response" and ev.get("content"):
+            final_text = ev.get("content", "")
+        elif ev.get("content"):
+            final_text = self._handle_content_event(ev, final_text)
+        elif kind == "usage":
+            stats_usage.update(ev.get("usage") or {})
+        elif kind == "run_info":
+            self._handle_run_info_event(ev, meta, renderer)
+
+        return final_text, stats_usage
+
+    def _handle_content_event(self, ev: dict[str, Any], final_text: str) -> str:
+        content = ev.get("content", "")
+        if not content.startswith("Artifact received:"):
+            return content
+        return final_text
+
+    def _handle_run_info_event(
+        self,
+        ev: dict[str, Any],
+        meta: dict[str, Any],
+        renderer: RichStreamRenderer,
+    ) -> None:
+        if ev.get("model"):
+            meta["model"] = ev["model"]
+            renderer.on_start(meta)
+        if ev.get("run_id"):
+            meta["run_id"] = ev["run_id"]
+            renderer.on_start(meta)
+
+    # --------------------------------------------------------------------- #
+    # Finalisation helpers
+    # --------------------------------------------------------------------- #
+    def finalize_renderer(
+        self,
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        started_monotonic: float | None,
+        finished_monotonic: float | None,
+    ) -> str:
+        """Complete rendering and return the textual result."""
+        st = RunStats()
+        st.started_at = started_monotonic or st.started_at
+        st.finished_at = finished_monotonic or st.started_at
+        st.usage = stats_usage
+
+        rendered_text = ""
+        buffer_values: Any | None = None
+
+        if hasattr(renderer, "state") and hasattr(renderer.state, "buffer"):
+            buffer_values = renderer.state.buffer
+        elif hasattr(renderer, "buffer"):
+            buffer_values = getattr(renderer, "buffer")
+
+        if buffer_values is not None:
+            try:
+                rendered_text = "".join(buffer_values)
+            except TypeError:
+                rendered_text = ""
+
+        renderer.on_complete(st)
+        return final_text or rendered_text or "No response content received."
+
+
+def compute_timeout_seconds(kwargs: dict[str, Any]) -> float:
+    """Determine the execution timeout for agent runs.
+
+    Args:
+        kwargs: Dictionary containing execution parameters, including timeout.
+
+    Returns:
+        The timeout value in seconds, defaulting to DEFAULT_AGENT_RUN_TIMEOUT
+        if not specified in kwargs.
+    """
+    return kwargs.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)

glaip_sdk/config/constants.py

@@ -5,7 +5,7 @@ Authors:
 """
 
 # Default language model configuration
-DEFAULT_MODEL = "gpt-4.1"
+DEFAULT_MODEL = "gpt-5-nano"
 DEFAULT_AGENT_RUN_TIMEOUT = 300
 
 # User agent and version
@@ -36,3 +36,6 @@ DEFAULT_TOOL_VERSION = "1.0"
 # MCP creation/update constants
 DEFAULT_MCP_TYPE = "server"
 DEFAULT_MCP_TRANSPORT = "stdio"
+
+# Default error messages
+DEFAULT_ERROR_MESSAGE = "Unknown error"

glaip_sdk/exceptions.py

@@ -26,6 +26,15 @@ class APIError(AIPError):
         payload: Any = None,
         request_id: str | None = None,
     ):
+        """Initialize the API error.
+
+        Args:
+            message: The error message
+            status_code: HTTP status code
+            error_type: Type of error
+            payload: Additional error payload
+            request_id: Request identifier
+        """
         super().__init__(message)
         self.status_code = status_code
         self.error_type = error_type
@@ -91,6 +100,12 @@ class AgentTimeoutError(TimeoutError):
     """Agent execution timeout with specific duration information."""
 
     def __init__(self, timeout_seconds: float, agent_name: str = None):
+        """Initialize the agent timeout error.
+
+        Args:
+            timeout_seconds: The timeout duration in seconds
+            agent_name: Optional name of the agent that timed out
+        """
         agent_info = f" for agent '{agent_name}'" if agent_name else ""
         message = (
             f"Agent execution timed out after {timeout_seconds} seconds{agent_info}"

glaip_sdk/models.py

@@ -236,6 +236,11 @@ class TTYRenderer:
     """Simple TTY renderer for non-Rich environments."""
 
     def __init__(self, use_color: bool = True):
+        """Initialize the TTY renderer.
+
+        Args:
+            use_color: Whether to use color output
+        """
         self.use_color = use_color
 
     def render_message(self, message: str, event_type: str = "message") -> None:

glaip_sdk/payload_schemas/__init__.py

@@ -0,0 +1,19 @@
+"""Payload schema metadata for AIP resources.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from glaip_sdk.payload_schemas.agent import (
+    AgentImportOperation,
+    ImportFieldPlan,
+    get_import_field_plan,
+    list_server_only_fields,
+)
+
+__all__ = [
+    "AgentImportOperation",
+    "ImportFieldPlan",
+    "get_import_field_plan",
+    "list_server_only_fields",
+]

glaip_sdk/payload_schemas/agent.py

@@ -0,0 +1,87 @@
+"""Agent payload schema metadata derived from agent_payloads.md.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+
+This module encodes which agent fields are mutable, server-managed, or require
+additional sanitisation so that CLI and SDK flows can share the same rules.
+"""
+
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+AgentImportOperation = Literal["create", "update"]
+
+
+@dataclass(frozen=True)
+class FieldRule:
+    """Schema rule defining how a field should be treated."""
+
+    server_only: bool = False
+    cli_managed_create: bool = False
+    cli_managed_update: bool = False
+    requires_sanitization: bool = False
+
+
+@dataclass(frozen=True)
+class ImportFieldPlan:
+    """Plan for how an import pipeline should treat a specific field."""
+
+    copy: bool
+    sanitize: bool = False
+
+
+_DEFAULT_RULE = FieldRule()
+
+
+AGENT_FIELD_RULES: Mapping[str, FieldRule] = {
+    # Server-provided metadata (never send back)
+    "id": FieldRule(server_only=True),
+    "created_at": FieldRule(server_only=True),
+    "updated_at": FieldRule(server_only=True),
+    "deleted_at": FieldRule(server_only=True),
+    "success": FieldRule(server_only=True),
+    "message": FieldRule(server_only=True),
+    # Fields handled explicitly by CLI/SDK helpers for language model selection
+    "language_model_id": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "provider": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "model_name": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "model": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    # Fields collected via CLI flags / explicit logic
+    "name": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "instruction": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "tools": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "agents": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "mcps": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "timeout": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    # Fields requiring sanitisation before sending to the API
+    "agent_config": FieldRule(requires_sanitization=True),
+}
+
+
+def get_import_field_plan(
+    field_name: str, operation: AgentImportOperation
+) -> ImportFieldPlan:
+    """Return the import handling plan for ``field_name`` under ``operation``.
+
+    Unknown fields default to being copied as-is so new API fields propagate
+    without additional code changes.
+    """
+    rule = AGENT_FIELD_RULES.get(field_name, _DEFAULT_RULE)
+
+    if rule.server_only:
+        return ImportFieldPlan(copy=False)
+
+    if operation == "create" and rule.cli_managed_create:
+        return ImportFieldPlan(copy=False)
+
+    if operation == "update" and rule.cli_managed_update:
+        return ImportFieldPlan(copy=False)
+
+    return ImportFieldPlan(copy=True, sanitize=rule.requires_sanitization)
+
+
+def list_server_only_fields() -> Collection[str]:
+    """Expose the set of server-only fields for other tooling."""
+    return {name for name, rule in AGENT_FIELD_RULES.items() if rule.server_only}

glaip_sdk/rich_components.py

@@ -11,6 +11,12 @@ class AIPPanel(Panel):
     """Rich Panel configured without vertical borders by default."""
 
     def __init__(self, *args, **kwargs):
+        """Initialize AIPPanel with default settings for horizontal borders and padding.
+
+        Args:
+            *args: Positional arguments passed to Panel
+            **kwargs: Keyword arguments passed to Panel
+        """
         kwargs.setdefault("box", box.HORIZONTALS)
         kwargs.setdefault("padding", (0, 1))
         super().__init__(*args, **kwargs)
@@ -20,6 +26,12 @@ class AIPTable(Table):
     """Rich Table configured without vertical borders by default."""
 
     def __init__(self, *args, **kwargs):
+        """Initialize AIPTable with default settings for horizontal borders and no edge padding.
+
+        Args:
+            *args: Positional arguments passed to Table
+            **kwargs: Keyword arguments passed to Table
+        """
         kwargs.setdefault("box", box.HORIZONTALS)
         kwargs.setdefault("show_edge", False)
         kwargs.setdefault("pad_edge", False)