LLM Forward Approach - Overview¶

HMS Commander implements CLB Engineering's LLM Forward approach for hydrologic model automation.

What is LLM Forward?¶

The LLM Forward approach is a methodology for building engineering software that enables AI-assisted workflows while maintaining professional standards and client trust.

Five Core Principles¶

1. 🖥️ GUI Verifiable¶

All changes must be inspectable in the native software GUI.

In HMS Commander: - Clone operations create new components visible in HEC-HMS - Parameter changes can be verified in the GUI - Results can be compared visually in HMS results viewer

# Create cloned basin - appears in HMS GUI
HmsBasin.clone_basin(
    template="Original",
    new_name="Modified"
)
# Both basins now visible in Components Manager

2. 📋 Traceable¶

Complete audit trail of all operations.

In HMS Commander: - All operations logged with @log_call decorator - Clone descriptions document modifications - Version control tracks all changes

# Clone with metadata
HmsRun.clone_run(
    source_run="Baseline",
    new_run_name="Calibrated",
    description="CN adjusted to 85 based on 2020 storm calibration"
)
# Description visible in HMS GUI and project files

3. ✅ QAQC-able¶

Automated quality checks and comparison workflows.

In HMS Commander: - Side-by-side model comparison - Automated result validation - Acceptance criteria checking

# Compare baseline vs. updated
comparison = HmsResults.compare_runs(
    dss_files=["baseline.dss", "updated.dss"],
    element="Outlet"
)
# Automated diff report

4. 🔒 Non-Destructive¶

Original models always preserved.

In HMS Commander: - Clone operations never modify templates - Separate output files for each run - Rollback capability through version control

# Template preserved, modifications in clone
HmsBasin.clone_basin(template="Original", new_name="Test")
HmsBasin.set_loss_parameters("Test.basin", "Sub1", curve_number=85)
# Original.basin unchanged

5. 📄 Professional Documentation¶

Client-ready reports and documentation.

In HMS Commander: - Auto-generated API documentation - Comprehensive user guides - Example notebooks - Comparison reports

Why LLM Forward Matters¶

Traditional engineering software workflow:

Engineer → Manual GUI clicks → Model updates → Results

AI-assisted workflow without LLM Forward:

AI → Black box changes → ??? → Hope it worked

LLM Forward workflow:

AI → Traceable operations → GUI verification → Documented results

LLM Forward in Practice¶

Example: Atlas 14 Update Workflow¶

# 1. Clone for comparison (Non-Destructive)
HmsMet.clone_met("TP40_Met", "Atlas14_Met",
                  description="NOAA Atlas 14 update per client request")

# 2. Make traceable changes
HmsMet.update_tp40_to_atlas14("Atlas14_Met.met", atlas14_depths)
# Logged: Updated 6 precipitation depths

# 3. Create QAQC run
HmsRun.clone_run("Baseline", "Atlas14_Comparison",
                  new_met="Atlas14_Met", output_dss="atlas14.dss")

# 4. Execute and verify (GUI Verifiable)
HmsCmdr.compute_parallel(["Baseline", "Atlas14_Comparison"])

# 5. Generate professional comparison
comparison = HmsResults.compare_runs(
    ["baseline.dss", "atlas14.dss"], "Outlet"
)
# Client-ready report

Result: Engineer can: - ✅ Verify changes in HMS GUI - ✅ See complete audit trail in logs - ✅ Run automated comparisons - ✅ Roll back if needed - ✅ Deliver professional comparison report to client

Benefits for Engineering Firms¶

Client Trust - All work is verifiable and documented
Quality Assurance - Automated checks catch errors
Efficiency - AI handles repetitive tasks
Knowledge Retention - Code and docs capture expertise
Regulatory Compliance - Complete audit trail

Benefits for AI Assistants¶

Structured Patterns - Clear workflows to follow
Verification - GUI confirms operations succeeded
Error Recovery - Non-destructive allows retries
Documentation - Self-documenting code
Trust - Users can verify AI's work

Contributing - Development guidelines
Architecture - Technical implementation
Agent Instructions Guide - shared AGENTS/Claude loading model
Style Guide - Coding standards

Learn More¶

CLB Engineering Resources: - Website: https://clbengineering.com/ - Insights: https://clbengineering.com/insights

HMS Commander is built on the LLM Forward approach from inception.