glaip-sdk 0.0.0b99__py3-none-any.whl

glaip_sdk/utils/tool_storage_provider.py

@@ -0,0 +1,140 @@
+"""Helpers for local tool output storage setup.
+
+This module bridges agent_config.tool_output_sharing to ToolOutputManager
+for local execution without modifying aip-agents.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from gllm_core.utils import LoggerManager
+
+logger = LoggerManager().get_logger(__name__)
+
+
+def build_tool_output_manager(agent_name: str, agent_config: dict[str, Any]) -> Any | None:
+    """Build a ToolOutputManager for local tool output sharing.
+
+    Args:
+        agent_name: Name of the agent whose tool outputs will be stored.
+        agent_config: Agent configuration that may enable tool output sharing and contain task_id.
+
+    Returns:
+        A ToolOutputManager instance when tool output sharing is enabled and
+        dependencies are available, otherwise ``None``.
+    """
+    tool_output_sharing_enabled = agent_config.get("tool_output_sharing", False)
+    if not tool_output_sharing_enabled:
+        return None
+
+    try:
+        from aip_agents.storage.clients.minio_client import MinioConfig, MinioObjectStorage  # noqa: PLC0415
+        from aip_agents.storage.providers.memory import InMemoryStorageProvider  # noqa: PLC0415
+        from aip_agents.storage.providers.object_storage import ObjectStorageProvider  # noqa: PLC0415
+        from aip_agents.utils.langgraph.tool_output_management import (  # noqa: PLC0415
+            ToolOutputConfig,
+            ToolOutputManager,
+        )
+    except ImportError:
+        logger.warning("Tool output sharing requested but aip-agents is unavailable; skipping.")
+        return None
+
+    task_id = agent_config.get("task_id")
+
+    storage_provider = _build_tool_output_storage_provider(
+        agent_name=agent_name,
+        task_id=task_id,
+        minio_config_cls=MinioConfig,
+        minio_client_cls=MinioObjectStorage,
+        object_storage_provider_cls=ObjectStorageProvider,
+        memory_storage_provider_cls=InMemoryStorageProvider,
+    )
+    tool_output_config = _build_tool_output_config(storage_provider, ToolOutputConfig)
+    return ToolOutputManager(tool_output_config)
+
+
+def _build_tool_output_storage_provider(
+    agent_name: str,
+    task_id: str | None,
+    minio_config_cls: Any,
+    minio_client_cls: Any,
+    object_storage_provider_cls: Any,
+    memory_storage_provider_cls: Any,
+) -> Any:
+    """Create a storage provider for tool output sharing.
+
+    Args:
+        agent_name: Name of the agent whose tool outputs are stored.
+        task_id: Optional task identifier for coordination context.
+        minio_config_cls: Class exposing a ``from_env`` constructor for MinIO config.
+        minio_client_cls: MinIO client class used to talk to the object store.
+        object_storage_provider_cls: Storage provider wrapping the MinIO client.
+        memory_storage_provider_cls: In-memory provider used as a fallback.
+
+    Returns:
+        An instance of ``object_storage_provider_cls`` when MinIO initialization
+        succeeds, otherwise an instance of ``memory_storage_provider_cls``.
+    """
+    try:
+        config_obj = minio_config_cls.from_env()
+        minio_client = minio_client_cls(config=config_obj)
+        prefix = _build_tool_output_prefix(agent_name, task_id)
+        return object_storage_provider_cls(client=minio_client, prefix=prefix, use_json=False)
+    except Exception as exc:
+        logger.warning("Failed to initialize MinIO for tool outputs: %s. Using in-memory storage.", exc)
+        return memory_storage_provider_cls()
+
+
+def _build_tool_output_prefix(agent_name: str, task_id: str | None) -> str:
+    """Build object storage prefix for tool outputs in local mode.
+
+    Args:
+        agent_name: Name of the agent whose outputs are stored.
+        task_id: Optional task identifier for coordination context.
+
+    Returns:
+        Object storage key prefix dedicated to the provided agent.
+    """
+    if task_id:
+        return f"tool-outputs/tasks/{task_id}/agents/{agent_name}/"
+    return f"tool-outputs/agents/{agent_name}/"
+
+
+def _build_tool_output_config(storage_provider: Any, config_cls: Any) -> Any:
+    """Build ToolOutputConfig using env vars, with safe defaults.
+
+    Args:
+        storage_provider: Provider that will persist tool outputs.
+        config_cls: Tool output configuration class to instantiate.
+
+    Returns:
+        A configured ``config_cls`` instance ready for ToolOutputManager use.
+    """
+
+    def safe_int_conversion(env_var: str, default: str) -> int:
+        """Convert an environment variable to int with a fallback default.
+
+        Args:
+            env_var: Environment variable name to read.
+            default: Default string value used when parsing fails.
+
+        Returns:
+            Integer representation of the environment variable or the default.
+        """
+        try:
+            return int(os.getenv(env_var, default))
+        except (ValueError, TypeError):
+            logger.warning("Invalid value for %s, using default: %s", env_var, default)
+            return int(default)
+
+    return config_cls(
+        max_stored_outputs=safe_int_conversion("TOOL_OUTPUT_MAX_STORED", "200"),
+        max_age_minutes=safe_int_conversion("TOOL_OUTPUT_MAX_AGE_MINUTES", str(24 * 60)),
+        cleanup_interval=safe_int_conversion("TOOL_OUTPUT_CLEANUP_INTERVAL", "50"),
+        storage_provider=storage_provider,
+    )

glaip_sdk/utils/validation.py

@@ -0,0 +1,264 @@
+"""Validation utilities for resource names, timeouts, and other constraints.
+
+This module provides pure validation functions that raise ValueError for invalid
+inputs. CLI layer wraps these with click.ClickException for user-friendly errors.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import re
+from pathlib import Path
+from typing import Any
+
+from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
+from glaip_sdk.utils.resource_refs import validate_name_format
+
+# Constants for validation
+RESERVED_NAMES = ["admin", "root", "system", "api", "test", "demo"]
+
+
+def _validate_named_resource(name: str, resource_type: str) -> str:
+    """Shared validator that prevents reserved-name duplication."""
+    cleaned_name = validate_name_format(name, resource_type)
+
+    if cleaned_name.lower() in RESERVED_NAMES:
+        raise ValueError(f"{resource_type.capitalize()} name '{cleaned_name}' is reserved and cannot be used")
+
+    return cleaned_name
+
+
+def validate_agent_name(name: str) -> str:
+    """Validate agent name and return cleaned version.
+
+    Args:
+        name: Agent name to validate
+
+    Returns:
+        Cleaned agent name
+
+    Raises:
+        ValueError: If name is invalid
+    """
+    return _validate_named_resource(name, "agent")
+
+
+def validate_agent_instruction(instruction: str) -> str:
+    """Validate agent instruction and return cleaned version.
+
+    Args:
+        instruction: Agent instruction to validate
+
+    Returns:
+        Cleaned agent instruction
+
+    Raises:
+        ValueError: If instruction is invalid
+    """
+    if not instruction or not instruction.strip():
+        raise ValueError("Agent instruction cannot be empty or whitespace")
+
+    cleaned_instruction = instruction.strip()
+
+    if len(cleaned_instruction) > 100000:
+        raise ValueError("Agent instruction cannot be longer than 100,000 characters")
+
+    return cleaned_instruction
+
+
+def validate_tool_name(name: str) -> str:
+    """Validate tool name and return cleaned version.
+
+    Args:
+        name: Tool name to validate
+
+    Returns:
+        Cleaned tool name
+
+    Raises:
+        ValueError: If name is invalid
+    """
+    return _validate_named_resource(name, "tool")
+
+
+def validate_mcp_name(name: str) -> str:
+    """Validate MCP name and return cleaned version.
+
+    Args:
+        name: MCP name to validate
+
+    Returns:
+        Cleaned MCP name
+
+    Raises:
+        ValueError: If name is invalid
+    """
+    return _validate_named_resource(name, "mcp")
+
+
+def validate_timeout(timeout: int) -> int:
+    """Validate timeout value.
+
+    Args:
+        timeout: Timeout value in seconds
+
+    Returns:
+        Validated timeout value
+
+    Raises:
+        ValueError: If timeout is invalid
+    """
+    if timeout < 1:
+        raise ValueError("Timeout must be at least 1 second")
+
+    if timeout > 3600:  # 1 hour max
+        raise ValueError("Timeout cannot be longer than 1 hour (3600 seconds)")
+
+    return timeout
+
+
+def coerce_timeout(value: Any) -> int:
+    """Coerce timeout value to integer, handling various input types.
+
+    Args:
+        value: The timeout value to coerce (int, float, str, etc.)
+
+    Returns:
+        Integer timeout value
+
+    Raises:
+        ValueError: If value cannot be coerced to valid timeout
+
+    Examples:
+        coerce_timeout(300) -> 300
+        coerce_timeout(300.0) -> 300
+        coerce_timeout("300") -> 300
+        coerce_timeout(None) -> 300  # Uses DEFAULT_AGENT_RUN_TIMEOUT
+    """
+    if value is None:
+        return DEFAULT_AGENT_RUN_TIMEOUT
+    elif isinstance(value, int):
+        return validate_timeout(value)
+    elif isinstance(value, float):
+        if value.is_integer():
+            return validate_timeout(int(value))
+        return validate_timeout(int(value))  # Truncate if not integer
+    elif isinstance(value, str):
+        try:
+            fval = float(value)
+            return validate_timeout(int(fval))
+        except ValueError as err:
+            raise ValueError(f"Invalid timeout value: {value}") from err
+    else:
+        try:
+            return validate_timeout(int(value))
+        except (TypeError, ValueError) as err:
+            raise ValueError(f"Invalid timeout value: {value}") from err
+
+
+def validate_file_path(file_path: str | Path, must_exist: bool = True) -> Path:
+    """Validate file path.
+
+    Args:
+        file_path: File path to validate
+        must_exist: Whether file must exist
+
+    Returns:
+        Path object
+
+    Raises:
+        ValueError: If file path is invalid
+    """
+    path = Path(file_path)
+
+    if must_exist and not path.exists():
+        raise ValueError(f"File does not exist: {file_path}")
+
+    if must_exist and not path.is_file():
+        raise ValueError(f"Path is not a file: {file_path}")
+
+    return path
+
+
+def validate_directory_path(dir_path: str | Path, must_exist: bool = True) -> Path:
+    """Validate directory path.
+
+    Args:
+        dir_path: Directory path to validate
+        must_exist: Whether directory must exist
+
+    Returns:
+        Path object
+
+    Raises:
+        ValueError: If directory path is invalid
+    """
+    path = Path(dir_path)
+
+    if must_exist and not path.exists():
+        raise ValueError(f"Directory does not exist: {dir_path}")
+
+    if must_exist and not path.is_dir():
+        raise ValueError(f"Path is not a directory: {dir_path}")
+
+    return path
+
+
+def validate_url(url: str) -> str:
+    """Validate URL format (HTTPS only).
+
+    Args:
+        url: URL to validate
+
+    Returns:
+        Validated URL
+
+    Raises:
+        ValueError: If URL is invalid
+    """
+    url_pattern = re.compile(
+        r"^https://"  # https:// only
+        r"(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+[A-Z]{2,6}\.?|"  # domain...
+        r"localhost|"  # localhost...
+        r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})"  # ...or ip
+        r"(?::\d+)?"  # optional port
+        r"(?:/?|[/?]\S+)$",
+        re.IGNORECASE,
+    )
+
+    if not url_pattern.match(url):
+        raise ValueError("API URL must start with https:// and be a valid host.")
+
+    return url
+
+
+def validate_api_key(api_key: str) -> str:
+    """Validate API key format.
+
+    Args:
+        api_key: API key to validate
+
+    Returns:
+        Validated API key
+
+    Raises:
+        ValueError: If API key is invalid
+    """
+    if not api_key or not api_key.strip():
+        raise ValueError("API key cannot be empty")
+
+    cleaned_key = api_key.strip()
+
+    if len(cleaned_key) < 10:
+        raise ValueError("API key appears to be too short")
+
+    if len(cleaned_key) > 200:
+        raise ValueError("API key appears to be too long")
+
+    # Check for potentially invalid characters
+    if not re.match(r"^[a-zA-Z0-9_-]+$", cleaned_key):
+        raise ValueError(
+            "API key contains invalid characters. Only letters, numbers, hyphens, and underscores are allowed."
+        )
+
+    return cleaned_key

glaip_sdk-0.0.0b99.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: glaip-sdk
+Version: 0.0.0b99
+Summary: Python SDK and CLI for GL AIP (GDP Labs AI Agent Package) - Build, run, and manage AI agents
+Author-email: Raymond Christopher <raymond.christopher@gdplabs.id>
+License: MIT
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: python-dotenv<2.0.0,>=1.1.1
+Requires-Dist: readchar<5.0.0,>=4.2.1
+Requires-Dist: questionary<3.0.0,>=2.1.0
+Requires-Dist: click<8.3.0,>=8.2.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: packaging>=23.2
+Requires-Dist: textual>=0.52.0
+Requires-Dist: gllm-core-binary>=0.1.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: gllm-tools-binary>=0.1.3
+Provides-Extra: local
+Requires-Dist: aip-agents-binary[local]>=0.5.18; (python_version >= "3.11" and python_version < "3.13") and extra == "local"
+Provides-Extra: memory
+Requires-Dist: aip-agents-binary[memory]>=0.5.18; (python_version >= "3.11" and python_version < "3.13") and extra == "memory"
+Provides-Extra: privacy
+Requires-Dist: aip-agents-binary[privacy]>=0.5.18; (python_version >= "3.11" and python_version < "3.13") and extra == "privacy"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-dotenv>=0.5.2; extra == "dev"
+Requires-Dist: pre-commit>=4.3.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.6; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
+Requires-Dist: ruff>=0.14.0; extra == "dev"
+
+# GL AIP — GDP Labs AI Agents Package
+
+[![Python 3.11-3.12](https://img.shields.io/badge/python-3.11--3.12-blue.svg)](https://www.python.org/downloads/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+GL stands for **GDP Labs**—GL AIP is our AI Agents Package for building, running, and operating agents.
+
+> **Python SDK and CLI for GL AIP - Connect, configure, and manage AI agents on the GDP Labs AI Agents Package.**
+
+## 🚀 Quick Start
+
+### Installation
+
+Installing `glaip-sdk` provides both the **Python SDK** and the **`aip` CLI command** in a single package.
+
+```bash
+# Using pip (recommended)
+pip install --upgrade glaip-sdk
+
+# Using uv (fast alternative)
+uv tool install glaip-sdk
+
+# Using pipx (CLI-focused, isolated environment)
+pipx install glaip-sdk
+```
+
+**Requirements**: Python 3.11 or 3.12
+
+**Updating**: The `aip` CLI automatically detects your installation method and uses the correct update command:
+
+- If installed via `pip`: Uses `pip install --upgrade glaip-sdk`
+- If installed via `uv tool install`: Uses `uv tool install --upgrade glaip-sdk`
+- You can also update manually using the same command you used to install
+
+## 🐍 Hello World - Python SDK
+
+Perfect for building applications and integrations.
+
+### Step 1: Environment Setup
+
+Create a `.env` file:
+
+```bash
+# .env
+AIP_API_URL=https://your-gl-aip-instance.com
+AIP_API_KEY=your-api-key
+```
+
+### Step 2: Basic Python Script
+
+```python
+# hello_world.py
+from glaip_sdk import Client
+import os
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Initialize client
+client = Client()
+
+# Create a simple agent
+agent = client.agents.create(
+    name="hello-sdk",
+    instruction="You are a helpful assistant who responds clearly and concisely."
+)
+
+# Run the agent
+result = agent.run("Hello world, what's 2+2?")
+
+print(f"Agent response: {result}")
+```
+
+### Step 3: Run Your Script
+
+```bash
+python hello_world.py
+```
+
+### Step 4: Advanced Example with Streaming
+
+```python
+# streaming_example.py
+from glaip_sdk import Client
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+client = Client()
+
+# Create agent with streaming
+agent = client.agents.create(
+    name="streaming-agent",
+    instruction="You are a helpful assistant. Provide detailed responses."
+)
+
+# Stream the response
+print("Streaming response:")
+client.agents.run_agent(
+    agent.id,
+    "Explain quantum computing in simple terms",
+    verbose=True,
+)
+print("--- Stream complete ---")
+```
+
+🎉 **SDK Success!** You're now ready to build AI-powered applications with Python.
+
+______________________________________________________________________
+
+## 💻 Hello World - CLI
+
+Perfect for quick testing and command-line workflows.
+
+### Step 1: Configure Connection
+
+```bash
+# Interactive setup (recommended)
+aip configure
+```
+
+Or set environment variables:
+
+```bash
+export AIP_API_URL="https://your-gl-aip-instance.com"
+export AIP_API_KEY="your-api-key"
+```
+
+### Step 2: Verify Connection
+
+```bash
+aip status
+```
+
+### Step 3: Create & Run Your First Agent
+
+```bash
+# Create a simple agent
+aip agents create --name "hello-cli" --instruction "You are a helpful assistant"
+
+# List agents to get the ID
+aip agents list
+
+# Run the agent with input
+aip agents run <AGENT_ID> --input "Hello world, what's the weather like?"
+```
+
+🎉 **CLI Success!** You're now ready to use the CLI for AI agent workflows.
+
+## ✨ Key Features
+
+- **🤖 Agent Management**: Create, run, and orchestrate AI agents with custom instructions and streaming
+- **🧠 Language Models**: Choose from multiple AI models per agent with manual PII tag mapping
+- **🛠️ Tool Integration**: Extend agents with custom Python tools and script management
+- **🔌 MCP Support**: Connect external services through Model Context Protocols with tool discovery
+- **🔄 Multi-Agent Patterns**: Hierarchical, parallel, sequential, router, and aggregator patterns
+- **💻 Modern CLI**: Rich terminal interface with fuzzy search and multiple output formats
+
+## 🌳 Live Steps Panel
+
+The CLI steps panel now streams a fully hierarchical tree so you can audit complex agent runs without leaving the terminal.
+
+- Renders parent/child relationships with `│├└` connectors, even when events arrive out of order
+- Marks running steps with spinners and duration badges sourced from SSE metadata before local fallbacks
+- Highlights failures inline (`✗ reason`) and raises warning glyphs on affected delegate branches
+- Derives deterministic “💭 Thinking…” spans before/after each delegate or tool action to show scheduling gaps
+- Flags parallel work with a dedicated glyph and argument-derived labels so simultaneous tool calls stay readable
+- Try it locally: `poetry run python scripts/replay_steps_log.py --transcript tests/fixtures/rendering/transcripts/parallel_research.jsonl --output /tmp/parallel.log`
+
+## 📚 Documentation
+
+📖 **[Complete Documentation](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/overview)** - Visit our GitBook for comprehensive guides, tutorials, and API reference.
+
+Quick links:
+
+- **[Quick Start Guide](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/get-started/quick-start-guide)**: Get your first agent running in 5 minutes
+- **[Agent Management](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/guides/agents-guide)**: Complete agent lifecycle management
+- **[Custom Tools](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/guides/tools-guide)**: Build and integrate custom tools
+- **[MCP Integration](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/guides/mcps-guide)**: Connect external services
+- **[API Reference](https://gdplabs.gitbook.io/gl-aip/gl-aip-sdk/reference/python-sdk-reference)**: Complete SDK reference
+
+## 🧪 Simulate the Update Notifier
+
+Need to verify the in-session upgrade flow without hitting PyPI or actually running `pip install`? Use the bundled helper:
+
+```bash
+cd python/glaip-sdk
+poetry run python scripts/mock_update_notifier.py
+# or customize the mock payload:
+# poetry run python scripts/mock_update_notifier.py --version 3.3.3 --marker "[nightly build]"
+```
+
+The script:
+
+- Launches a SlashSession with prompt-toolkit disabled (so it runs cleanly in tests/CI).
+- Forces the notifier to believe a newer version exists (`--version 9.9.9` by default).
+- Appends a visible marker (default `[mock update]`) to the banner so you can prove the branding reload happened; pass `--marker ""` to skip.
+- Auto-selects “Update now”, mocks the install step, and runs the real branding refresh logic.
+- Resets module metadata afterwards so your environment remains untouched.
+
+You should see the Rich banner re-render with the mocked version (and optional marker) at the end of the run.