solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/cli/commands/plugin_cmd/official_registry.py

@@ -0,0 +1,175 @@
+import httpx
+from pathlib import Path
+from functools import lru_cache
+from typing import Dict, Optional
+import click
+from config_portal.backend.plugin_catalog.constants import (
+    DEFAULT_OFFICIAL_REGISTRY_URL,
+    OFFICIAL_REGISTRY_GIT_BRANCH,
+)
+
+IGNORE_SUB_DIRS = [".git", "__pycache__", ".venv", "node_modules", ".vscode", ".github"]
+
+
+@lru_cache(maxsize=1)
+def get_official_plugins() -> Dict[str, str]:
+    """
+    Fetches the list of official plugins from the default registry.
+
+    Returns:
+        Dict[str, str]: A mapping of plugin names to their full URLs/paths
+    """
+    registry_url = DEFAULT_OFFICIAL_REGISTRY_URL
+
+    if _is_github_url(registry_url):
+        return _fetch_github_plugins(registry_url, branch=OFFICIAL_REGISTRY_GIT_BRANCH)
+    else:
+        return _fetch_local_plugins(registry_url)
+
+
+def _is_github_url(url: str) -> bool:
+    """Check if the URL is a GitHub repository URL."""
+    return url.startswith("https://github.com/") or url.startswith("http://github.com/")
+
+
+def _fetch_github_plugins(github_url: str, branch: str = None) -> Dict[str, str]:
+    """
+    Fetch plugin list from GitHub repository using the GitHub API.
+
+    Args:
+        github_url: GitHub repository URL
+        branch: Optional branch name to fetch plugins from
+
+    Returns:
+        Dict[str, str]: Mapping of plugin names to their full GitHub URLs
+    """
+    try:
+        if github_url.endswith(".git"):
+            github_url = github_url[:-4]
+
+        parts = (
+            github_url.replace("https://github.com/", "")
+            .replace("http://github.com/", "")
+            .split("/")
+        )
+        if len(parts) < 2:
+            click.echo(
+                click.style(f"Error: Invalid GitHub URL format: {github_url}", fg="red")
+            )
+            return {}
+
+        owner, repo = parts[0], parts[1]
+        api_url = f"https://api.github.com/repos/{owner}/{repo}/contents"
+        if branch:
+            api_url += f"?ref={branch}"
+
+        with httpx.Client() as client:
+            response = client.get(api_url, timeout=10.0)
+            response.raise_for_status()
+
+        contents = response.json()
+
+        plugins = {}
+        for item in contents:
+            if item.get("type") == "dir" and item["name"] not in IGNORE_SUB_DIRS:
+                plugin_name = item["name"]
+                plugin_url = f"git+{github_url}"
+                if branch:
+                    plugin_url += f"@{branch}"
+                plugin_url += f"#subdirectory={plugin_name}"
+                plugins[plugin_name] = plugin_url
+
+        return plugins
+
+    except httpx.RequestError as e:
+        click.echo(click.style(f"Error fetching plugins from GitHub: {e}", fg="red"))
+        return {}
+    except httpx.HTTPStatusError as e:
+        click.echo(
+            click.style(f"HTTP error fetching plugins from GitHub: {e}", fg="red")
+        )
+        return {}
+    except Exception as e:
+        click.echo(
+            click.style(f"Unexpected error fetching plugins from GitHub: {e}", fg="red")
+        )
+        return {}
+
+
+def _fetch_local_plugins(local_path: str) -> Dict[str, str]:
+    """
+    Fetch plugin list from local filesystem.
+
+    Args:
+        local_path: Local directory path
+
+    Returns:
+        Dict[str, str]: Mapping of plugin names to their full local paths
+    """
+    try:
+        path = Path(local_path).expanduser().resolve()
+
+        if not path.exists():
+            click.echo(
+                click.style(
+                    f"Error: Local plugin registry path does not exist: {path}",
+                    fg="red",
+                )
+            )
+            return {}
+
+        if not path.is_dir():
+            click.echo(
+                click.style(
+                    f"Error: Local plugin registry path is not a directory: {path}",
+                    fg="red",
+                )
+            )
+            return {}
+
+        plugins = {}
+        for item in path.iterdir():
+            if item.is_dir() and item.name not in IGNORE_SUB_DIRS:
+                plugin_name = item.name
+                plugins[plugin_name] = str(item)
+
+        return plugins
+
+    except Exception as e:
+        click.echo(
+            click.style(f"Error fetching plugins from local path: {e}", fg="red")
+        )
+        return {}
+
+
+def is_official_plugin(plugin_name: str) -> bool:
+    """
+    Check if a plugin name is an official plugin.
+
+    Args:
+        plugin_name: Name of the plugin to check
+
+    Returns:
+        bool: True if the plugin is official, False otherwise
+    """
+    official_plugins = get_official_plugins()
+    return plugin_name in official_plugins
+
+
+def get_official_plugin_url(plugin_name: str) -> Optional[str]:
+    """
+    Get the full URL/path for an official plugin.
+
+    Args:
+        plugin_name: Name of the official plugin
+
+    Returns:
+        Optional[str]: Full URL/path if plugin is official, None otherwise
+    """
+    # if the plugin_name is a git path, url, or a local path, it can't be an official plugin
+    if plugin_name.startswith(
+        ("git+", "http://", "https://", "file://", "/", "./", "../", "~/")
+    ):
+        return False
+    official_plugins = get_official_plugins()
+    return official_plugins.get(plugin_name)

solace_agent_mesh/cli/commands/plugin_cmd/plugin_cmd_llm.txt

@@ -0,0 +1,305 @@
+# Plugin Command Module Analysis
+
+## 1. Primary Purpose and Functionality
+
+The `plugin_cmd` module provides a comprehensive CLI interface for managing SAM (Serverless Application Model) plugins. It enables users to:
+
+- **Create** new plugin projects with standardized structure and templates
+- **Add** plugin components from various sources (installed modules, local paths, Git repositories)
+- **Build** plugins into distributable packages
+- **Launch** a web-based plugin store interface
+
+The module follows a command-group pattern where all plugin-related operations are organized under the `sam plugin` command namespace.
+
+## 2. External Interfaces (APIs, Exports, Public Methods)
+
+### Main Command Group
+```python
+@click.group("plugin")
+def plugin() -> None
+```
+- **Purpose**: Root command group for all plugin operations
+- **Usage**: `sam plugin <subcommand>`
+
+### Subcommands
+- `sam plugin create <plugin_name>` - Create new plugin
+- `sam plugin add <component_name> --plugin <source>` - Add component from plugin
+- `sam plugin build [path]` - Build plugin package
+- `sam plugin store` - Launch plugin store web interface
+
+## 3. Key Dependencies and Imports
+
+### External Dependencies
+- `click` - CLI framework for command definitions and options
+- `pathlib` - Modern path handling
+- `subprocess` - External process execution (git, pip, python build)
+- `tempfile` - Temporary directory management
+- `shutil` - File operations and command existence checks
+- `toml` - TOML file parsing for pyproject.toml
+- `multiprocessing` - Process management for web server
+- `webbrowser` - Browser launching for plugin store
+
+### Internal Dependencies
+- `cli.utils` - Utility functions for name formatting, user interaction, templates
+- `cli.__version__` - CLI version information
+- `config_portal.backend.plugin_store_server` - Backend server for plugin store
+
+## 4. Data Structures and Models
+
+### Command Functions
+
+#### `create_plugin_cmd`
+```python
+@click.command("create")
+@click.argument("plugin_name_arg": str)
+@click.option("--author-name", "author_name_opt": str, help="Author's name.")
+@click.option("--author-email", "author_email_opt": str, help="Author's email.")
+@click.option("--description", "description_opt": str, help="Plugin description.")
+@click.option("--version", "version_opt": str, help="Initial plugin version.")
+@click.option("--skip", is_flag=True, help="Skip interactive prompts and use defaults or provided flags.")
+def create_plugin_cmd(plugin_name_arg: str, author_name_opt: str, author_email_opt: str, description_opt: str, version_opt: str, skip: bool) -> None
+```
+
+**Purpose**: Creates a new SAM plugin directory structure with interactive prompts for metadata.
+
+**Usage Example**:
+```bash
+# Interactive mode
+sam plugin create my-awesome-plugin
+
+# Non-interactive with options
+sam plugin create my-plugin --author-name "John Doe" --author-email "john@example.com" --skip
+```
+
+**Generated Structure**:
+- `my-awesome-plugin/`
+  - `config.yaml` - Plugin configuration template
+  - `pyproject.toml` - Python package configuration
+  - `README.md` - Documentation template
+  - `src/`
+    - `__init__.py` - Package initialization
+    - `tools.py` - Plugin tools implementation
+
+**Template Placeholders**:
+- `__PLUGIN_KEBAB_CASE_NAME__` - Plugin name in kebab-case
+- `__PLUGIN_SNAKE_CASE_NAME__` - Plugin name in snake_case
+- `__PLUGIN_SPACED_NAME__` - Plugin name with spaces
+- `__PLUGIN_CAMEL_CASE_NAME__` - Plugin name in camelCase
+- `__PLUGIN_AUTHOR_NAME__` - Author's name
+- `__PLUGIN_AUTHOR_EMAIL__` - Author's email
+- `__PLUGIN_DESCRIPTION__` - Plugin description
+- `__PLUGIN_VERSION__` - Plugin version
+
+
+#### `add_plugin_component_cmd`
+```python
+@click.command("add")
+@click.argument("component_name": str)
+@click.option("--plugin", "plugin_source": str, required=True, help="Plugin source: installed module name, local path, or Git URL.")
+def add_plugin_component_cmd(component_name: str, plugin_source: str, confirm_pip: bool) -> None
+```
+
+**Purpose**: Creates a new component instance from a specified plugin source.
+
+**Usage Examples**:
+```bash
+# From installed module
+sam plugin add my-component --plugin installed-plugin-name
+
+# From local path
+sam plugin add my-component --plugin ./path/to/plugin
+
+# From Git repository
+sam plugin add my-component --plugin https://github.com/user/plugin.git
+
+# Skip pip confirmation
+sam plugin add my-component --plugin ./local/plugin
+```
+
+**Plugin Source Types**:
+1. **Module**: Installed Python module (no slashes in name)
+2. **Local**: Local directory path (existing directory)
+3. **Git**: Git repository URL (starts with git+, http://, https:// and ends with .git)
+
+**Component Placeholders**:
+- `__COMPONENT_UPPER_SNAKE_CASE_NAME__` - Component name in UPPER_SNAKE_CASE
+- `__COMPONENT_KEBAB_CASE_NAME__` - Component name in kebab-case
+- `__COMPONENT_CAMEL_CASE_NAME__` - Component name in camelCase
+
+**Output**: Creates `configs/plugins/{component-name}.yaml` with processed plugin configuration.
+
+#### `build_plugin_cmd`
+```python
+@click.command("build")
+@click.argument("plugin_path_arg": str, type=click.Path(exists=True, file_okay=False, dir_okay=True, resolve_path=True), default=".", metavar="PLUGIN_PATH")
+def build_plugin_cmd(plugin_path_arg: str) -> None
+```
+
+**Purpose**: Builds the SAM plugin in the specified directory using Python's build module.
+
+**Usage Examples**:
+```bash
+# Build current directory
+sam plugin build
+
+# Build specific directory
+sam plugin build ./my-plugin-directory
+```
+
+**Requirements**:
+- `pyproject.toml` must exist in target directory
+- `build` package must be installed (`pip install build`)
+
+**Output**: Creates `dist/` directory with built artifacts (wheel and source distribution).
+
+#### `store`
+```python
+@click.command("store")
+@click.option('--port', default=5003, type=int, show_default=True, help="Port to run the plugin store web server on.")
+def store(port: int) -> None
+```
+
+**Purpose**: Launches the SAM Plugin Store web interface.
+
+**Usage Examples**:
+```bash
+# Default port (5003)
+sam plugin store
+
+# Custom port
+sam plugin store --port 8080
+```
+
+**Behavior**:
+- Starts Flask backend server in separate process
+- Opens web browser to plugin store interface
+- Handles graceful shutdown on Ctrl+C
+- Uses multiprocessing for process management
+
+### Helper Functions
+
+#### `ensure_directory_exists`
+```python
+def ensure_directory_exists(path: pathlib.Path) -> None
+```
+**Purpose**: Creates a directory if it doesn't exist.
+**Parameters**: `path` - Path object for directory to create
+**Usage**: Used internally for creating plugin directory structures.
+
+#### `replace_placeholders`
+```python
+def replace_placeholders(content: str, replacements: dict) -> str
+```
+**Purpose**: Replaces placeholders in template content.
+**Parameters**: 
+- `content` - Template string with placeholders
+- `replacements` - Dictionary mapping placeholders to values
+**Returns**: Processed content with placeholders replaced
+
+#### `_check_command_exists`
+```python
+def _check_command_exists(command: str) -> bool
+```
+**Purpose**: Checks if a command exists on the system.
+**Parameters**: `command` - Command name to check
+**Returns**: True if command is available, False otherwise
+
+#### `_get_plugin_name_from_source_pyproject`
+```python
+def _get_plugin_name_from_source_pyproject(source_path: pathlib.Path) -> str | None
+```
+**Purpose**: Reads pyproject.toml from source path and returns the project name.
+**Parameters**: `source_path` - Path to directory containing pyproject.toml
+**Returns**: Normalized project name (snake_case) or None if not found
+
+#### `_run_pip_install`
+```python
+def _run_pip_install(install_target: str | pathlib.Path, operation_desc: str) -> str | None
+```
+**Purpose**: Runs pip install for the given target.
+**Parameters**:
+- `install_target` - Path or URL to install
+- `operation_desc` - Description for user feedback
+**Returns**: None on success, error message string on failure
+
+#### `run_flask_plugin_store`
+```python
+def run_flask_plugin_store(host: str, port: int, shared_data: dict) -> None
+```
+**Purpose**: Starts the Flask backend server for plugin store.
+**Parameters**:
+- `host` - Server host address
+- `port` - Server port number
+- `shared_data` - Multiprocessing shared dictionary for status communication
+
+### Configuration Objects
+
+#### Default Values
+```python
+DEFAULT_AUTHOR_NAME = "Your Name"
+DEFAULT_AUTHOR_EMAIL = "your.email@example.com"
+DEFAULT_PLUGIN_VERSION = "0.1.0"
+```
+
+#### Template Requirements
+The module expects these template files to exist:
+- `plugin_config_template.yaml` - Plugin configuration template
+- `plugin_pyproject_template.toml` - Python package configuration template
+- `plugin_tools_template.py` - Plugin tools implementation template
+- `plugin_readme_template.md` - Documentation template
+
+## 5. Architecture Patterns Used
+
+### Command Pattern
+- Each subcommand is implemented as a separate module with a single command function
+- Commands are registered with the main plugin group in `__init__.py`
+
+### Template Pattern
+- Uses template files with placeholder replacement for generating plugin scaffolding
+- Consistent placeholder naming convention across all templates
+
+### Strategy Pattern
+- Different installation strategies for plugin sources (module, local, git)
+- Conditional logic based on source type detection
+
+### Process Management Pattern
+- Uses multiprocessing for running web server in separate process
+- Shared data structures for inter-process communication
+
+### Error Handling Pattern
+- Consistent error handling with `error_exit()` utility function
+- Graceful degradation with user-friendly error messages
+
+## 6. Integration Points with Other Systems
+
+### CLI Framework Integration
+- Integrates with Click framework for command-line interface
+- Uses `cli.utils` for common functionality (name formatting, user interaction, template loading)
+
+### Package Management Integration
+- Integrates with pip for plugin installation
+- Supports Git repositories for plugin sources
+- Uses Python's build system for plugin packaging
+
+### Web Interface Integration
+- Launches Flask-based web server for plugin store
+- Integrates with browser for user interface
+- Uses multiprocessing for server management
+
+### File System Integration
+- Creates and manages plugin directory structures
+- Reads and writes configuration files (YAML, TOML)
+- Handles temporary directories for Git operations
+
+### Template System Integration
+- Loads templates from template directory
+- Processes placeholders for dynamic content generation
+- Supports multiple template formats (YAML, TOML, Python, Markdown)
+
+### External Tool Integration
+- Git for repository cloning
+- Python build tools for package creation
+- Pip for package installation
+- System commands through subprocess
+
+The module provides a comprehensive plugin management system that integrates seamlessly with the broader SAM CLI ecosystem while maintaining clear separation of concerns and robust error handling.

solace_agent_mesh/cli/commands/run_cmd.py

@@ -0,0 +1,215 @@
+import logging
+import os
+import sys
+from pathlib import Path
+
+import click
+from dotenv import find_dotenv, load_dotenv
+
+from cli.utils import error_exit
+from solace_agent_mesh.common.utils.initializer import initialize
+from solace_ai_connector.common.logging_config import configure_from_file
+
+
+def _execute_with_solace_ai_connector(config_file_paths: list[str]):
+    try:
+        from solace_ai_connector.main import main as solace_ai_connector_main
+    except ImportError:
+        error_exit(
+            "Error: Failed to import 'solace_ai_connector.main'.\n"
+            "Please ensure 'solace-agent-mesh' (which includes the connector) is installed correctly."
+        )
+
+    program_name = sys.argv[0]
+    if os.path.basename(program_name) == "sam":
+        connector_program_name = program_name.replace("sam", "solace-ai-connector")
+    elif os.path.basename(program_name) == "solace-agent-mesh":
+        connector_program_name = program_name.replace(
+            "solace-agent-mesh", "solace-ai-connector"
+        )
+    else:
+        connector_program_name = "solace-ai-connector"
+
+    sys.argv = [connector_program_name] + config_file_paths
+
+    sys.argv = [
+        sys.argv[0].replace("solace-agent-mesh", "solace-ai-connector"),
+        *config_file_paths,
+    ]
+    return sys.exit(solace_ai_connector_main())
+
+
+@click.command(name="run")
+@click.argument(
+    "files", nargs=-1, type=click.Path(exists=True, dir_okay=True, resolve_path=True)
+)
+@click.option(
+    "-s",
+    "--skip",
+    "skip_files",
+    multiple=True,
+    help="File name(s) to exclude from the run (e.g., -s my_agent.yaml).",
+)
+@click.option(
+    "-u",
+    "--system-env",
+    is_flag=True,
+    default=False,
+    help="Use system environment variables only; do not load .env file.",
+)
+def run(files: tuple[str, ...], skip_files: tuple[str, ...], system_env: bool):
+    """
+    Run the Solace application with specified or discovered YAML configuration files.
+
+    This command accepts paths to individual YAML files (`.yaml`, `.yml`) or directories.
+    When a directory is provided, it is recursively searched for YAML files.
+    """
+    # Set up initial logging to root logger (will be overwritten by LOGGING_CONFIG_PATH if provided)
+    log = None
+    reset_logging = True
+
+    def _setup_backup_logger():
+        nonlocal log
+        if not log:
+            log = logging.getLogger()
+            handler = logging.StreamHandler(sys.stdout)
+            formatter = logging.Formatter(
+                "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+            )
+            handler.setFormatter(formatter)
+            log.addHandler(handler)
+            log.setLevel(logging.INFO)
+        return log
+        
+    env_path = ""
+
+    if not system_env:
+        env_path = find_dotenv(usecwd=True)
+        if env_path:
+            load_dotenv(dotenv_path=env_path, override=True)
+
+            # Resolve LOGGING_CONFIG_PATH to absolute path if it's relative
+            logging_config_path = os.getenv("LOGGING_CONFIG_PATH")
+            if logging_config_path and not os.path.isabs(logging_config_path):
+                absolute_logging_path = os.path.abspath(logging_config_path)
+                os.environ["LOGGING_CONFIG_PATH"] = absolute_logging_path
+
+    try:
+        if configure_from_file():
+            log = logging.getLogger(__name__)
+            log.info("Logging reconfigured from LOGGING_CONFIG_PATH")
+            reset_logging = False
+        else:
+            log = _setup_backup_logger()
+    except ImportError:
+        log = _setup_backup_logger()  # solace_ai_connector might not be available yet
+        log.warning("Using backup logger; solace_ai_connector not available.")
+
+    if system_env:
+        log.warning("Skipping .env file loading due to --system-env flag.")
+    else:
+        if not env_path:
+            log.warning("Warning: .env file not found in the current directory or parent directories. Proceeding without loading .env.")
+        else:
+            log.info("Loaded environment variables from: %s", env_path)
+
+    # Run enterprise initialization if present
+    initialize()
+
+    config_files_to_run = []
+    project_root = Path.cwd()
+    configs_dir = project_root / "configs"
+
+    if not files:
+        log.info(
+            "No specific files provided. Discovering YAML files in %s...", configs_dir
+        )
+        if not configs_dir.is_dir():
+            log.error(
+                "Error: Configuration directory '%s' not found. Please run 'init' first or provide specific config files.",
+                configs_dir
+            )
+            sys.exit(1)
+
+        for filepath in configs_dir.rglob("*.yaml"):
+            if filepath.name.startswith("_") or filepath.name.startswith(
+                "shared_config"
+            ):
+                log.info(
+                    "  Skipping discovery: %s (underscore prefix or shared_config)", filepath
+                )
+                continue
+            config_files_to_run.append(str(filepath.resolve()))
+
+        for filepath in configs_dir.rglob("*.yml"):
+            if filepath.name.startswith("_") or filepath.name.startswith(
+                "shared_config"
+            ):
+                log.info(
+                    "  Skipping discovery: %s (underscore prefix or shared_config)", filepath
+                )
+                continue
+            if str(filepath.resolve()) not in config_files_to_run:
+                config_files_to_run.append(str(filepath.resolve()))
+
+    else:
+        log.info("Processing provided configuration files and directories:")
+        processed_files = set()
+        for path_str in files:
+            path = Path(path_str)
+            if path.is_dir():
+                log.info("  Discovering YAML files in directory: %s", path)
+                for yaml_ext in ("*.yaml", "*.yml"):
+                    for filepath in path.rglob(yaml_ext):
+                        if filepath.name.startswith("_") or filepath.name.startswith(
+                            "shared_config"
+                        ):
+                            log.info(
+                                "  Skipping discovery: %s (underscore prefix or shared_config)", filepath
+                            )
+                            continue
+                        processed_files.add(str(filepath.resolve()))
+            elif path.is_file():
+                if path.suffix in [".yaml", ".yml"]:
+                    processed_files.add(str(path.resolve()))
+                else:
+                    log.warning(
+                        "  Ignoring non-YAML file: %s", path
+                    )
+        config_files_to_run = sorted(list(processed_files))
+
+    if skip_files:
+        log.info("Applying --skip for: %s", skip_files)
+        final_list = []
+        skipped_basenames = [os.path.basename(s) for s in skip_files]
+        for cf in config_files_to_run:
+            if os.path.basename(cf) in skipped_basenames:
+                log.info(
+                    "  Skipping execution: %s (due to --skip)", cf
+                )
+                continue
+            final_list.append(cf)
+        config_files_to_run = final_list
+
+    if not config_files_to_run:
+        log.warning(
+            "No configuration files to run after filtering. Exiting."
+        )
+        return 0
+
+    file_list = "\n".join(f"  - {cf}" for cf in config_files_to_run)
+    log.info("Final list of configuration files to run:\n%s", file_list)
+
+    if reset_logging:
+        for handler in log.handlers[:]:
+            log.removeHandler(handler)
+    return_code = _execute_with_solace_ai_connector(config_files_to_run)
+
+    if return_code == 0:
+        log.info("Application run completed successfully.")
+    else:
+        log.error(
+            "Application run failed or exited with code %s.", return_code
+        )
+
+    sys.exit(return_code)