# 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.