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

solace_agent_mesh/cli/commands/init_cmd/init_cmd_llm.txt

@@ -0,0 +1,365 @@
+# 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.