solace-agent-mesh 1.7.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/cli/commands/add_cmd/add_cmd_llm.txt

@@ -1,250 +0,0 @@
-# Add Command Module Analysis
-
-## 1. Primary Purpose and Functionality
-
-The `add_cmd` module provides a CLI interface for creating templates for agents and gateways in what appears to be an AI agent framework. The primary functionality includes:
-
-- **Agent Creation**: Creates new agent configurations via CLI or web-based GUI
-- **Gateway Creation**: Placeholder functionality for gateway template creation (not yet implemented)
-- **Interactive Configuration**: Supports both interactive CLI prompts and web-based configuration portal
-- **Template Processing**: Generates YAML configuration files from templates with user-provided parameters
-
-## 2. External Interfaces (APIs, Exports, Public Methods)
-
-### CLI Commands
-- `add agent [NAME] [OPTIONS]` - Creates a new agent configuration
-- `add gateway NAME` - Placeholder for gateway creation
-
-### Public Functions
-```python
-def launch_add_agent_web_portal(cli_options: dict) -> tuple[str, dict, Path]
-def create_agent_config(agent_name_input: str, cli_provided_options: dict, skip_interactive: bool) -> bool
-```
-
-## 3. Key Dependencies and Imports
-
-- **click**: CLI framework for command-line interfaces
-- **pathlib.Path**: File system path operations
-- **yaml**: YAML file processing
-- **json**: JSON parsing for tools and skills configuration
-- **re**: Regular expression operations for template processing
-- **multiprocessing**: Process management for web portal
-- **webbrowser**: Browser automation for web portal
-- **config_portal.backend.server**: Web-based configuration portal backend
-
-## 4. Data Structures and Models
-
-### AGENT_DEFAULTS Configuration Dictionary
-```python
-AGENT_DEFAULTS = {
-    "supports_streaming": bool,           # Enable streaming support
-    "model_type": str,                   # Model type: "planning", "general", "image_gen", "report_gen", "multimodal", "gemini_pro"
-    "instruction": str,                  # Agent instruction template
-    "artifact_handling_mode": str,       # Mode: "ignore", "embed", "reference"
-    "enable_embed_resolution": bool,     # Enable embed resolution
-    "enable_artifact_content_instruction": bool,  # Enable artifact content instruction
-    "session_service_type": str,         # Type: "memory", "vertex_rag"
-    "session_service_behavior": str,     # Behavior: "PERSISTENT", "RUN_BASED"
-    "artifact_service_type": str,        # Type: "filesystem", "memory", "gcs"
-    "artifact_service_base_path": str,   # Base path for filesystem service
-    "artifact_service_scope": str,       # Scope: "namespace", "app", "custom"
-    "agent_card_description": str,       # Agent description
-    "agent_card_default_input_modes": list[str],   # Input modes: ["text"]
-    "agent_card_default_output_modes": list[str],  # Output modes: ["text", "file"]
-    "agent_card_publishing_interval": int,         # Publishing interval in seconds
-    "agent_discovery_enabled": bool,     # Enable agent discovery
-    "inter_agent_communication_allow_list": list[str],  # Allow list: ["*"]
-    "inter_agent_communication_deny_list": list[str],   # Deny list: []
-    "inter_agent_communication_timeout": int,           # Timeout in seconds
-    "namespace": str,                    # namespace
-}
-```
-
-**Purpose**: Provides default values for all agent configuration options.
-
-**Usage Example**:
-```python
-default_model = AGENT_DEFAULTS["model_type"]  # Returns "planning"
-default_streaming = AGENT_DEFAULTS["supports_streaming"]  # Returns True
-```
-
-### Configuration Options Dictionary
-```python
-config_options = {
-    "agent_name": str,                   # Camel case agent name
-    "namespace": str,                    # Agent namespace
-    "supports_streaming": bool,          # Streaming support flag
-    "model_type": str,                   # Model type selection
-    "instruction": str,                  # Custom agent instruction
-    "tools": list[dict] | str,          # Tools configuration (list or JSON string)
-    "session_service_type": str,         # Session service configuration
-    "session_service_behavior": str,     # Session behavior mode
-    "artifact_service_type": str,        # Artifact service configuration
-    "artifact_service_base_path": str,   # Filesystem base path
-    "artifact_service_scope": str,       # Artifact scope
-    "artifact_handling_mode": str,       # Artifact handling mode
-    "enable_embed_resolution": bool,     # Embed resolution flag
-    "enable_artifact_content_instruction": bool,  # Artifact content instruction flag
-    "agent_card_description": str,       # Agent card description
-    "agent_card_default_input_modes": list[str],   # Default input modes
-    "agent_card_default_output_modes": list[str],  # Default output modes
-    "agent_card_skills": list[dict],     # Skills configuration from GUI
-    "agent_card_skills_str": str,        # Skills configuration from CLI (JSON string)
-    "agent_card_publishing_interval": int,         # Publishing interval
-    "agent_discovery_enabled": bool,     # Discovery flag
-    "inter_agent_communication_allow_list": list[str],  # Communication allow list
-    "inter_agent_communication_deny_list": list[str],   # Communication deny list
-    "inter_agent_communication_timeout": int,           # Communication timeout
-}
-```
-
-**Purpose**: Contains user-provided configuration options for agent creation.
-
-**Usage Example**:
-```python
-config = {
-    "agent_name": "MyAgent",
-    "model_type": "planning",
-    "supports_streaming": True,
-    "tools": [{"name": "calculator", "type": "builtin"}]
-}
-```
-
-### Special Constants
-```python
-USE_DEFAULT_SHARED_SESSION = "use_default_shared_session"
-USE_DEFAULT_SHARED_ARTIFACT = "use_default_shared_artifact"
-```
-
-**Purpose**: Special values indicating use of default shared services instead of custom configurations.
-
-## 5. Key Functions and Methods
-
-### create_agent_config()
-```python
-def create_agent_config(agent_name_input: str, cli_provided_options: dict, skip_interactive: bool) -> bool
-```
-
-**Purpose**: Main function for CLI-based agent creation. Collects configuration options interactively or from CLI parameters.
-
-**Parameters**:
-- `agent_name_input`: Raw agent name input from user
-- `cli_provided_options`: Dictionary of options provided via CLI flags
-- `skip_interactive`: If True, skips interactive prompts and uses defaults
-
-**Returns**: Boolean indicating success/failure
-
-**Usage Example**:
-```python
-success = create_agent_config(
-    "my-agent", 
-    {"model_type": "planning", "supports_streaming": True}, 
-    False
-)
-```
-
-### _write_agent_yaml_from_data()
-```python
-def _write_agent_yaml_from_data(agent_name_input: str, config_options: dict, project_root: Path) -> tuple[bool, str, str]
-```
-
-**Purpose**: Writes the agent YAML configuration file based on provided options.
-
-**Parameters**:
-- `agent_name_input`: Raw agent name input
-- `config_options`: Complete configuration dictionary
-- `project_root`: Project root directory path
-
-**Returns**: Tuple of (success_flag, message, relative_file_path)
-
-**Usage Example**:
-```python
-success, message, file_path = _write_agent_yaml_from_data(
-    "my-agent",
-    config_options,
-    Path.cwd()
-)
-```
-
-### launch_add_agent_web_portal()
-```python
-def launch_add_agent_web_portal(cli_options: dict) -> tuple[str, dict, Path]
-```
-
-**Purpose**: Launches web-based configuration portal for agent creation.
-
-**Parameters**:
-- `cli_options`: Dictionary containing initial options (typically just "name")
-
-**Returns**: Tuple of (agent_name, agent_options, project_root)
-
-**Usage Example**:
-```python
-agent_name, options, root = launch_add_agent_web_portal({"name": "my-agent"})
-```
-
-### add_agent Command
-```python
-@click.command(name="agent")
-@click.argument("name", required=False)
-@click.option("--gui", is_flag=True, help="Launch the web UI to configure the agent.")
-@click.option("--skip-interactive", is_flag=True, help="Skip interactive prompts and use defaults.")
-# ... additional options for all configuration parameters
-def add_agent(name: str, gui: bool=False, **kwargs)
-```
-
-**Purpose**: Main CLI command entry point for agent creation.
-
-**Parameters**:
-- `name`: Agent name (optional if using GUI)
-- `gui`: Flag to launch web-based configuration
-- `**kwargs`: All other configuration options as CLI flags
-
-**CLI Usage Examples**:
-```bash
-# Interactive CLI mode
-python -m cli.main add agent my-agent
-
-# Non-interactive CLI mode with options
-python -m cli.main add agent my-agent --skip-interactive --model-type planning --supports-streaming
-
-# Web GUI mode
-python -m cli.main add agent my-agent --gui
-```
-
-## 6. Architecture Patterns Used
-
-- **Command Pattern**: Uses Click framework for CLI command structure
-- **Template Method Pattern**: Uses template files with placeholder replacement
-- **Factory Pattern**: Creates agent configurations based on user input
-- **Multiprocessing Pattern**: Separates web portal into isolated process
-- **Configuration Pattern**: Centralized defaults and user option management
-
-## 7. Integration Points with Other Systems
-
-### Template System
-- Integrates with `load_template()` utility to load agent YAML templates
-- Uses placeholder replacement for dynamic content generation
-
-### Web Portal Integration
-- Launches Flask-based web server via `config_portal.backend.server.run_flask`
-- Uses multiprocessing for process isolation
-- Communicates via shared dictionary for data exchange
-
-### File System Integration
-- Creates agent configuration files in `configs/agents/` directory
-- Generates snake_case filenames with `_agent.yaml` suffix
-- Uses project root detection for relative path generation
-
-### Utility Integration
-- Uses `get_formatted_names()` for name format conversion
-- Uses `ask_if_not_provided()` for interactive CLI prompts
-- Integrates with YAML and JSON processing for configuration serialization
-
-### External Dependencies
-- **Click Framework**: Provides CLI interface and option parsing
-- **YAML Processing**: Handles configuration file generation and parsing
-- **Web Browser**: Automatically opens configuration portal
-- **Multiprocessing**: Manages web portal lifecycle
-
-The module serves as a comprehensive agent creation system supporting both CLI and web-based workflows, with extensive configuration options and robust error handling.

solace_agent_mesh/cli/commands/init_cmd/init_cmd_llm.txt

@@ -1,365 +0,0 @@
-# init_cmd Directory Analysis
-
-## 1. Primary Purpose and Functionality
-
-The `init_cmd` directory implements a comprehensive project initialization system for Solace Agent Mesh applications. It provides both CLI-based and web-based initialization flows to create new projects with proper directory structure, configuration files, and environment setup.
-
-**Core Functionality:**
-- Creates project directory structure (`configs/`, `src/`, etc.)
-- Generates configuration files for agents and gateways
-- Sets up environment variables and broker connections
-- Supports multiple broker types (existing Solace, containerized, dev mode)
-- Provides web-based GUI configuration option
-- Creates orchestrator agent configurations
-- Optionally sets up WebUI gateway
-
-## 2. External Interfaces (APIs, Exports, Public Methods)
-
-### Main CLI Command
-```python
-@click.command(name="init")
-def init(**kwargs) -> None
-```
-**Purpose:** Main entry point for project initialization
-**Parameters:** All CLI options as keyword arguments
-**Usage:** `solace-agent-mesh init [OPTIONS]`
-
-### Key CLI Options
-- `--skip`: Non-interactive mode using defaults
-- `--gui`: Launch web-based configuration interface
-- `--broker-type`: Choose broker type (1=existing, 2=container, 3=dev)
-- `--llm-*`: LLM service configuration options
-- `--agent-*`: Orchestrator agent configuration options
-- `--webui-*`: WebUI gateway configuration options
-
-### Core Orchestration Function
-```python
-def run_init_flow(
-    skip_interactive: bool,
-    use_web_based_init_flag: bool,
-    **cli_options
-) -> None
-```
-**Purpose:** Orchestrates the complete initialization process
-**Parameters:**
-- `skip_interactive`: Skip all prompts, use defaults
-- `use_web_based_init_flag`: Use web interface for configuration
-- `**cli_options`: All CLI option values
-
-## 3. Key Dependencies and Imports
-
-### External Dependencies
-- `click`: CLI framework for commands and options
-- `pathlib.Path`: File system path operations
-- `yaml`: YAML configuration file processing
-- `multiprocessing`: Web portal process management
-- `webbrowser`: Automatic browser launching
-
-### Internal Dependencies
-- `...utils`: Utility functions (`ask_if_not_provided`, `ask_yes_no_question`, `load_template`)
-- `config_portal.backend.server`: Web-based configuration interface
-
-## 4. Data Structures and Models
-
-### DEFAULT_INIT_VALUES Dictionary
-```python
-DEFAULT_INIT_VALUES: Dict[str, Any] = {
-    # Broker Configuration
-    "broker_type": "1",  # str - Default to existing Solace broker
-    "broker_url": "ws://localhost:8008",  # str
-    "broker_vpn": "default",  # str
-    "broker_username": "default",  # str
-    "broker_password": "default",  # str
-    "container_engine": "docker",  # str - "docker" | "podman"
-    
-    # Environment Variables
-    "SOLACE_LOCAL_BROKER_URL": "ws://localhost:8008",  # str
-    "SOLACE_LOCAL_BROKER_VPN": "default",  # str
-    "SOLACE_LOCAL_BROKER_USERNAME": "default",  # str
-    "SOLACE_LOCAL_BROKER_PASSWORD": "default",  # str
-    "DEV_BROKER_URL": "ws://localhost:8008",  # str
-    "DEV_BROKER_VPN": "default",  # str
-    "DEV_BROKER_USERNAME": "default",  # str
-    "DEV_BROKER_PASSWORD": "default",  # str
-    
-    # LLM Configuration
-    "llm_endpoint_url": "YOUR_LLM_ENDPOINT_URL_HERE",  # str
-    "llm_api_key": "YOUR_LLM_API_KEY_HERE",  # str
-    "llm_planning_model_name": "YOUR_LLM_PLANNING_MODEL_NAME_HERE",  # str
-    "llm_general_model_name": "YOUR_LLM_GENERAL_MODEL_NAME_HERE",  # str
-    
-    # Project Configuration
-    "namespace": "solace_app/",  # str - Must end with "/"
-    "dev_mode": "false",  # str - "true" | "false"
-    
-    # WebUI Gateway Configuration
-    "add_webui_gateway": True,  # bool
-    "webui_session_secret_key": str,  # str - From ENV_DEFAULTS
-    "webui_fastapi_host": str,  # str - From ENV_DEFAULTS
-    "webui_fastapi_port": int,  # int - From ENV_DEFAULTS
-    "webui_enable_embed_resolution": bool,  # bool - From ENV_DEFAULTS
-    "webui_frontend_welcome_message": str,  # str
-    "webui_frontend_bot_name": "Solace Agent Mesh",  # str
-    "webui_frontend_collect_feedback": False,  # bool
-    
-    # Orchestrator Configuration (flattened from ORCHESTRATOR_DEFAULTS)
-    "agent_name": "OrchestratorAgent",  # str
-    "supports_streaming": True,  # bool
-    "session_service_type": "memory",  # str - "memory" | "vertex_rag"
-    "session_service_behavior": "PERSISTENT",  # str - "PERSISTENT" | "RUN_BASED"
-    "artifact_service_type": "filesystem",  # str - "memory" | "filesystem" | "gcs"
-    "artifact_service_base_path": "/tmp/samv2",  # str
-    "artifact_service_scope": "namespace",  # str - "namespace" | "app" | "custom"
-    "artifact_handling_mode": "embed",  # str - "ignore" | "embed" | "reference"
-    "enable_embed_resolution": True,  # bool
-    "enable_artifact_content_instruction": True,  # bool
-    "agent_card_description": str,  # str
-    "agent_card_default_input_modes": str,  # str - comma-separated
-    "agent_card_default_output_modes": str,  # str - comma-separated
-    "agent_discovery_enabled": True,  # bool
-    "agent_card_publishing_interval": 10,  # int - seconds
-    "inter_agent_communication_allow_list": "*",  # str - comma-separated
-    "inter_agent_communication_deny_list": "",  # str - comma-separated
-    "inter_agent_communication_timeout": 30,  # int - seconds
-}
-```
-
-### ORCHESTRATOR_DEFAULTS Configuration
-```python
-ORCHESTRATOR_DEFAULTS: Dict[str, Any] = {
-    "agent_name": "OrchestratorAgent",  # str
-    "supports_streaming": True,  # bool
-    "artifact_handling_mode": "embed",  # str
-    "enable_embed_resolution": True,  # bool
-    "enable_artifact_content_instruction": True,  # bool
-    "session_service": {
-        "type": "memory",  # str - "memory" | "vertex_rag"
-        "default_behavior": "PERSISTENT"  # str - "PERSISTENT" | "RUN_BASED"
-    },
-    "artifact_service": {
-        "type": "filesystem",  # str - "memory" | "filesystem" | "gcs"
-        "base_path": "/tmp/samv2",  # str
-        "artifact_scope": "namespace"  # str - "namespace" | "app" | "custom"
-    },
-    "agent_card": {
-        "description": str,  # str - Agent description
-        "defaultInputModes": ["text"],  # List[str]
-        "defaultOutputModes": ["text", "file"],  # List[str]
-        "skills": []  # List[str]
-    },
-    "agent_card_publishing": {
-        "interval_seconds": 10  # int
-    },
-    "agent_discovery": {
-        "enabled": True  # bool
-    },
-    "inter_agent_communication": {
-        "allow_list": ["*"],  # List[str]
-        "request_timeout_seconds": 30  # int
-    }
-}
-```
-
-### ENV_DEFAULTS Configuration
-```python
-ENV_DEFAULTS: Dict[str, str] = {
-    "LLM_SERVICE_ENDPOINT": "YOUR_LLM_SERVICE_ENDPOINT_HERE",
-    "LLM_SERVICE_API_KEY": "YOUR_LLM_SERVICE_API_KEY_HERE", 
-    "LLM_SERVICE_PLANNING_MODEL_NAME": "YOUR_LLM_SERVICE_PLANNING_MODEL_NAME_HERE",
-    "LLM_SERVICE_GENERAL_MODEL_NAME": "YOUR_LLM_SERVICE_GENERAL_MODEL_NAME_HERE",
-    "NAMESPACE": "my_project_namespace/",
-    "SOLACE_BROKER_URL": "ws://localhost:8008",
-    "SOLACE_BROKER_VPN": "default",
-    "SOLACE_BROKER_USERNAME": "default", 
-    "SOLACE_BROKER_PASSWORD": "default",
-    "SOLACE_DEV_MODE": "false",
-    "SESSION_SECRET_KEY": "please_change_me_in",
-    "FASTAPI_HOST": "127.0.0.1",
-    "FASTAPI_PORT": "8000",
-    "ENABLE_EMBED_RESOLUTION": "true",
-}
-```
-
-### WEBUI_GATEWAY_DEFAULTS Configuration
-```python
-WEBUI_GATEWAY_DEFAULTS: Dict[str, Any] = {
-    "webui_frontend_welcome_message": "",  # str
-    "webui_frontend_bot_name": "Solace Agent Mesh",  # str
-    "webui_frontend_collect_feedback": False,  # bool
-    "webui_session_secret_key": "please_change_me_in",  # str
-    "webui_fastapi_host": "127.0.0.1",  # str
-    "webui_fastapi_port": 8000,  # int
-    "webui_enable_embed_resolution": True,  # bool
-}
-```
-
-## 5. Step Functions
-
-### broker_setup_step Function
-```python
-def broker_setup_step(
-    options: dict, 
-    default_values: dict, 
-    skip_interactive: bool
-) -> dict
-```
-**Purpose:** Configures broker connection settings
-**Parameters:**
-- `options`: Mutable configuration dictionary
-- `default_values`: Default values for prompts
-- `skip_interactive`: Skip user prompts if True
-**Returns:** Updated options dictionary
-**Side Effects:** May start Docker/Podman containers for local broker
-
-### create_project_directories Function
-```python
-def create_project_directories(project_root: Path) -> bool
-```
-**Purpose:** Creates standard project directory structure
-**Parameters:**
-- `project_root`: Root directory for the project
-**Returns:** True on success, False on failure
-**Creates:**
-- `configs/`
-- `configs/gateways/`
-- `configs/agents/`
-- `src/`
-
-### create_project_files Function
-```python
-def create_project_files(project_root: Path) -> bool
-```
-**Purpose:** Creates standard project files
-**Parameters:**
-- `project_root`: Root directory for the project
-**Returns:** True on success, False on failure
-**Creates:**
-- `src/__init__.py`
-- `requirements.txt` (with solace-agent-mesh dependency)
-
-### create_env_file Function
-```python
-def create_env_file(
-    project_root: Path, 
-    options: dict, 
-    skip_interactive: bool
-) -> bool
-```
-**Purpose:** Creates .env file with environment variables
-**Parameters:**
-- `project_root`: Root directory for the project
-- `options`: Configuration values
-- `skip_interactive`: Skip user prompts if True
-**Returns:** True on success, False on failure
-**Creates:** `.env` file with all necessary environment variables
-
-### create_orchestrator_config Function
-```python
-def create_orchestrator_config(
-    project_root: Path, 
-    options: dict, 
-    skip_interactive: bool
-) -> bool
-```
-**Purpose:** Creates orchestrator agent configuration files
-**Parameters:**
-- `project_root`: Root directory for the project
-- `options`: Configuration values
-- `skip_interactive`: Skip user prompts if True
-**Returns:** True on success, False on failure
-**Creates:**
-- `configs/shared_config.yaml`
-- `configs/agents/main_orchestrator.yaml`
-
-### create_webui_gateway_config Function
-```python
-def create_webui_gateway_config(
-    project_root: Path, 
-    options: dict, 
-    skip_interactive: bool, 
-    default_values: dict
-) -> bool
-```
-**Purpose:** Creates WebUI gateway configuration
-**Parameters:**
-- `project_root`: Root directory for the project
-- `options`: Configuration values
-- `skip_interactive`: Skip user prompts if True
-- `default_values`: Default values for prompts
-**Returns:** True on success, False on failure
-**Creates:** `configs/gateways/webui.yaml` (if enabled)
-
-### perform_web_init Function
-```python
-def perform_web_init(current_cli_params: dict) -> dict
-```
-**Purpose:** Launches web-based configuration interface
-**Parameters:**
-- `current_cli_params`: Current CLI parameter values
-**Returns:** Updated configuration dictionary with web form values
-**Side Effects:**
-- Starts Flask server on port 5002
-- Opens browser to configuration portal
-- Blocks until configuration is complete
-
-## 6. Architecture Patterns Used
-
-### Step-Based Pipeline Pattern
-The initialization process follows a sequential step pattern where each step:
-- Receives an options dictionary
-- Performs its specific configuration task
-- Updates the options dictionary for subsequent steps
-- Returns success/failure status
-
-### Template-Based Configuration Generation
-Configuration files are generated using template replacement:
-- Templates contain `__PLACEHOLDER__` markers
-- Values from options dictionary replace placeholders
-- Supports both simple string replacement and YAML anchor references
-
-### Multi-Modal Interface Pattern
-Supports both CLI and web-based configuration:
-- CLI mode: Interactive prompts with defaults
-- Web mode: Browser-based form interface
-- Skip mode: Non-interactive using defaults/CLI args
-
-### Hierarchical Defaults Pattern
-Configuration values are resolved in priority order:
-1. CLI arguments (highest priority)
-2. Web form values
-3. Interactive prompts
-4. Default values (lowest priority)
-
-## 7. Integration Points with Other Systems
-
-### CLI Framework Integration
-- Integrates with Click command framework
-- Inherits from parent CLI structure
-- Uses shared utility functions from `...utils`
-
-### Template System Integration
-- Uses `load_template()` utility to load YAML templates
-- Templates stored in CLI package template directory
-- Supports dynamic placeholder replacement
-
-### Container Runtime Integration
-- Detects and uses Docker or Podman for local broker setup
-- Executes container commands via `os.system()`
-- Validates container runtime availability
-
-### Web Portal Integration
-- Launches separate Flask process for web configuration
-- Uses multiprocessing for inter-process communication
-- Automatically opens browser to configuration URL
-
-### File System Integration
-- Creates project directory structure
-- Generates configuration files in standard locations
-- Creates environment files with proper formatting
-
-### Environment Variable Integration
-- Generates `.env` files for runtime configuration
-- Maps CLI options to environment variable names
-- Supports secure handling of sensitive values (passwords, API keys)
-
-The init_cmd system provides a comprehensive, user-friendly way to bootstrap new Solace Agent Mesh projects with proper configuration, directory structure, and integration setup.