Re-org Nework to allow user-defined layout and network name

AGENTS.md

@@ -1,6 +1,6 @@
 # Guidelines for LLMs
 
-**Creating new documentation**:
+**Creating new documentation for agents (e.g. AGENTS.md` or `CLAUDE.md`)**:
 - **Always** create context-specific documentation as `AGENTS.md` (not `CLAUDE.md`)
 - **Always** symlink the new `AGENTS.md` file as `CLAUDE.md` in the same directory
 - **Don't create AGENTS.md in every directory** - Only create when the directory contains complex patterns that aren't obvious from code
@@ -27,6 +27,7 @@
 - **Focus on patterns, not details** - What to do, not why it exists
 - **Scannable structure** - Use headers, bullets, and short paragraphs
 - **Reference, don't explain** - Link to related files instead of duplicating information
+- **No emoticons in code** - Never add emoji or emoticons to code files, comments, or print statements
 
 **Good example structure**:
 ```markdown
@@ -46,7 +47,7 @@
 - `file.py` - Purpose
 ```
 
-**Updating existing documentation**:
+**Updating existing agent documentation**:
 - **IMPORTANT**: When making code changes in a directory, ALWAYS update the corresponding `AGENTS.md` file in that directory
 - If no `AGENTS.md` exists in the directory where you're making changes, create one following the structure above
 - Keep documentation synchronized with code changes to help other LLMs understand the current state
@@ -55,6 +56,20 @@
 - Focus on architectural patterns, state management, data flow, and key concepts that aren't obvious from code alone
 - If you need to preserve detailed explanations, move them to a separate `*_GUIDE.md` file for human readers
 
+**Code quality directives**:
+- **Extract meaningful patterns, not trivial wrappers** - Only create helper functions when they add real value:
+  - ✅ **DO extract** when:
+    - Logic must be done in a specific way to avoid bugs (e.g., `get_next_node_name()` - prevents duplicates)
+    - Complex workflow logic that's hard to understand inline (e.g., multi-step validation)
+    - Algorithm that requires deep understanding to get right
+    - Pattern that encapsulates important business rules
+  - ❌ **DON'T extract** when:
+    - It's just a 1-2 line wrapper around existing functions
+    - It's standard library usage (file I/O, simple pandas operations)
+    - The abstraction obscures rather than clarifies intent
+    - It would be clearer to just write inline
+  - **Rule of thumb**: If the helper function is shorter/simpler than its call sites, don't extract it
+
 **Directory-specific AGENTS.md files**:
 - `cea/databases/AGENTS.md` - Database structure, COMPONENTS vs ASSEMBLIES
 - `cea/analysis/costs/AGENTS.md` - Cost calculation patterns
@@ -135,6 +150,7 @@ cea.api.demand(scenario='/path/to/scenario')
 4. **Multiprocessing**: Check `config.multiprocessing` before using `Pool`
 5. **Scenario Structure**: Respect `/inputs/`, `/outputs/` conventions
 6. **Config Type Hints**: After modifying `config.py`, regenerate `config.pyi` by running `pixi run python cea/utilities/config_type_generator.py`
+7. **F-strings**: Only use f-strings when string contains variables (e.g., `f"Value: {x}"`). Use regular strings otherwise (e.g., `"No variables"`) to avoid linter warnings
 
 ## Module Documentation
 

cea/AGENTS.md

@@ -0,0 +1,122 @@
+# Configuration Parameters
+
+## Main API
+
+- `Parameter.decode(value: str) → Any` - Parse value from config file (lenient)
+- `Parameter.encode(value: Any) → str` - Validate value before saving (strict)
+- `ChoiceParameter._choices → list[str]` - Available options (can be dynamic via `@property`)
+
+## Key Pattern: decode() vs encode()
+
+### ✅ DO: Separate parsing from validation
+
+```python
+class MyParameter(Parameter):
+    def decode(self, value):
+        """Parse - security checks only"""
+        if not value:
+            return ""
+        value = value.strip()
+
+        # Only validate security concerns (path traversal, injection, etc.)
+        if self._has_security_issue(value):
+            raise ValueError("Security violation")
+
+        return value  # Don't check business rules
+
+    def encode(self, value):
+        """Validate - all business rules"""
+        if not value or not value.strip():
+            raise ValueError("Value required")
+
+        value = value.strip()
+
+        # Security check
+        if self._has_security_issue(value):
+            raise ValueError("Security violation")
+
+        # Business rule check
+        if self._resource_exists(value):
+            raise ValueError(f"Resource '{value}' already exists")
+
+        return value
+```
+
+### ❌ DON'T: Validate business rules in decode()
+
+```python
+def decode(self, value):
+    # ❌ Expensive I/O on every config load
+    if not self._resource_exists(value):
+        raise ValueError("Resource not found")
+
+    # ❌ Breaks loading old configs when resources deleted
+    if self._check_collision(value):
+        raise ValueError("Already exists")
+
+    return value
+```
+
+**Why**: decode() is called when loading config files - must be lenient and fast.
+
+## Dynamic Choices
+
+### ✅ DO: Use @property for dynamic choices
+
+```python
+class DynamicChoiceParameter(ChoiceParameter):
+    def initialize(self, parser):
+        self.depends_on = ['other-param']  # Declare dependencies
+
+    @property
+    def _choices(self):
+        """Scan resources on each access"""
+        return self._get_available_options()
+
+    def _get_available_options(self):
+        # Scan filesystem/database for available options
+        if not self._can_scan():
+            return []
+
+        # Return list of valid choices
+        return self._scan_resources()
+```
+
+## Validation Helpers
+
+Extract shared validation into helpers:
+
+```python
+def _validate_security(self, value):
+    """Security checks (used by encode AND decode)"""
+    invalid_chars = ['/', '\\', ':', '*', '?', '"', '<', '>', '|']
+    if any(char in value for char in invalid_chars):
+        raise ValueError("Invalid characters")
+
+def _validate_business(self, value):
+    """Business rules (used by encode ONLY)"""
+    if self._resource_exists(value):
+        raise ValueError("Already exists")
+
+def decode(self, value):
+    return self._validate_security(value.strip())
+
+def encode(self, value):
+    self._validate_security(value.strip())
+    self._validate_business(value)
+    return value
+```
+
+## Common Pitfalls
+
+1. **Validating in decode()** → Fragile config loading
+2. **No dependency declaration** → Dynamic choices don't update
+3. **Caching without invalidation** → Stale options
+4. **Mixing security/business validation** → Security checks in both, business in encode only
+
+## Related Files
+
+- `config.py` - All parameter classes (PathParameter, ChoiceParameter, etc.)
+- `config.pyi` - Type stubs (regenerate: `pixi run python cea/utilities/config_type_generator.py`)
+- `default.config` - Default values for all parameters
+- `interfaces/dashboard/api/tools.py` - Validation API endpoints (`validate_field`, `get_parameter_metadata`)

cea/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

cea/config.py

@@ -427,11 +427,11 @@ def initialize(self, parser):
         the default.config
         """
 
-    def encode(self, value):
+    def encode(self, value) -> str:
         """Encode ``value`` to a string representation for writing to the configuration file"""
         return str(value)
 
-    def decode(self, value):
+    def decode(self, value) -> Any:
         """Decode ``value`` to the type supported by this Parameter"""
         return value
 
@@ -754,6 +754,69 @@ class StringParameter(Parameter):
     """Default Parameter type"""""
 
 
+class NetworkLayoutNameParameter(StringParameter):
+    """
+    Parameter for network layout names with collision detection.
+    Validates in real-time to prevent overwriting existing network layouts.
+    """
+
+    def _validate_network_name(self, value) -> str:
+        """
+        Validate network name for invalid characters and collision with existing networks.
+        """
+        value = value.strip()
+
+        # Check for invalid filesystem characters
+        invalid_chars = ['/', '\\', ':', '*', '?', '"', '<', '>', '|']
+        if any(char in value for char in invalid_chars):
+            raise ValueError(
+                f"Network name contains invalid characters. "
+                f"Avoid: {' '.join(invalid_chars)}"
+            )
+
+        # Check for collision with existing networks
+        scenario = self.config.scenario
+        locator = cea.inputlocator.InputLocator(scenario)
+
+        # Check network folder exists
+        network_folder = locator.get_thermal_network_folder_network_name_folder(value)
+        if os.path.exists(network_folder):
+            raise ValueError(
+                f"Network '{value}' already exists. "
+                f"Choose a different name or delete the existing network."
+            )
+
+        return value
+
+    def encode(self, value):
+        """
+        Validate and encode network name.
+        Raises ValueError if name contains invalid characters or collides with existing network.
+        """
+        if not str(value) or str(value).strip() == '':
+            raise ValueError("Network name is required. Please provide a valid name.")
+
+        return self._validate_network_name(str(value))
+
+    def decode(self, value):
+        """Parse and normalize network name from config file"""
+        if not value:
+            return ""
+
+        value = value.strip()
+
+        # Only validate filesystem characters (security concern)
+        # Don't check collision - that's encode's job when saving
+        invalid_chars = ['/', '\\', ':', '*', '?', '"', '<', '>', '|']
+        if any(char in value for char in invalid_chars):
+            raise ValueError(
+                f"Network name contains invalid characters. "
+                f"Avoid: {' '.join(invalid_chars)}"
+            )
+
+        return value
+
+
 class OptimizationIndividualListParameter(ListParameter):
     def initialize(self, parser):
         # allow the parent option to be set
@@ -803,6 +866,106 @@ def decode(self, value):
             return self._choices[0]
 
 
+class NetworkLayoutChoiceParameter(ChoiceParameter):
+    """
+    Parameter for selecting existing network layouts based on network type.
+    """
+
+    _network_types = {'DH', 'DC'}
+
+    def initialize(self, parser):
+        # Override to dynamically populate choices based on available networks
+        pass
+
+    @property
+    def _choices(self):
+        networks = self._get_available_networks()
+        sorted_networks = self._sort_networks_by_modification_time(networks)
+        return sorted_networks
+
+    def _get_available_networks(self) -> List[str]:
+        locator = cea.inputlocator.InputLocator(self.config.scenario)
+        network_folder = locator.get_thermal_network_folder()
+        if not os.path.exists(network_folder):
+            return []
+        return [name for name in os.listdir(network_folder)
+                if os.path.isdir(os.path.join(network_folder, name)) and name not in self._network_types]
+
+    def _get_network_file_paths(self, network_type: str, network_name: str) -> Tuple[str, str]:
+        """Get path for network node and edge files for the given network name"""
+        locator = cea.inputlocator.InputLocator(self.config.scenario)
+
+        network_type_folder = locator.get_output_thermal_network_type_folder(network_type, network_name)
+        # Remove trailing slash/separator if present
+        network_type_folder = network_type_folder.rstrip(os.sep)
+
+        edges_path = locator.get_network_layout_nodes_shapefile(network_type, network_name)
+        nodes_path = locator.get_network_layout_nodes_shapefile(network_type, network_name)
+
+        return edges_path, nodes_path
+
+    def _sort_networks_by_modification_time(self, network_names: List[str]) -> List[str]:
+        """Sort network layouts by modification time (most recent first)"""
+        modified_times = []
+        for network_name in network_names:
+            network_time = []
+            for network_type in self._network_types:
+                edges_path, nodes_path = self._get_network_file_paths(network_type, network_name)
+                if os.path.exists(edges_path) and os.path.exists(nodes_path):
+                    sort_time = os.path.getmtime(edges_path)
+                    network_time.append((network_name, sort_time))
+            if network_time:
+                # Get the most recent modification time across network types
+                most_recent_time = max(time for _, time in network_time)
+                modified_times.append((network_name, most_recent_time))
+
+        # Sort by modification time, most recent first
+        modified_times.sort(key=lambda x: x[1], reverse=True)
+        sorted_networks = [network_name for network_name, _ in modified_times]
+        return sorted_networks
+
+    def encode(self, value):
+        """
+        Validate and encode value.
+        Raises ValueError if the network layout doesn't exist.
+        """
+        # Empty value not allowed
+        if not value or str(value).strip() == '':
+            raise ValueError("Network layout is required. Please select a network layout.")
+
+        available_networks = self._get_available_networks()
+
+        # Validate that the network exists
+        if str(value) not in available_networks:
+            raise ValueError(
+                f"Network layout '{value}' not found. "
+                f"Available layouts: {', '.join(available_networks)}"
+            )
+        return str(value)
+
+    def decode(self, value):
+        """
+        Decode and validate value exists in available networks.
+        Returns the selected value if valid, otherwise returns the most recent network as default.
+
+        If no value provided and no networks found for current network-type, try to find
+        the most recent network across ALL network types and switch network-type accordingly.
+        """
+        available_networks = self._get_available_networks()
+
+        # If value is provided and valid, return it
+        if value and value in available_networks:
+            return value
+
+        # Otherwise, return the most recent network (first choice) if available
+        if available_networks:
+            sorted_networks = self._sort_networks_by_modification_time(available_networks)
+            most_recent_network = sorted_networks[0]
+            return most_recent_network
+
+        return ''
+
+
 class DatabasePathParameter(Parameter):
     """A parameter that can either be set to a region-specific CEA Database (e.g. CH or SG) or to a user-defined
     folder that has the same structure."""
@@ -989,7 +1152,10 @@ class SingleBuildingParameter(ChoiceParameter):
 
     def initialize(self, parser):
         # skip the default ChoiceParameter initialization of _choices
-        pass
+        try:
+            self.nullable = parser.getboolean(self.section.name, f"{self.name}.nullable")
+        except configparser.NoOptionError:
+            self.nullable = False
 
     @property
     def _choices(self):
@@ -999,8 +1165,15 @@ def _choices(self):
         if not building_names:
             raise cea.ConfigError("Either no buildings in zone or no zone geometry found.")
         return building_names
+
+    def decode(self, value):
+        if self.nullable and (value is None or value == ''):
+            return None
+        return super().decode(value)
 
     def encode(self, value):
+        if self.nullable and (value is None or value == ''):
+            return ''
         if str(value) not in self._choices:
             return self._choices[0]
         return str(value)