pltr-cli 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

pltr/commands/aip_agents.py

@@ -0,0 +1,333 @@
+"""
+AIP Agents management commands for Foundry.
+Provides commands for agent inspection, session management, and version control.
+"""
+
+import typer
+from typing import Optional
+from rich.console import Console
+
+from ..services.aip_agents import AipAgentsService
+from ..utils.formatting import OutputFormatter
+from ..utils.progress import SpinnerProgressTracker
+from ..utils.pagination import PaginationConfig
+from ..auth.base import ProfileNotFoundError, MissingCredentialsError
+from ..utils.completion import (
+    complete_rid,
+    complete_profile,
+    complete_output_format,
+    cache_rid,
+)
+
+# Create main app and sub-apps
+app = typer.Typer(help="Manage AIP Agents, sessions, and versions")
+sessions_app = typer.Typer(help="Manage agent conversation sessions")
+versions_app = typer.Typer(help="Manage agent versions")
+
+# Add sub-apps
+app.add_typer(sessions_app, name="sessions")
+app.add_typer(versions_app, name="versions")
+
+console = Console()
+formatter = OutputFormatter(console)
+
+
+@app.command("get")
+def get_agent(
+    agent_rid: str = typer.Argument(
+        ...,
+        help="Agent Resource Identifier (e.g., ri.foundry.main.agent.abc123)",
+        autocompletion=complete_rid,
+    ),
+    version: Optional[str] = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Agent version to retrieve (e.g., '1.0'). Defaults to latest published.",
+    ),
+    profile: Optional[str] = typer.Option(
+        None,
+        "--profile",
+        "-p",
+        help="Profile name",
+        autocompletion=complete_profile,
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format (table, json, csv)",
+        autocompletion=complete_output_format,
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output file path"
+    ),
+):
+    """
+    Get detailed information about an AIP Agent.
+
+    Retrieves agent configuration including name, description, parameters,
+    and version information.
+
+    Examples:
+
+        # Get latest published version of agent
+        pltr aip-agents get ri.foundry.main.agent.abc123
+
+        # Get specific version
+        pltr aip-agents get ri.foundry.main.agent.abc123 --version 1.5
+
+        # Output as JSON
+        pltr aip-agents get ri.foundry.main.agent.abc123 --format json
+    """
+    try:
+        cache_rid(agent_rid)
+
+        service = AipAgentsService(profile=profile)
+
+        with SpinnerProgressTracker().track_spinner(f"Fetching agent {agent_rid}..."):
+            agent = service.get_agent(agent_rid, version=version)
+
+        if output:
+            formatter.save_to_file(agent, output, format)
+            formatter.print_success(f"Agent information saved to {output}")
+        else:
+            formatter.display(agent, format)
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        formatter.print_error(f"Authentication error: {e}")
+        raise typer.Exit(1)
+    except ValueError as e:
+        formatter.print_error(f"Invalid request: {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        formatter.print_error(f"Failed to get agent: {e}")
+        raise typer.Exit(1)
+
+
+@sessions_app.command("list")
+def list_sessions(
+    agent_rid: str = typer.Argument(
+        ...,
+        help="Agent Resource Identifier",
+        autocompletion=complete_rid,
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format (table, json, csv)",
+        autocompletion=complete_output_format,
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output file path"
+    ),
+    page_size: Optional[int] = typer.Option(
+        None, "--page-size", help="Number of sessions per page"
+    ),
+    max_pages: Optional[int] = typer.Option(
+        1, "--max-pages", help="Maximum number of pages to fetch (default: 1)"
+    ),
+    all: bool = typer.Option(
+        False, "--all", help="Fetch all available sessions (overrides --max-pages)"
+    ),
+):
+    """
+    List conversation sessions for an agent.
+
+    Only lists sessions created by this client (API). Sessions created
+    in AIP Agent Studio will not appear.
+
+    Examples:
+
+        # List first page of sessions
+        pltr aip-agents sessions list ri.foundry.main.agent.abc123
+
+        # List all sessions
+        pltr aip-agents sessions list ri.foundry.main.agent.abc123 --all
+
+        # List first 3 pages with 50 sessions each
+        pltr aip-agents sessions list ri.foundry.main.agent.abc123 \\
+            --page-size 50 --max-pages 3
+    """
+    try:
+        cache_rid(agent_rid)
+
+        service = AipAgentsService(profile=profile)
+        config = PaginationConfig(
+            page_size=page_size,
+            max_pages=max_pages,
+            fetch_all=all,
+        )
+
+        with SpinnerProgressTracker().track_spinner(
+            f"Fetching sessions for agent {agent_rid}..."
+        ):
+            result = service.list_sessions(agent_rid, config)
+
+        if not result.data:
+            console.print("[yellow]No sessions found for this agent[/yellow]")
+            return
+
+        if output:
+            formatter.format_paginated_output(result, format, output)
+            console.print(f"[green]Results saved to {output}[/green]")
+        else:
+            formatter.format_paginated_output(result, format)
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        formatter.print_error(f"Authentication error: {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        formatter.print_error(f"Failed to list sessions: {e}")
+        raise typer.Exit(1)
+
+
+@sessions_app.command("get")
+def get_session(
+    agent_rid: str = typer.Argument(
+        ...,
+        help="Agent Resource Identifier",
+        autocompletion=complete_rid,
+    ),
+    session_rid: str = typer.Argument(
+        ...,
+        help="Session Resource Identifier",
+        autocompletion=complete_rid,
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format (table, json, csv)",
+        autocompletion=complete_output_format,
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output file path"
+    ),
+):
+    """
+    Get detailed information about a conversation session.
+
+    Examples:
+
+        # Get session details
+        pltr aip-agents sessions get \\
+            ri.foundry.main.agent.abc123 \\
+            ri.foundry.main.session.xyz789
+
+        # Export session details to JSON
+        pltr aip-agents sessions get \\
+            ri.foundry.main.agent.abc123 \\
+            ri.foundry.main.session.xyz789 \\
+            --format json --output session.json
+    """
+    try:
+        cache_rid(agent_rid)
+        cache_rid(session_rid)
+
+        service = AipAgentsService(profile=profile)
+
+        with SpinnerProgressTracker().track_spinner(
+            f"Fetching session {session_rid}..."
+        ):
+            session = service.get_session(agent_rid, session_rid)
+
+        if output:
+            formatter.save_to_file(session, output, format)
+            formatter.print_success(f"Session information saved to {output}")
+        else:
+            formatter.display(session, format)
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        formatter.print_error(f"Authentication error: {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        formatter.print_error(f"Failed to get session: {e}")
+        raise typer.Exit(1)
+
+
+@versions_app.command("list")
+def list_versions(
+    agent_rid: str = typer.Argument(
+        ...,
+        help="Agent Resource Identifier",
+        autocompletion=complete_rid,
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format (table, json, csv)",
+        autocompletion=complete_output_format,
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output file path"
+    ),
+    page_size: Optional[int] = typer.Option(
+        None, "--page-size", help="Number of versions per page"
+    ),
+    max_pages: Optional[int] = typer.Option(
+        1, "--max-pages", help="Maximum number of pages to fetch (default: 1)"
+    ),
+    all: bool = typer.Option(
+        False, "--all", help="Fetch all available versions (overrides --max-pages)"
+    ),
+):
+    """
+    List all versions for an AIP Agent.
+
+    Versions are returned in descending order (most recent first).
+
+    Examples:
+
+        # List first page of versions
+        pltr aip-agents versions list ri.foundry.main.agent.abc123
+
+        # List all versions
+        pltr aip-agents versions list ri.foundry.main.agent.abc123 --all
+
+        # Export all versions to CSV
+        pltr aip-agents versions list ri.foundry.main.agent.abc123 \\
+            --all --format csv --output versions.csv
+    """
+    try:
+        cache_rid(agent_rid)
+
+        service = AipAgentsService(profile=profile)
+        config = PaginationConfig(
+            page_size=page_size,
+            max_pages=max_pages,
+            fetch_all=all,
+        )
+
+        with SpinnerProgressTracker().track_spinner(
+            f"Fetching versions for agent {agent_rid}..."
+        ):
+            result = service.list_versions(agent_rid, config)
+
+        if not result.data:
+            console.print("[yellow]No versions found for this agent[/yellow]")
+            return
+
+        if output:
+            formatter.format_paginated_output(result, format, output)
+            console.print(f"[green]Results saved to {output}[/green]")
+        else:
+            formatter.format_paginated_output(result, format)
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        formatter.print_error(f"Authentication error: {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        formatter.print_error(f"Failed to list versions: {e}")
+        raise typer.Exit(1)

pltr/commands/connectivity.py

@@ -4,7 +4,8 @@ Connectivity management commands for Foundry connections and imports.
 
 import typer
 import json
-from typing import Optional
+from pathlib import Path
+from typing import List, Optional
 from rich.console import Console
 
 from ..services.connectivity import ConnectivityService
@@ -29,6 +30,53 @@ app.add_typer(connection_app, name="connection", help="Manage connections")
 app.add_typer(import_app, name="import", help="Manage data imports")
 
 
+def _load_json_param(
+    json_str: Optional[str], file_path: Optional[str], param_name: str
+) -> dict:
+    """
+    Load JSON from either a string or a file.
+
+    Args:
+        json_str: JSON string (optional)
+        file_path: Path to JSON file (optional)
+        param_name: Name of parameter for error messages
+
+    Returns:
+        Parsed JSON dictionary
+
+    Raises:
+        typer.Exit: If neither or both are provided, or if parsing fails
+    """
+    if json_str and file_path:
+        console.print(
+            f"[red]Cannot specify both {param_name} and {param_name}-file[/red]"
+        )
+        raise typer.Exit(1)
+
+    if not json_str and not file_path:
+        console.print(
+            f"[red]Must specify either {param_name} or --{param_name}-file[/red]"
+        )
+        raise typer.Exit(1)
+
+    if file_path:
+        path = Path(file_path)
+        if not path.exists():
+            console.print(f"[red]File not found: {file_path}[/red]")
+            raise typer.Exit(1)
+        try:
+            json_str = path.read_text()
+        except Exception as e:
+            console.print(f"[red]Error reading {file_path}: {e}[/red]")
+            raise typer.Exit(1)
+
+    try:
+        return json.loads(json_str)  # type: ignore[arg-type]
+    except json.JSONDecodeError as e:
+        console.print(f"[red]Invalid JSON for {param_name}: {e}[/red]")
+        raise typer.Exit(1)
+
+
 @connection_app.command("list")
 def list_connections(
     profile: Optional[str] = typer.Option(
@@ -104,6 +152,266 @@ def get_connection(
         raise typer.Exit(1)
 
 
+@connection_app.command("create")
+def create_connection(
+    display_name: str = typer.Argument(..., help="Display name for the connection"),
+    parent_folder_rid: str = typer.Argument(
+        ..., help="Parent folder Resource Identifier", autocompletion=complete_rid
+    ),
+    configuration: Optional[str] = typer.Argument(
+        None, help="Connection configuration in JSON format"
+    ),
+    worker: Optional[str] = typer.Argument(
+        None, help="Worker configuration in JSON format"
+    ),
+    config_file: Optional[str] = typer.Option(
+        None, "--config-file", help="Path to JSON file with connection configuration"
+    ),
+    worker_file: Optional[str] = typer.Option(
+        None, "--worker-file", help="Path to JSON file with worker configuration"
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format (table, json, csv)",
+        autocompletion=complete_output_format,
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output file path"
+    ),
+):
+    """Create a new connection.
+
+    Configuration and worker can be provided as JSON strings or via file options.
+    """
+    try:
+        cache_rid(parent_folder_rid)
+
+        # Load configuration from string or file
+        config_dict = _load_json_param(configuration, config_file, "configuration")
+        worker_dict = _load_json_param(worker, worker_file, "worker")
+
+        service = ConnectivityService(profile=profile)
+
+        with SpinnerProgressTracker().track_spinner("Creating connection..."):
+            connection = service.create_connection(
+                display_name=display_name,
+                parent_folder_rid=parent_folder_rid,
+                configuration=config_dict,
+                worker=worker_dict,
+            )
+
+        cache_rid(connection.get("rid", ""))
+        console.print(f"[green]Connection created: {connection.get('rid')}[/green]")
+        formatter.format_output([connection], format, output)
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error creating connection: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@connection_app.command("get-config")
+def get_connection_configuration(
+    connection_rid: str = typer.Argument(
+        ..., help="Connection Resource Identifier", autocompletion=complete_rid
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+    format: str = typer.Option(
+        "json",
+        "--format",
+        "-f",
+        help="Output format (table, json, csv)",
+        autocompletion=complete_output_format,
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output file path"
+    ),
+):
+    """Get connection configuration."""
+    try:
+        cache_rid(connection_rid)
+
+        with SpinnerProgressTracker().track_spinner(
+            f"Fetching configuration for {connection_rid}..."
+        ):
+            service = ConnectivityService(profile=profile)
+            config = service.get_connection_configuration(connection_rid)
+
+        formatter.format_output([config], format, output)
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error getting connection configuration: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@connection_app.command("update-secrets")
+def update_connection_secrets(
+    connection_rid: str = typer.Argument(
+        ..., help="Connection Resource Identifier", autocompletion=complete_rid
+    ),
+    secrets_file: str = typer.Option(
+        ...,
+        "--secrets-file",
+        "-s",
+        help="Path to JSON file containing secrets (mapping secret names to values)",
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+):
+    """Update connection secrets.
+
+    Secrets must be provided via a file for security (to avoid exposure in shell
+    history or process listings).
+    """
+    try:
+        cache_rid(connection_rid)
+
+        # Load secrets from file
+        path = Path(secrets_file)
+        if not path.exists():
+            console.print(f"[red]Secrets file not found: {secrets_file}[/red]")
+            raise typer.Exit(1)
+
+        try:
+            secrets_content = path.read_text()
+            secrets_dict = json.loads(secrets_content)
+        except json.JSONDecodeError as e:
+            console.print(f"[red]Invalid JSON in secrets file: {e}[/red]")
+            raise typer.Exit(1)
+        except Exception as e:
+            console.print(f"[red]Error reading secrets file: {e}[/red]")
+            raise typer.Exit(1)
+
+        service = ConnectivityService(profile=profile)
+
+        with SpinnerProgressTracker().track_spinner("Updating secrets..."):
+            service.update_secrets(connection_rid, secrets_dict)
+
+        console.print(
+            f"[green]Secrets updated for connection: {connection_rid}[/green]"
+        )
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error updating secrets: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@connection_app.command("update-export-settings")
+def update_export_settings(
+    connection_rid: str = typer.Argument(
+        ..., help="Connection Resource Identifier", autocompletion=complete_rid
+    ),
+    settings: Optional[str] = typer.Argument(
+        None, help="Export settings in JSON format"
+    ),
+    settings_file: Optional[str] = typer.Option(
+        None, "--settings-file", help="Path to JSON file with export settings"
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+):
+    """Update connection export settings.
+
+    Settings can be provided as a JSON string or via --settings-file.
+    """
+    try:
+        cache_rid(connection_rid)
+
+        # Load settings from string or file
+        settings_dict = _load_json_param(settings, settings_file, "settings")
+
+        service = ConnectivityService(profile=profile)
+
+        with SpinnerProgressTracker().track_spinner("Updating export settings..."):
+            service.update_export_settings(connection_rid, settings_dict)
+
+        console.print(
+            f"[green]Export settings updated for connection: {connection_rid}[/green]"
+        )
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error updating export settings: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@connection_app.command("upload-jdbc-drivers")
+def upload_jdbc_drivers(
+    connection_rid: str = typer.Argument(
+        ..., help="Connection Resource Identifier", autocompletion=complete_rid
+    ),
+    driver_files: List[str] = typer.Argument(
+        ..., help="Path(s) to JAR file(s) to upload"
+    ),
+    profile: Optional[str] = typer.Option(
+        None, "--profile", "-p", help="Profile name", autocompletion=complete_profile
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format (table, json, csv)",
+        autocompletion=complete_output_format,
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output file path"
+    ),
+):
+    """Upload custom JDBC drivers to a connection.
+
+    Only JAR files are supported.
+    """
+    try:
+        cache_rid(connection_rid)
+
+        # Validate files exist and are JAR files before uploading
+        for driver_file in driver_files:
+            path = Path(driver_file)
+            if not path.exists():
+                console.print(f"[red]File not found: {driver_file}[/red]")
+                raise typer.Exit(1)
+            if path.suffix.lower() != ".jar":
+                console.print(f"[red]File must be a JAR file: {driver_file}[/red]")
+                raise typer.Exit(1)
+
+        service = ConnectivityService(profile=profile)
+        results = []
+
+        for driver_file in driver_files:
+            with SpinnerProgressTracker().track_spinner(f"Uploading {driver_file}..."):
+                result = service.upload_custom_jdbc_drivers(connection_rid, driver_file)
+                results.append(result)
+            console.print(f"[green]Uploaded: {driver_file}[/green]")
+
+        formatter.format_output(results, format, output)
+
+    except (ProfileNotFoundError, MissingCredentialsError) as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error uploading JDBC drivers: {e}[/red]")
+        raise typer.Exit(1)
+
+
 @import_app.command("file")
 def import_file(
     connection_rid: str = typer.Argument(