glaip-sdk 0.6.19__py3-none-any.whl → 0.7.27__py3-none-any.whl

glaip_sdk/models/_validation.py

@@ -0,0 +1,97 @@
+"""Model validation utility for GL AIP SDK.
+
+Validates model names in 'provider/model' format and provides
+helpful error messages for invalid formats.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+
+def _validate_model(model: str) -> str:
+    """Validate model format and deprecate bare names.
+
+    Args:
+        model: Model string to validate
+
+    Returns:
+        Normalized model string in provider/model format
+
+    Raises:
+        ValueError: If model format is invalid
+    """
+    if "/" not in model:
+        warnings.warn(
+            f"Bare model name '{model}' is deprecated. "
+            f"Use 'provider/model' format (e.g., 'openai/{model}'). "
+            f"This will be an error in v2.0. Use constants: from glaip_sdk.models import OpenAI",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return f"openai/{model}"
+
+    provider, model_name = model.split("/", 1)
+    if not provider or not model_name:
+        raise ValueError(
+            f"Invalid model format: '{model}'. "
+            f"Expected 'provider/model' format (e.g., 'openai/gpt-4o-mini'). "
+            f"Use constants: from glaip_sdk.models import OpenAI; Agent(model=OpenAI.GPT_4O_MINI)."
+        )
+    return model
+
+
+def convert_model_for_local_execution(model: str | Any) -> tuple[str, dict[str, Any]]:
+    """Convert model to aip_agents format for local execution.
+
+    Converts provider/model format appropriately for aip_agents.
+    Handles both Model objects and string models.
+
+    Args:
+        model: Model object or string identifier.
+
+    Returns:
+        Tuple of (model_string, config_dict) where:
+        - model_string: Model in format expected by aip_agents (provider/model)
+        - config_dict: Configuration dict with credentials, hyperparameters, etc.
+    """
+    from glaip_sdk.models import Model  # noqa: PLC0415
+
+    # Handle Model objects
+    if isinstance(model, Model):
+        return model.to_aip_agents_format()
+
+    # Handle string models
+    if isinstance(model, str):
+        if "/" not in model:
+            return model, {}
+
+        parts = model.split("/", 1)
+        provider = parts[0]
+        model_name = parts[1]
+
+        # Map provider to driver and get base_url from config
+        from glaip_sdk.models._provider_mappings import (  # noqa: PLC0415
+            get_base_url,
+            get_driver,
+        )
+
+        driver = get_driver(provider)
+        base_url = get_base_url(provider)
+
+        config: dict[str, Any] = {}
+        if base_url:
+            config["lm_base_url"] = base_url
+
+        # Return with driver name
+        return f"{driver}/{model_name}", config
+
+    # For other types (None, etc.), return as-is
+    return model, {}
+
+
+__all__ = ["_validate_model", "convert_model_for_local_execution"]

glaip_sdk/models/agent.py

@@ -13,9 +13,10 @@ Authors:
 from datetime import datetime
 from typing import Any
 
-from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
 from pydantic import BaseModel
 
+from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
+
 
 class AgentResponse(BaseModel):
     """Pydantic model for Agent API responses.

glaip_sdk/models/agent_runs.py

@@ -13,6 +13,7 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 
 # Type alias for SSE event dictionaries
 RunOutputChunk = dict[str, Any]
+RunStatus = Literal["started", "success", "failed", "cancelled", "aborted", "unavailable"]
 
 
 class RunSummary(BaseModel):
@@ -22,7 +23,7 @@ class RunSummary(BaseModel):
     agent_id: UUID
     run_type: Literal["manual", "schedule"]
     schedule_id: UUID | None = None
-    status: Literal["started", "success", "failed", "cancelled", "aborted", "unavailable"]
+    status: RunStatus
     started_at: datetime
     completed_at: datetime | None = None
     input: str | None = None

glaip_sdk/models/constants.py

@@ -0,0 +1,141 @@
+# pylint: disable=duplicate-code
+"""Model constants for GL AIP SDK.
+
+Typed constants for popular AI models matching AIP Server's language_models.yaml keys.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ModelProvider",
+    "OpenAI",
+    "Anthropic",
+    "Google",
+    "AzureOpenAI",
+    "DeepInfra",
+    "DeepSeek",
+    "Bedrock",
+    "DEFAULT_MODEL",
+]
+
+# Note: DeepInfra provider changed to 'openai-compatible' for aip_agents compatibility
+
+
+class ModelProvider:
+    """Supported model providers."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    AZURE_OPENAI = "azure-openai"
+    GOOGLE = "google"
+    DEEPINFRA = "deepinfra"
+    DEEPSEEK = "deepseek"
+    OPENAI_COMPATIBLE = "openai-compatible"
+    BEDROCK = "bedrock"
+
+
+class OpenAI:
+    """OpenAI model constants."""
+
+    GPT_4O_MINI = "openai/gpt-4o-mini"
+    GPT_4O = "openai/gpt-4o"
+    GPT_4_1 = "openai/gpt-4.1"
+    GPT_4_1_NANO = "openai/gpt-4.1-nano"
+    GPT_4_1_MINI = "openai/gpt-4.1-mini"
+    GPT_5 = "openai/gpt-5"
+    GPT_5_MINI = "openai/gpt-5-mini"
+    GPT_5_NANO = "openai/gpt-5-nano"
+    GPT_5_LOW = "openai/gpt-5-low"
+    GPT_5_MINIMAL = "openai/gpt-5-minimal"
+    GPT_5_MEDIUM = "openai/gpt-5-medium"
+    GPT_5_HIGH = "openai/gpt-5-high"
+    GPT_5_1 = "openai/gpt-5.1"
+    GPT_5_1_LOW = "openai/gpt-5.1-low"
+    GPT_5_1_MEDIUM = "openai/gpt-5.1-medium"
+    GPT_5_1_HIGH = "openai/gpt-5.1-high"
+    GPT_5_2 = "openai/gpt-5.2"
+    GPT_5_2_LOW = "openai/gpt-5.2-low"
+    GPT_5_2_MEDIUM = "openai/gpt-5.2-medium"
+    GPT_5_2_HIGH = "openai/gpt-5.2-high"
+    GPT_5_2_XHIGH = "openai/gpt-5.2-xhigh"
+    GPT_4O_2024_11_20 = "openai/gpt-4o-2024-11-20"
+    O4_MINI = "openai/o4-mini"
+
+
+class Anthropic:
+    """Anthropic model constants."""
+
+    CLAUDE_3_5_SONNET_LATEST = "anthropic/claude-3-5-sonnet-latest"
+    CLAUDE_3_7_SONNET_LATEST = "anthropic/claude-3-7-sonnet-latest"
+    CLAUDE_SONNET_4_0 = "anthropic/claude-sonnet-4-0"
+    CLAUDE_OPUS_4_0 = "anthropic/claude-opus-4-0"
+    CLAUDE_OPUS_4_1 = "anthropic/claude-opus-4-1"
+    CLAUDE_SONNET_4_5 = "anthropic/claude-sonnet-4-5"
+    # DX Alias
+    CLAUDE_3_5_SONNET = CLAUDE_3_5_SONNET_LATEST
+
+
+class Google:
+    """Google model constants."""
+
+    GEMINI_2_5_FLASH = "google/gemini-2.5-flash"
+    GEMINI_3_FLASH_PREVIEW = "google/gemini-3-flash-preview"
+    GEMINI_3_PRO_PREVIEW = "google/gemini-3-pro-preview"
+    GEMINI_2_5_PRO = "google/gemini-2.5-pro"
+
+
+class AzureOpenAI:
+    """Azure OpenAI model constants."""
+
+    GPT_4O = "azure-openai/gpt-4o"
+    GPT_4O_MINI = "azure-openai/gpt-4o-mini"
+    GPT_4_1 = "azure-openai/gpt-4.1"
+
+
+class DeepInfra:
+    """DeepInfra model constants.
+
+    Note: DeepInfra models use the openai-compatible driver internally,
+    but we expose them with the 'deepinfra/' prefix for better DX.
+    The SDK handles the mapping to 'openai-compatible/' automatically.
+    """
+
+    QWEN3_235B_A22B_INSTRUCT_2507 = "deepinfra/Qwen/Qwen3-235B-A22B-Instruct-2507"
+    KIMI_K2_INSTRUCT = "deepinfra/moonshotai/Kimi-K2-Instruct"
+    QWEN3_30B_A3B = "deepinfra/Qwen/Qwen3-30B-A3B"
+    GLM_4_5_AIR = "deepinfra/zai-org/GLM-4.5-Air"
+    QWEN3_32B = "deepinfra/Qwen/Qwen3-32B"
+    QWEN3_NEXT_80B_A3B_THINKING = "deepinfra/Qwen/Qwen3-Next-80B-A3B-Thinking"
+    QWEN3_NEXT_80B_A3B_INSTRUCT = "deepinfra/Qwen/Qwen3-Next-80B-A3B-Instruct"
+    QWEN3_14B = "deepinfra/Qwen/Qwen3-14B"
+    GLM_4_5 = "deepinfra/zai-org/GLM-4.5"
+
+
+class DeepSeek:
+    """DeepSeek model constants.
+
+    Note: DeepSeek models use the openai-compatible driver internally,
+    but we expose them with the 'deepseek/' prefix for better DX.
+    The SDK handles the mapping to 'openai-compatible/' automatically.
+    """
+
+    DEEPSEEK_CHAT = "deepseek/deepseek-chat"
+    DEEPSEEK_V3_1 = "deepseek/deepseek-ai/DeepSeek-V3.1"
+    DEEPSEEK_V3_1_TERMINUS = "deepseek/deepseek-ai/DeepSeek-V3.1-Terminus"
+
+
+class Bedrock:
+    """AWS Bedrock model constants."""
+
+    CLAUDE_SONNET_4_20250514_V1_0 = "bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0"
+    CLAUDE_3_5_HAIKU_20241022_V1_0 = "bedrock/us.anthropic.claude-3-5-haiku-20241022-v1:0"
+    CLAUDE_SONNET_4_5_20250929_V1_0 = "bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+
+    # DX Aliases
+    ANTHROPIC_CLAUDE_SONNET_4 = CLAUDE_SONNET_4_20250514_V1_0
+    ANTHROPIC_CLAUDE_3_5_HAIKU = CLAUDE_3_5_HAIKU_20241022_V1_0
+    ANTHROPIC_CLAUDE_SONNET_4_5 = CLAUDE_SONNET_4_5_20250929_V1_0
+
+
+# Default model selection
+DEFAULT_MODEL = OpenAI.GPT_5_NANO

glaip_sdk/models/model.py

@@ -0,0 +1,170 @@
+"""Model configuration class for GL AIP SDK.
+
+Provides a structured way to specify models, credentials, and hyperparameters
+for local execution.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, field_validator
+
+
+class Model(BaseModel):
+    """Model configuration class for local execution.
+
+    Bundles model identity with credentials and hyperparameters.
+    """
+
+    id: str
+    credentials: dict[str, Any] | str | None = None
+    hyperparameters: dict[str, Any] | None = None
+    base_url: str | None = None
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, v: str) -> str:
+        """Validate model ID format.
+
+        Args:
+            v: Model identifier string.
+
+        Returns:
+            Validated model identifier in 'provider/model' format.
+
+        Raises:
+            ValueError: If model format is invalid.
+        """
+        from glaip_sdk.models._validation import _validate_model  # noqa: PLC0415
+
+        return _validate_model(v)
+
+    def to_aip_agents_format(self) -> tuple[str, dict[str, Any]]:
+        """Convert Model to aip_agents format.
+
+        Converts provider/model format to driver/model format for aip_agents.
+        For custom models with base_url, uses format: openai-compatible/base_url:model_name
+
+        Returns:
+            Tuple of (model_string, agent_config_dict).
+        """
+        if "/" not in self.id:
+            return self.id, {}
+
+        parts = self.id.split("/", 1)
+        provider = parts[0]
+        model_name = parts[1]
+
+        config = self._build_agent_config(provider)
+        model_string = self._build_model_string(provider, model_name, config)
+
+        return model_string, config
+
+    def _build_agent_config(self, provider: str) -> dict[str, Any]:
+        """Build agent config dict from Model attributes.
+
+        Args:
+            provider: Provider name extracted from model id.
+
+        Returns:
+            Configuration dict with credentials, hyperparameters, and base_url.
+        """
+        config: dict[str, Any] = {}
+
+        if self.credentials:
+            if isinstance(self.credentials, str):
+                config["lm_api_key"] = self.credentials
+            elif isinstance(self.credentials, dict):
+                config["lm_credentials"] = self.credentials
+
+        if self.hyperparameters:
+            config["lm_hyperparameters"] = self.hyperparameters
+
+        base_url = self._resolve_base_url(provider)
+        if base_url:
+            config["lm_base_url"] = base_url
+
+        return config
+
+    def _resolve_base_url(self, provider: str) -> str | None:
+        """Resolve base URL for the provider.
+
+        Uses centralized provider configurations to determine base_url.
+        Users can override by explicitly setting base_url attribute.
+
+        Args:
+            provider: Provider name from model ID (e.g., "deepinfra").
+
+        Returns:
+            Base URL string or None.
+
+        Examples:
+            >>> model = Model(id="deepinfra/Qwen/Qwen3-30B")
+            >>> model._resolve_base_url("deepinfra")
+            "https://api.deepinfra.com/v1/openai"
+        """
+        if self.base_url:
+            return self.base_url
+
+        # Get base_url from provider config
+        from glaip_sdk.models._provider_mappings import get_base_url  # noqa: PLC0415
+
+        base_url = get_base_url(provider)
+        if base_url:
+            return base_url
+
+        return None
+
+    def _build_model_string(self, provider: str, model_name: str, config: dict[str, Any]) -> str:
+        """Build normalized model string for aip_agents.
+
+        Converts provider names to their driver implementations for local execution.
+
+        Conversion strategy:
+        1. Custom models with base_url: Use colon format (openai-compatible/{base_url}:{model_name})
+           This allows aip_agents to parse base_url and model_name separately.
+        2. Standard providers: Map to driver and use slash format (driver/{model_name})
+           aip_agents will handle provider/model format internally.
+
+        Args:
+            provider: Provider name from model ID (e.g., "deepinfra", "openai").
+            model_name: Model name after provider prefix.
+            config: Agent config dict (may contain base_url).
+
+        Returns:
+            Normalized model string in provider/model format with driver name.
+
+        Examples:
+            >>> _build_model_string("deepinfra", "Qwen/Qwen3-30B", {})
+            "openai-compatible/Qwen/Qwen3-30B"
+            >>> _build_model_string("openai", "gpt-4o", {})
+            "openai/gpt-4o"
+        """
+        from glaip_sdk.models._provider_mappings import get_driver  # noqa: PLC0415
+
+        # Map provider to driver (e.g., deepinfra → openai-compatible)
+        driver = get_driver(provider)
+
+        if provider == "custom":
+            base_url = config.get("lm_base_url")
+            if base_url:
+                return f"{driver}/{base_url}:{model_name}"
+
+        # Standard case: driver with slash format
+        # aip_agents will handle provider/model format internally
+        return f"{driver}/{model_name}"
+
+    def __repr__(self) -> str:
+        """Return string representation of Model.
+
+        Note: Credentials are masked to avoid leaking secrets in logs.
+        Hyperparameters and base_url are shown if present.
+        """
+        creds_repr = "***" if self.credentials else "None"
+        return (
+            f"Model(id={self.id!r}, "
+            f"credentials={creds_repr}, "
+            f"hyperparameters={self.hyperparameters!r}, "
+            f"base_url={self.base_url!r})"
+        )

glaip_sdk/models/schedule.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Schedule DTO models for AIP SDK.
+
+These models represent API payloads and responses. They are intentionally DTO-only
+and do not contain runtime behavior.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from glaip_sdk.models.agent_runs import RunStatus
+
+
+class ScheduleConfig(BaseModel):
+    """Cron-like schedule configuration matching backend ScheduleConfig.
+
+    All fields accept cron-style values:
+    - Specific values: "0", "9", "1"
+    - Wildcards: "*"
+    - Intervals: "*/5", "*/2"
+    - Ranges: "1-5", "9-17"
+    - Lists: "1,3,5"
+
+    Note: day_of_week uses 0-6 where 0=Monday.
+    """
+
+    minute: str = "*"
+    hour: str = "*"
+    day_of_month: str = "*"
+    month: str = "*"
+    day_of_week: str = "*"
+
+    model_config = ConfigDict(from_attributes=True)
+
+    def to_cron_string(self) -> str:
+        """Convert to standard cron string format.
+
+        Returns:
+            Cron string in format "minute hour day_of_month month day_of_week"
+        """
+        return f"{self.minute} {self.hour} {self.day_of_month} {self.month} {self.day_of_week}"
+
+    @classmethod
+    def from_cron_string(cls, cron: str) -> "ScheduleConfig":
+        """Parse a cron string into ScheduleConfig.
+
+        Args:
+            cron: Cron string in format "minute hour day_of_month month day_of_week"
+
+        Returns:
+            ScheduleConfig instance
+
+        Raises:
+            ValueError: If cron string doesn't have exactly 5 fields
+        """
+        parts = cron.split()
+        if len(parts) != 5:
+            raise ValueError(f"Invalid cron string: expected 5 fields, got {len(parts)}")
+        return cls(
+            minute=parts[0],
+            hour=parts[1],
+            day_of_month=parts[2],
+            month=parts[3],
+            day_of_week=parts[4],
+        )
+
+
+class ScheduleMetadata(BaseModel):
+    """Metadata embedded in schedule responses.
+
+    Contains the agent association, input text, and cron configuration.
+    """
+
+    agent_id: str
+    input: str
+    schedule: ScheduleConfig
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class ScheduleResponse(BaseModel):
+    """Schedule response DTO.
+
+    Attributes:
+        id: Schedule ID.
+        next_run_time: Next run time as returned by the API.
+        time_until_next_run: Human-readable duration until next run.
+        metadata: Schedule metadata.
+        created_at: Creation timestamp.
+        updated_at: Update timestamp.
+        agent_id: Agent ID derived from metadata.
+        input: Input text derived from metadata.
+        schedule_config: ScheduleConfig derived from metadata.
+    """
+
+    id: str
+    next_run_time: str | None = None
+    time_until_next_run: str | None = None
+    metadata: ScheduleMetadata | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    model_config = ConfigDict(from_attributes=True)
+
+    @property
+    def agent_id(self) -> str | None:
+        """Get the agent ID from metadata."""
+        return self.metadata.agent_id if self.metadata else None
+
+    @property
+    def input(self) -> str | None:
+        """Get the scheduled input text from metadata."""
+        return self.metadata.input if self.metadata else None
+
+    @property
+    def schedule_config(self) -> ScheduleConfig | None:
+        """Get the schedule configuration from metadata."""
+        return self.metadata.schedule if self.metadata else None
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the schedule."""
+        parts = [f"ScheduleResponse(id={self.id!r}"]
+        if self.next_run_time:
+            parts.append(f"next_run_time={self.next_run_time!r}")
+        if self.time_until_next_run:
+            parts.append(f"time_until_next_run={self.time_until_next_run!r}")
+        if self.agent_id:
+            parts.append(f"agent_id={self.agent_id!r}")
+        if self.created_at:
+            parts.append(f"created_at={self.created_at!r}")
+        return ", ".join(parts) + ")"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()
+
+
+# Type alias for SSE event dictionaries
+ScheduleRunOutputChunk = dict[str, Any]
+
+
+class ScheduleRunResponse(BaseModel):
+    """Schedule run response DTO."""
+
+    id: str
+    agent_id: str
+    schedule_id: str | None = None  # May be None for non-scheduled runs
+    status: RunStatus  # Backend uses lowercase.
+    run_type: str | None = None  # "schedule" for scheduled runs
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    input: str | None = None  # Input used for the execution.
+    config: ScheduleConfig | dict[str, str] | None = None  # Schedule config used.
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    model_config = ConfigDict(from_attributes=True, extra="ignore")
+
+    @property
+    def duration(self) -> str | None:
+        """Calculate the duration of the run.
+
+        Returns:
+            Formatted duration string (HH:MM:SS) or None if incomplete
+        """
+        if self.started_at and self.completed_at:
+            delta = self.completed_at - self.started_at
+            total_seconds = int(delta.total_seconds())
+            hours, remainder = divmod(total_seconds, 3600)
+            minutes, seconds = divmod(remainder, 60)
+            return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+        return None
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the run."""
+        parts = [f"ScheduleRunResponse(id={self.id!r}"]
+        parts.append(f"status={self.status!r}")
+        if self.started_at:
+            parts.append(f"started_at={self.started_at.isoformat()!r}")
+        if self.duration:
+            parts.append(f"duration={self.duration!r}")
+        return ", ".join(parts) + ")"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()
+
+
+class ScheduleRunResult(BaseModel):
+    """Full output payload for a schedule run.
+
+    Maps to the backend's AgentRunWithOutputResponse which includes
+    run metadata plus the output stream.
+    """
+
+    id: str
+    agent_id: str
+    schedule_id: str | None = None
+    status: RunStatus
+    run_type: str | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    input: str | None = None  # Input used for the execution.
+    config: ScheduleConfig | dict[str, str] | None = None  # Schedule config used.
+    output: list[ScheduleRunOutputChunk] | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    model_config = ConfigDict(from_attributes=True, extra="ignore")
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the result."""
+        output_count = len(self.output) if self.output else 0
+        return f"ScheduleRunResult(id={self.id!r}, status={self.status!r}, output_chunks={output_count})"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()

glaip_sdk/payload_schemas/agent.py

@@ -57,6 +57,7 @@ AGENT_FIELD_RULES: Mapping[str, FieldRule] = {
     "timeout": FieldRule(cli_managed_create=True, cli_managed_update=True),
     # Fields requiring sanitisation before sending to the API
     "agent_config": FieldRule(requires_sanitization=True),
+    "guardrail": FieldRule(requires_sanitization=True),
 }