erdo 0.1.31__py3-none-any.whl

erdo/formatting.py

@@ -0,0 +1,279 @@
+"""Output formatting helpers for bot invocations.
+
+This module provides utilities to parse and format bot invocation events
+into human-readable output. Use these for displaying invocation results
+in terminals, scripts, or other user-facing contexts.
+
+Example:
+    >>> from erdo import invoke
+    >>> from erdo.formatting import format_invocation
+    >>>
+    >>> response = invoke("my_agent", messages=[...])
+    >>> print(format_invocation(response))
+    Bot: my agent
+    Invocation ID: abc-123
+
+    Result:
+    The answer is 4
+
+    >>> # Verbose mode shows steps
+    >>> print(format_invocation(response, verbose=True))
+    Bot: my agent
+    Invocation ID: abc-123
+
+    Steps:
+      ✓ step1 (utils.echo)
+      ✓ step2 (llm.message)
+
+    Result:
+    The answer is 4
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class StepInfo:
+    """Information about a single step execution."""
+
+    key: str
+    action: str
+    status: str = "completed"
+
+
+@dataclass
+class InvocationSummary:
+    """Structured summary of a bot invocation.
+
+    This provides a clean, parsed view of the invocation events
+    with key information extracted and organized.
+    """
+
+    bot_name: Optional[str] = None
+    bot_key: Optional[str] = None
+    invocation_id: Optional[str] = None
+    steps: List[StepInfo] = field(default_factory=list)
+    result: Optional[Any] = None
+    error: Optional[str] = None
+    success: bool = True
+
+
+def parse_invocation_events(
+    events: List[Dict[str, Any]],
+    bot_key: Optional[str] = None,
+    invocation_id: Optional[str] = None,
+) -> InvocationSummary:
+    """Parse raw invocation events into a structured summary.
+
+    Args:
+        events: List of event dictionaries from the backend
+        bot_key: Bot key to use as fallback if not in events
+        invocation_id: Invocation ID to use as fallback if not in events
+
+    Returns:
+        InvocationSummary with parsed information
+
+    Example:
+        >>> summary = parse_invocation_events(response.events, bot_key="my_agent")
+        >>> print(summary.bot_name)
+        'my agent'
+        >>> print(summary.steps)
+        [StepInfo(key='step1', action='utils.echo', status='completed')]
+    """
+    summary = InvocationSummary(
+        bot_key=bot_key,
+        invocation_id=invocation_id,
+    )
+
+    steps_seen = set()
+    final_messages = []
+
+    for event in events:
+        # Events are dicts with 'payload' and 'metadata'
+        payload = event.get("payload", {})
+        metadata = event.get("metadata", {})
+
+        # Extract invocation ID if not set
+        if summary.invocation_id is None:
+            if "invocation_id" in payload:
+                summary.invocation_id = payload["invocation_id"]
+            elif "invocation_id" in metadata:
+                summary.invocation_id = metadata["invocation_id"]
+
+        # Extract bot name
+        if summary.bot_name is None and "bot_name" in payload:
+            summary.bot_name = payload["bot_name"]
+
+        # Track step execution
+        if "action_type" in payload and "key" in payload:
+            step_key = payload["key"]
+            # Only add if not already present (avoid duplicates)
+            if step_key not in steps_seen:
+                steps_seen.add(step_key)
+                summary.steps.append(
+                    StepInfo(
+                        key=step_key,
+                        action=payload["action_type"],
+                        status="completed",
+                    )
+                )
+
+        # Collect user-visible text messages (final output)
+        if isinstance(payload, str) and metadata.get("user_visibility") == "visible":
+            if metadata.get("message_content_id"):  # It's part of a message
+                final_messages.append(payload)
+
+    # Combine final messages into result
+    if final_messages:
+        summary.result = "".join(final_messages)
+
+    return summary
+
+
+def format_invocation(
+    response: Any,
+    mode: str = "text",
+    verbose: bool = False,
+) -> str:
+    """Format a bot invocation response for display.
+
+    Args:
+        response: InvokeResult from invoke()
+        mode: Output mode - 'text' or 'json'
+        verbose: Show detailed step execution (only applies to text mode)
+
+    Returns:
+        Formatted string ready to print
+
+    Example:
+        >>> from erdo import invoke
+        >>> from erdo.formatting import format_invocation
+        >>>
+        >>> response = invoke("my_agent", messages=[...])
+        >>>
+        >>> # Simple text output
+        >>> print(format_invocation(response))
+        >>>
+        >>> # Verbose text output (shows steps)
+        >>> print(format_invocation(response, verbose=True))
+        >>>
+        >>> # JSON output
+        >>> print(format_invocation(response, mode='json'))
+    """
+    if mode == "json":
+        return _format_as_json(response)
+    else:
+        return _format_as_text(response, verbose)
+
+
+def _format_as_json(response: Any) -> str:
+    """Format response as JSON."""
+    output = {
+        "success": response.success,
+        "invocation_id": response.invocation_id,
+        "result": response.result,
+        "error": response.error,
+        "events": response.events,
+    }
+    return json.dumps(output, indent=2)
+
+
+def _format_as_text(response: Any, verbose: bool = False) -> str:
+    """Format response as human-readable text."""
+    # Get bot key from response if available
+    bot_key = getattr(response, "bot_id", None)
+    invocation_id = response.invocation_id
+
+    # Parse events to extract information
+    # Handle SDK response structure: response.result may contain {'events': [...]}
+    events_to_process = response.events
+    if isinstance(response.result, dict) and "events" in response.result:
+        events_to_process = response.result["events"]
+
+    summary = parse_invocation_events(
+        events_to_process,
+        bot_key=bot_key,
+        invocation_id=invocation_id,
+    )
+
+    # Build output
+    lines = []
+
+    if not response.success:
+        lines.append(f"❌ Invocation failed: {response.error}")
+        return "\n".join(lines)
+
+    # Header
+    lines.append(f"Bot: {summary.bot_name or summary.bot_key or 'unknown'}")
+    lines.append(f"Invocation ID: {summary.invocation_id or 'N/A'}")
+
+    # Steps (verbose mode)
+    if verbose and summary.steps:
+        lines.append("")
+        lines.append("Steps:")
+        for step in summary.steps:
+            status_icon = "✓" if step.status == "completed" else "•"
+            lines.append(f"  {status_icon} {step.key} ({step.action})")
+
+    # Result
+    if summary.result:
+        lines.append("")
+        lines.append("Result:")
+
+        # Try to parse as JSON for pretty printing
+        try:
+            parsed = json.loads(summary.result)
+            lines.append(json.dumps(parsed, indent=2))
+        except (json.JSONDecodeError, TypeError):
+            # If not JSON, print as is
+            lines.append(summary.result)
+    elif response.result is not None:
+        lines.append("")
+        lines.append("Result:")
+        if isinstance(response.result, (dict, list)):
+            lines.append(json.dumps(response.result, indent=2))
+        else:
+            lines.append(str(response.result))
+
+    return "\n".join(lines)
+
+
+# Convenience method to add to InvokeResult
+def add_format_method():
+    """Add format() method to InvokeResult class.
+
+    This is called during SDK initialization to add the format()
+    method to InvokeResult instances.
+    """
+    try:
+        from .invoke.invoke import InvokeResult
+
+        def format_method(self, mode="text", verbose=False):
+            """Format this invocation result for display.
+
+            Args:
+                mode: 'text' or 'json'
+                verbose: Show step details (text mode only)
+
+            Returns:
+                Formatted string
+
+            Example:
+                >>> response = invoke("my_agent", messages=[...])
+                >>> print(response.format())
+                >>> print(response.format(verbose=True))
+            """
+            return format_invocation(self, mode=mode, verbose=verbose)
+
+        # Add method to class
+        InvokeResult.format = format_method
+
+    except ImportError:
+        # InvokeResult not available, skip
+        pass
+
+
+# Auto-add format method on import
+add_format_method()

erdo/install_cli.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Post-install script to download Erdo CLI binary from GitHub releases."""
+
+import os
+import platform
+import shutil
+import urllib.request
+from pathlib import Path
+
+
+def get_platform_info():
+    """Get platform and architecture information."""
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    # Normalize architecture names
+    if machine in ["x86_64", "amd64"]:
+        arch = "amd64"
+    elif machine in ["aarch64", "arm64"]:
+        arch = "arm64"
+    else:
+        raise RuntimeError(f"Unsupported architecture: {machine}")
+
+    # Map platform names
+    if system == "darwin":
+        platform_name = "darwin"
+    elif system == "linux":
+        platform_name = "linux"
+    elif system == "windows":
+        platform_name = "windows"
+    else:
+        raise RuntimeError(f"Unsupported platform: {system}")
+
+    return platform_name, arch
+
+
+def get_download_url(version="latest"):
+    """Get the download URL for the CLI binary."""
+    platform_name, arch = get_platform_info()
+
+    # Construct the binary name based on GoReleaser naming convention
+    if platform_name == "windows":
+        binary_name = f"erdo-cli_Windows_{arch}.zip"
+    else:
+        # For Unix-like systems, use tar.gz
+        if arch == "amd64":
+            arch_name = "x86_64"
+        else:
+            arch_name = arch
+
+        platform_title = platform_name.title()
+        binary_name = f"erdo-cli_{platform_title}_{arch_name}.tar.gz"
+
+    base_url = "https://github.com/erdoai/homebrew-tap/releases"
+    if version == "latest":
+        return f"{base_url}/latest/download/{binary_name}"
+    else:
+        return f"{base_url}/download/{version}/{binary_name}"
+
+
+def download_and_install_cli():
+    """Download and install the CLI binary."""
+    try:
+        # Get the installation directory
+        package_dir = Path(__file__).parent
+        bin_dir = package_dir / "bin"
+        bin_dir.mkdir(exist_ok=True)
+
+        platform_name, arch = get_platform_info()
+
+        # Determine the final binary name
+        if platform_name == "windows":
+            binary_name = "erdo.exe"
+        else:
+            binary_name = "erdo"
+
+        binary_path = bin_dir / binary_name
+
+        # Skip if binary already exists
+        if binary_path.exists():
+            print(f"Erdo CLI already installed at {binary_path}")
+            return
+
+        print("Downloading Erdo CLI...")
+        download_url = get_download_url()
+
+        # Download the archive
+        archive_path = bin_dir / "erdo-cli-archive"
+        urllib.request.urlretrieve(download_url, archive_path)
+
+        # Extract the binary
+        if platform_name == "windows":
+            import zipfile
+
+            with zipfile.ZipFile(archive_path, "r") as zip_ref:
+                # Extract erdo.exe from the zip
+                for file_info in zip_ref.filelist:
+                    if file_info.filename.endswith("erdo.exe"):
+                        with (
+                            zip_ref.open(file_info) as source,
+                            open(binary_path, "wb") as target,
+                        ):
+                            shutil.copyfileobj(source, target)
+                        break
+        else:
+            import tarfile
+
+            with tarfile.open(archive_path, "r:gz") as tar_ref:
+                # Extract erdo binary from the tar.gz
+                for member in tar_ref.getmembers():
+                    if member.name.endswith("/erdo") or member.name == "erdo":
+                        with (
+                            tar_ref.extractfile(member) as source,
+                            open(binary_path, "wb") as target,
+                        ):
+                            shutil.copyfileobj(source, target)
+                        break
+
+        # Make executable on Unix-like systems
+        if platform_name != "windows":
+            os.chmod(binary_path, 0o755)
+
+        # Clean up the archive
+        archive_path.unlink()
+
+        print(f"✓ Erdo CLI installed to {binary_path}")
+
+        # Add to PATH instructions
+        print("\nTo use the CLI globally, add the following to your PATH:")
+        print(f'export PATH="{bin_dir}:$PATH"')
+
+    except Exception as e:
+        print(f"Warning: Failed to download Erdo CLI: {e}")
+        print(
+            "You can manually download it from: https://github.com/erdoai/homebrew-tap/releases"
+        )
+
+
+if __name__ == "__main__":
+    download_and_install_cli()

erdo/integrations.py

@@ -0,0 +1,131 @@
+# Integration base classes for defining integration configurations in Python
+"""
+Integration configuration framework for defining integration configs alongside agents.
+
+This module provides base classes for defining integration configurations in Python,
+which can then be synced to the backend alongside agents.
+"""
+
+from typing import Any, Dict, Optional
+
+from ._generated.types import IntegrationConfig, IntegrationDefinition
+
+
+# Helper function to create integration configurations
+def create_integration_config(**kwargs) -> IntegrationConfig:
+    """Create an IntegrationConfig with the provided parameters."""
+    # Extract metadata
+    source = kwargs.pop("source", "python")
+    file_path = kwargs.pop("file_path", None)
+
+    # Create IntegrationDefinition with remaining parameters
+    definition = IntegrationDefinition(**kwargs)
+
+    return IntegrationConfig(definition=definition, source=source, file_path=file_path)
+
+
+# Base class that acts like IntegrationConfig but handles initialization better
+class IntegrationConfigClass:
+    """Base class for integration configurations using auto-generated types."""
+
+    def __init__(self, **kwargs):
+        """Initialize with integration definition parameters."""
+        # Extract metadata
+        self._source = kwargs.pop("source", "python")
+        self._file_path = kwargs.pop("file_path", None)
+
+        # Create the definition with remaining kwargs
+        self._definition = IntegrationDefinition(**kwargs)
+
+        # Create the actual IntegrationConfig instance
+        self._config = IntegrationConfig(
+            definition=self._definition, source=self._source, file_path=self._file_path
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for syncing to backend."""
+        return self._config.to_dict()
+
+    @property
+    def definition(self) -> IntegrationDefinition:
+        """Access the underlying definition."""
+        return self._definition
+
+    @property
+    def config(self) -> IntegrationConfig:
+        """Access the underlying IntegrationConfig."""
+        return self._config
+
+
+# Helper functions for common credential schemas
+def oauth_credential_schema() -> Dict[str, Any]:
+    """Helper to create standard OAuth credential schema"""
+    return {
+        "access_token": {
+            "type": "string",
+            "description": "OAuth access token",
+            "required": True,
+            "source": "integration_credentials",
+        },
+        "refresh_token": {
+            "type": "string",
+            "description": "OAuth refresh token",
+            "required": False,
+            "source": "integration_credentials",
+        },
+    }
+
+
+def database_credential_schema() -> Dict[str, Any]:
+    """Helper to create standard database credential schema"""
+    return {
+        "host": {
+            "type": "string",
+            "description": "Database host",
+            "required": True,
+            "source": "integration_credentials",
+        },
+        "port": {
+            "type": "string",
+            "description": "Database port",
+            "required": True,
+            "source": "integration_credentials",
+        },
+        "database": {
+            "type": "string",
+            "description": "Database name",
+            "required": True,
+            "source": "integration_credentials",
+        },
+        "username": {
+            "type": "string",
+            "description": "Database username",
+            "required": True,
+            "source": "integration_credentials",
+        },
+        "password": {
+            "type": "string",
+            "description": "Database password",
+            "required": True,
+            "source": "integration_credentials",
+        },
+    }
+
+
+def api_key_credential_schema(
+    key_name: str = "api_key", header_name: Optional[str] = None
+) -> Dict[str, Any]:
+    """Helper to create standard API key credential schema"""
+    schema = {
+        key_name: {
+            "type": "string",
+            "description": "API Key for authentication",
+            "required": True,
+            "source": "integration_credentials",
+        }
+    }
+
+    if header_name:
+        schema[key_name]["header"] = header_name
+
+    return schema

erdo/invoke/__init__.py

@@ -0,0 +1,11 @@
+"""Invoke module for running agents via the Erdo orchestrator."""
+
+from .invoke import Invoke, InvokeResult, invoke, invoke_agent, invoke_by_key
+
+__all__ = [
+    "Invoke",
+    "InvokeResult",
+    "invoke",
+    "invoke_agent",
+    "invoke_by_key",
+]