Class AutomationDiagnostics

java.lang.Object
neqsim.process.automation.AutomationDiagnostics
All Implemented Interfaces:
Serializable
public class AutomationDiagnostics extends Object implements Serializable
Provides self-diagnosis, fuzzy matching, and error-recovery capabilities for the ProcessAutomation API. When an agent uses an incorrect address, unit name, or property, this class supplies structured remediation hints including closest-match suggestions and auto-correction.

Also tracks operation history to learn from failures and provide accumulated insights.

Key Capabilities:

  • Fuzzy name resolution — finds closest unit/property when exact match fails
  • Auto-correction — fixes common mistakes (casing, whitespace, partial names)
  • Structured diagnostics — returns JSON with error category, suggestions, and fix actions
  • Operation history — tracks successes/failures to improve over time
  • Physical validation — warns when values are outside reasonable bounds
Version:
1.0
Author:
Even Solbraa
See Also:

  • Field Details

  • Constructor Details

    • AutomationDiagnostics

      public AutomationDiagnostics()
      Creates an AutomationDiagnostics instance with default history size (1000).

    • AutomationDiagnostics

      public AutomationDiagnostics(int maxHistorySize)
      Creates an AutomationDiagnostics instance with a specified history size.
      Parameters:
      maxHistorySize - maximum number of operation records to keep

  • Method Details

    • findClosestNames

      public List<String> findClosestNames(String input, List<String> validNames, int maxResults)
      Finds the closest matching unit name from a list of valid names using edit distance.
      Parameters:
      input - the input name that was not found
      validNames - the list of valid names to search
      maxResults - maximum number of suggestions to return
      Returns:
      ranked list of closest matches

    • autoCorrectName

      public String autoCorrectName(String input, List<String> validNames)
      Attempts auto-correction of a unit name by trying common transformations.

      Tries: case-insensitive match, trimmed whitespace, partial substring match, and previously learned corrections.

      Parameters:
      input - the unit name to correct
      validNames - the list of valid names
      Returns:
      the corrected name, or null if no confident correction found

    • diagnoseUnitNotFound

      public AutomationDiagnostics.DiagnosticResult diagnoseUnitNotFound(String unitName, List<String> validUnits)
      Diagnoses a unit-not-found error and returns structured remediation.
      Parameters:
      unitName - the name that was not found
      validUnits - list of valid unit names in the process
      Returns:
      diagnostic result with suggestions and auto-correction

    • diagnosePropertyNotFound

      public AutomationDiagnostics.DiagnosticResult diagnosePropertyNotFound(String address, String unitName, String propertyName, List<SimulationVariable> validVariables)
      Diagnoses a property-not-found error and returns structured remediation.
      Parameters:
      address - the full address that was not resolved
      unitName - the unit name
      propertyName - the property that was not found
      validVariables - the valid variables for that unit
      Returns:
      diagnostic result with suggestions and auto-correction

    • diagnosePortNotFound

      public AutomationDiagnostics.DiagnosticResult diagnosePortNotFound(String address, String unitName, String portName, List<String> validPorts)
      Diagnoses a port-not-found error.
      Parameters:
      address - the full address
      unitName - the unit name
      portName - the port that was not found
      validPorts - known valid port names for the equipment type
      Returns:
      diagnostic result with suggestions

    • validatePhysicalBounds

      public AutomationDiagnostics.DiagnosticResult validatePhysicalBounds(String propertyName, double value, String unit)
      Validates a value against known physical bounds for a property.
      Parameters:
      propertyName - the property being set
      value - the value to validate
      unit - the unit of the value
      Returns:
      diagnostic result if out of bounds, null if valid

    • recordSuccess

      public void recordSuccess(String operationType, String address)
      Records a successful operation.
      Parameters:
      operationType - the type of operation (get, set, list)
      address - the address used

    • recordFailure

      public void recordFailure(String operationType, String address, AutomationDiagnostics.ErrorCategory category, String correction)
      Records a failed operation with its correction.
      Parameters:
      operationType - the type of operation (get, set, list)
      address - the address that failed
      category - the error category
      correction - the correction that was applied, or null

    • getSuccessRate

      public double getSuccessRate()
      Gets the success rate for recent operations.
      Returns:
      success rate as fraction (0.0 to 1.0)

    • getErrorCategoryCounts

      public Map<String,Integer> getErrorCategoryCounts()
      Gets the most common error categories from operation history.
      Returns:
      map of error category to count, sorted by frequency

    • getLearnedCorrections

      public Map<String,String> getLearnedCorrections()
      Gets the learned corrections that can be applied automatically in future calls.
      Returns:
      unmodifiable map of input to corrected values

    • getOperationCount

      public int getOperationCount()
      Gets the total number of operations recorded.
      Returns:
      operation count

    • getLearningReport

      public String getLearningReport()
      Generates a learning report summarizing patterns from operation history.
      Returns:
      JSON string with operation statistics and learned corrections

    • reset

      public void reset()
      Clears the operation history and learned corrections.

    • computeMatchScore

      private double computeMatchScore(String input, String valid)
      Computes a match score between two strings (higher is better).
      Parameters:
      input - the input string (already lowercased)
      valid - the valid string (already lowercased)
      Returns:
      score from 0.0 (no match) to 1.0 (exact match)

    • editDistance

      static int editDistance(String a, String b)
      Computes the Levenshtein edit distance between two strings.
      Parameters:
      a - first string
      b - second string
      Returns:
      minimum number of edits (insert, delete, substitute)

    • addRecord

      private void addRecord(AutomationDiagnostics.OperationRecord record)
      Adds an operation record to history, trimming if over capacity.
      Parameters:
      record - the record to add

    • getRecentFailures

      private List<Map<String,String>> getRecentFailures(int count)
      Gets the most recent failures for diagnostics.
      Parameters:
      count - maximum number of failures to return
      Returns:
      list of recent failure descriptions

    • generateRecommendations

      private List<String> generateRecommendations()
      Generates recommendations based on failure patterns.
      Returns:
      list of recommendation strings

    • getPhysicalBound

      private AutomationDiagnostics.PhysicalBound getPhysicalBound(String propertyName, String unit)
      Returns physical bounds for common properties.
      Parameters:
      propertyName - the property name
      unit - the unit of measurement
      Returns:
      physical bounds, or null if unknown