Package com.tnsai.annotations

Annotation Interface Utility

@Documented @Retention(RUNTIME) @Target({}) public @interface Utility
Utility-based planning configuration for actions.

This is a nested annotation used within ActionSpec to configure utility-based action selection. Utility AI selects actions based on cost/value trade-offs rather than goal-directed planning.

Usage


 @ActionSpec(
     type = ActionType.LLM,
     description = "Search in cache",
     utility = @Utility(cost = 5, value = 30)
 )
 public SearchResults searchCache(String query) { ... }

 @ActionSpec(
     type = ActionType.LLM,
     description = "Search the web",
     utility = @Utility(cost = 10, value = 50, tags = {"slow", "expensive"})
 )
 public SearchResults searchWeb(String query) { ... }

When to Use

  • Exploratory behaviors (chatbots)
  • Dynamic environments where plans become stale quickly
  • Cost optimization (prefer cheaper actions)
  • A/B testing with different utility functions

Selection Algorithm

UtilityAIPlanner selects the action with highest utility score: 

 utility = value - cost
 // Or with considerations:
 utility = sum(consideration.score() * consideration.weight())
Author:
TnsAI Team
See Also:
  • invalid reference 
    Action#utility()
  • invalid reference 
    com.tnsai.planning.UtilityAIPlanner

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    considerations
    Custom consideration class names.
    int
    cost
    Cost of executing this action.
    String[]
    tags
    Tags for filtering/grouping actions.
    int
    value
    Expected value/benefit of this action.
    float
    weight
    Weight multiplier for this action's utility score.

  • Element Details

    • cost

      int cost
      Cost of executing this action.

      Higher cost = less preferred (all else equal).

      Can represent: API cost, latency, resource usage, etc.

      Returns:
      action cost (default: 1)
      Default:
      1

    • value

      int value
      Expected value/benefit of this action.

      Higher value = more preferred (all else equal).

      Can represent: accuracy, completeness, reliability, etc.

      Returns:
      expected value (default: 1)
      Default:
      1

    • weight

      float weight
      Weight multiplier for this action's utility score.

      Use to boost or reduce priority of specific actions.

      Returns:
      weight multiplier (default: 1.0)
      Default:
      1.0f

    • tags

      String[] tags
      Tags for filtering/grouping actions.

      Example: "expensive", "fast", "reliable"

      Returns:
      array of tags
      Default:
      {}

    • considerations

      String[] considerations
      Custom consideration class names.

      Advanced: Use custom Consideration implementations for dynamic scoring.

      Returns:
      array of consideration class names
      Default:
      {}