Adding gui hints to control input field size and drop down data sources.

 

GUI Hints Implementation Specification

Overview

This specification defines a system for providing GUI presentation hints to agents, enabling dropdown template selectors and intelligent tooltips for input fields. The system maintains complete separation between execution logic and presentation behavior.

Architecture Principles

1. Separation of Concerns: GUI hints are metadata only - they never affect execution logic
2. Optional Behavior: All GUI hints are optional overrides on default behavior
3. Graceful Degradation: Agents work perfectly without GUI hints (CLI, web service, testing)
4. Emergent Intelligence: Smart behavior emerges from simple rules, not hard-coded logic

Configuration Structure

Agent Definition with GUI Hints

json

{
  "agent_name": {
    "type": "proc",
    "help": "Agent description",
    "inputs": ["field1", "field2"],
    "optional_inputs": ["field3"],
    "outputs": ["result"],
    "function_def": "...",
    
    "gui_hints": {
      "field1": {
        "templates": "template_section_name",
        "width": "full|wide|normal",
        "height": "1|3|5|10"
      },
      "field2": {
        "width": "normal",
        "height": "1"
      }
    }
  }
}

Template Data Section

json

{
  "template_section_name": {
    "Display Name 1": "actual_value_string_1",
    "Display Name 2": "actual_value_string_2", 
    "Custom...": ""
  }
}

GUI Implementation

Field Rendering Logic

function renderInputField(fieldName, fieldConfig, currentValue, guiHints) {
  // 1. Create base input field
  const field = createInputField({
    name: fieldName,
    value: currentValue,
    width: guiHints?.width || 'normal',
    height: guiHints?.height || '1'
  });
  
  // 2. Add template dropdown if specified
  if (guiHints?.templates) {
    const dropdown = createTemplateDropdown(
      getTemplateSection(guiHints.templates),
      (selectedValue) => field.setValue(selectedValue)
    );
    field.addAdjacentElement(dropdown);
  }
  
  // 3. Add intelligent tooltip
  field.addTooltip(() => getIntelligentTooltip(field.getValue(), guiHints?.templates));
  
  return field;
}

Template Dropdown Behavior

function createTemplateDropdown(templateMap, onSelect) {
  const dropdown = new Dropdown();
  
  // Populate dropdown options
  Object.entries(templateMap).forEach(([displayName, value]) => {
    dropdown.addOption(displayName, () => onSelect(value));
  });
  
  return dropdown;
}

Intelligent Tooltip Logic

function getIntelligentTooltip(fieldValue, templateSectionName) {
  if (!templateSectionName) {
    return null; // No tooltip for non-template fields
  }
  
  const templateMap = getTemplateSection(templateSectionName);
  
  // Check for exact match with any template value
  for (const [displayName, templateValue] of Object.entries(templateMap)) {
    if (fieldValue === templateValue) {
      return displayName; // e.g., "Convert to Lowercase"
    }
  }
  
  // No exact match found
  return "Custom mapping";
}

Configuration Examples

Character Converter Agent

json

{
  "char_converter": {
    "type": "proc",
    "help": "Universal character converter using configurable character maps",
    "inputs": ["input_text", "char_map"],
    "outputs": ["converted_text"],
    "function_def": "def convert_characters(input_text, char_map, output)...",
    
    "gui_hints": {
      "input_text": {
        "width": "full",
        "height": "5"
      },
      "char_map": {
        "templates": "character_maps",
        "width": "full", 
        "height": "3"
      }
    }
  }
}

Template Data Section

json

{
  "character_maps": {
    "Convert to Lowercase": "A:a,B:b,C:c,D:d,E:e,F:f,G:g,H:h,I:i,J:j,K:k,L:l,M:m,N:n,O:o,P:p,Q:q,R:r,S:s,T:t,U:u,V:v,W:w,X:x,Y:y,Z:z",
    "Convert to Uppercase": "a:A,b:B,c:C,d:D,e:E,f:F,g:G,h:H,i:I,j:J,k:K,l:L,m:M,n:N,o:O,p:P,q:Q,r:R,s:S,t:T,u:U,v:V,w:W,x:X,y:Y,z:Z",
    "Leet Speak Transform": "a:4,e:3,i:1,o:0,s:5,t:7,A:4,E:3,I:1,O:0,S:5,T:7",
    "Remove Vowels": "a:,e:,i:,o:,u:,A:,E:,I:,O:,U:",
    "ROT13 Cipher": "a:n,b:o,c:p,d:q,e:r,f:s,g:t,h:u,i:v,j:w,k:x,l:y,m:z,n:a,o:b,p:c,q:d,r:e,s:f,t:g,u:h,v:i,w:j,x:k,y:l,z:m,A:N,B:O,C:P,D:Q,E:R,F:S,G:T,H:U,I:V,J:W,K:X,L:Y,M:Z,N:A,O:B,P:C,Q:D,R:E,S:F,T:G,U:H,V:I,W:J,X:K,Y:L,Z:M",
    "HTML Escape": "<:&lt;,>:&gt;,&:&amp;,\":&quot;,':%27",
    "URL Encode Spaces": " :%20,!:%21,\":%22,#:%23,$:%24,%:%25,&:%26,':%27,(:%28,):%29",
    "Remove Accents": "á:a,à:a,â:a,ä:a,ã:a,é:e,è:e,ê:e,ë:e,í:i,ì:i,î:i,ï:i,ó:o,ò:o,ô:o,ö:o,õ:o,ú:u,ù:u,û:u,ü:u,ñ:n,ç:c",
    "Custom...": ""
  }
}

User Experience Flow

Scenario 1: Template Selection

1. User sees input field with adjacent dropdown
2. User clicks dropdown, sees friendly names: "Convert to Lowercase", "Leet Speak Transform", etc.
3. User selects "Convert to Lowercase"
4. GUI fills field with mapping string: "A:a,B:b,C:c..."
5. Tooltip displays: "Convert to Lowercase"

Scenario 2: Custom Modification

1. User has selected a template (tooltip shows "Convert to Lowercase")
2. User modifies the field content: "A:a,B:b,C:c,X:×"
3. Tooltip immediately updates to: "Custom mapping"
4. User can continue editing or select a different template

Scenario 3: Manual Entry

1. User types directly in field: "hello:world,foo:bar"
2. Tooltip shows: "Custom mapping"
3. No template dropdown interaction needed

Technical Requirements

GUI Framework Integration

• Field rendering must support dynamic width/height sizing
• Dropdown must be positioned adjacent to target field
• Tooltip must update in real-time as field content changes
• Template selection must trigger field value replacement

Performance Considerations

• Template comparison should use string equality (O(1) hash lookup preferred)
• Tooltip updates should be debounced to avoid excessive DOM updates
• Template data should be loaded once and cached

Error Handling

• Missing template sections should gracefully degrade (no dropdown shown)
• Invalid GUI hint values should fall back to defaults
• Template data loading failures should not break field functionality

Extension Points

Future Template Types

• Regex patterns: For validation templates
• Code snippets: For function_def templates
• File paths: For common directory templates
• URLs: For endpoint templates

Advanced GUI Behaviors

• Multi-select dropdowns: For list-type inputs
• Hierarchical templates: Nested template categories
• Conditional hints: Different hints based on other field values
• Template validation: Real-time validation against template patterns

Implementation Phases

Phase 1: Basic Template Dropdown

• Implement template section loading
• Add dropdown rendering for template-enabled fields
• Implement template value replacement on selection

Phase 2: Intelligent Tooltips

• Add tooltip comparison logic
• Implement real-time tooltip updates
• Add "Custom mapping" fallback behavior

Phase 3: Layout Control

• Implement width/height GUI hints
• Add responsive field sizing
• Test layout behavior across different screen sizes

Phase 4: Template Management

• Add template section validation
• Implement template sharing across agents
• Add template import/export capabilities