Querying HMS Documentation

Primary Sources

Production Agent

Location: hms_agents/hms_doc_query/

Quick access:

• QUICK_START.md - 5-minute guide
• AGENT.md - Comprehensive documentation
• doc_query.py - Query implementation

This agent queries official documentation via web requests to HEC documentation servers.

Documentation Sources

Official USACE Documentation

Community Resources

When to Use This Skill

Use When

1. Method Documentation

   • "What parameters does Clark Unit Hydrograph require?"
   • "How does Green-Ampt loss method work?"
   • "What's the difference between ModClark and Clark?"

2. File Format Questions

   • "What is the structure of a .control file?"
   • "How are gages defined in .gage files?"
   • "What DSS pathname format does HMS use?"

3. Version-Specific Features

   • "Is gridded soil moisture available in HMS 4.10?"
   • "What new features were added in HMS 4.11?"
   • "When was the EAP transform introduced?"

4. Workflow Guidance

   • "How do I set up gridded precipitation?"
   • "How do I configure a reservoir routing model?"
   • "What's the workflow for calibration?"

5. Troubleshooting

   • "What does WARNING 10020 mean?"
   • "Why am I getting NullPointerException?"
   • "How do I fix 'Project not found' errors?"

Don't Use When

1. Internal Implementation Details

   • Use hms_investigate_internals skill instead
   • hms_investigate_internals has decompiled source code

2. JythonHms API Reference

   • Use hms_investigate_internals skill
   • Decompiled JythonHms.java has complete method signatures

3. Undocumented Features

   • Official docs won't cover undocumented behavior
   • Use hms_investigate_internals for source code analysis

4. hms-commander API Questions

   • Read hms-commander docstrings directly
   • Check examples/ notebooks

Query Functions

query_documentation()

Main function to query HMS documentation.

Parameters:

• question (str): The technical question
• focus_area (str): Narrow search
  • "loss_methods", "transform_methods", "routing_methods"
  • "file_formats", "workflows", "release_notes"
  • "installation", "troubleshooting"
• hms_version (str): Target version (e.g., "4.11")

get_method_parameters()

Get parameter details for specific HMS method.

Parameters:

• method_type (str): "loss", "transform", "baseflow", "routing"
• method_name (str): Name of the method

search_release_notes()

Search HMS release notes.

Parameters:

• query (str): Search query
• version (str): Specific version to search

validate_method_name()

Check if method name is valid in HMS.

Parameters:

• method_name (str): Method name to validate
• method_type (str): "loss", "transform", etc.

Common Questions

Loss Methods

Transform Methods

Routing Methods

File Formats

Known Limitations

Image/Screenshot Support

IMPORTANT: HMS documentation relies heavily on screenshots and diagrams.

• WebFetch retrieves TEXT content from documentation pages
• Images are REFERENCED but NOT RENDERED
• Agent cannot describe UI screenshots or visual diagrams
• Agent CAN identify when images exist and reference captions

Workaround: Agent provides URLs for manual viewing when visual content is needed.

Other Limitations

• Cannot access local HMS installation help files
• PDF manuals require direct URLs
• Community forums have varying quality
• Version differences may not be clearly documented

Complementary Skills

hms_investigate_internals

Purpose: Decompiled source code analysis

Complementary use:

Related Skills

• hms_parse_basin-models - Working with basin files
• hms_execute_runs - Running simulations
• hms_manage_versions - Version detection and handling

Integration with hms-commander

This skill supports hms-commander development by providing:

1. Method Validation: Verify method names and parameters before use
2. File Format Guidance: Understand file structures when parsing
3. Version Compatibility: Check feature availability across versions
4. Troubleshooting Context: Interpret error messages

Example workflow:

# 1. Query documentation for method parameters
# Use hms_doc_query to verify "Deficit and Constant" parameters

# 2. Set parameters with confidence
from hms_commander import HmsBasin
HmsBasin.set_loss_parameters(
    "model.basin", "Sub1",
    method="Deficit and Constant",
    initial_deficit=0.5,
    maximum_deficit=1.0,
    constant_rate=0.2,
    impervious_percent=10
)

Skill Workflow

Standard Query Flow

User Question
    |
    v
Identify Focus Area
    |-- loss_methods, transform_methods, routing_methods
    |-- file_formats, workflows, release_notes
    |-- installation, troubleshooting
    |
    v
Query Documentation (hms_doc_query)
    |
    v
Return Answer + Source URLs
    |
    v
Provide URL for Visual Content (if needed)

When to Escalate to Code Analysis

Documentation Query
    |
    v
Answer Found? --> YES --> Return Answer
    |
    NO
    |
    v
Undocumented Feature?
    |
    v
Use hms_investigate_internals
    |
    v
Decompile and Analyze Source

Quality Checklist

Before answering user questions:

• Identified appropriate focus area
• Queried correct documentation source
• Provided source URLs for verification
• Noted when visual content exists but cannot be shown
• Suggested hms_investigate_internals for undocumented features
• Pointed to primary sources (not duplicated content)

Quick Reference

Common questions -> Focus areas:

Agent location: hms_agents/hms_doc_query/

Documentation URLs:

• User's Manual: https://www.hec.usace.army.mil/confluence/hmsdocs/hmsum/latest/
• Technical Reference: https://www.hec.usace.army.mil/confluence/hmsdocs/hmstrm/latest/

Status: Production skill Version: 1.0 Created: 2025-12-17 Agent: hms_doc_query