Package com.tnsai.metadata

Record Class ActionConfig

java.lang.Object
java.lang.Record
com.tnsai.metadata.ActionConfig
Record Components:
name - the action name (LLM-facing, unique per role)
description - human-readable description for the LLM tool catalog
type - the action type (typically ActionType.LOCAL)
parameters - parameter metadata (may be empty; the handler reads the map)
handler - the dispatch callback
contract - declarative DBC gates (ContractSpec.NONE if none); TNS-637
inputGuardrail - per-action input guardrail (null if none); TNS-643
outputGuardrail - per-action output guardrail (null if none); TNS-643
public record ActionConfig(String name, String description, ActionType type, List<ParamSpec> parameters, ActionHandler handler, ContractSpec contract, InputGuardrailConfig inputGuardrail, OutputGuardrailConfig outputGuardrail) extends Record
Programmatic counterpart of @ActionSpec (TNS-551) — declares a role action via a builder instead of an annotated method, so RoleBuilder.addAction(ActionConfig) can register actions that an agent dispatches identically to annotation-derived ones.

Scoped to LOCAL (lambda-handler) actions for now — the common case and the one with no annotation equivalent for the builder path. The richer @ActionSpec fields (web-service config, LLM overrides, examples, safety constraints) land incrementally as their builder forms are needed.

Placed in com.tnsai.metadata (not com.tnsai.actions) to keep the package graph acyclic: com.tnsai.actions.ActionExecutor already depends on com.tnsai.roles.Role, so a roles → actions dependency (which RoleBuilder would introduce) would create a cycle.

Since:
0.11.0
Author:
TnsAI Team
See Also:

  • Constructor Details

  • Method Details

    • local

      public static ActionConfig local(String name, String description, ActionHandler handler)
      A LOCAL action with no declared parameters — the handler reads the argument map directly.

    • local

      public static ActionConfig local(String name, String description, List<ParamSpec> parameters, ActionHandler handler)
      A LOCAL action with declared parameters (surfaced to the LLM tool schema, same as annotation actions).

    • withContract

      public ActionConfig withContract(ContractSpec contract)
      Returns a copy of this config with the given ContractSpec attached — the programmatic equivalent of annotating the action method with @Contract (TNS-637). Enforced at dispatch by ContractValidator. 
      
 RoleBuilder.addAction(ActionConfig.local("transfer", "...", handler)
     .withContract(ContractSpec.builder()
         .precondition("amount > 0")
         .postcondition("result.success()")
         .build()));

    • withInputGuardrail

      public ActionConfig withInputGuardrail(InputGuardrailConfig inputGuardrail)
      Returns a copy of this config with the given per-action input guardrail (TNS-643) — the programmatic equivalent of a method-level @InputGuardrail. Enforced at dispatch by InputGuardrailEnforcer, at method-level precedence (it overrides the role's RoleBuilder.inputGuardrail(...) default). 
      
 RoleBuilder.addAction(ActionConfig.local("transfer", "...", handler)
     .withInputGuardrail(InputGuardrailConfig.builder().maxLength(500).build()));
      Parameters:
      inputGuardrail - the per-action input guardrail; null clears it
      Returns:
      a copy with the guardrail attached

    • withOutputGuardrail

      public ActionConfig withOutputGuardrail(OutputGuardrailConfig outputGuardrail)
      Returns a copy of this config with the given per-action output guardrail (TNS-643) — the programmatic equivalent of a method-level @OutputGuardrail. Enforced at dispatch by OutputGuardrailEnforcer, at method-level precedence (it overrides the role's RoleBuilder.outputGuardrail(...) default).
      Parameters:
      outputGuardrail - the per-action output guardrail; null clears it
      Returns:
      a copy with the guardrail attached

    • toActionMetadata

      public ActionMetadata toActionMetadata()
      Converts this config into the runtime ActionMetadata shape that reflection produces for @ActionSpec methods — no reflective Method; dispatch goes through handler().

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • name

      public String name()
      Returns the value of the name record component.
      Returns:
      the value of the name record component

    • description

      public String description()
      Returns the value of the description record component.
      Returns:
      the value of the description record component

    • type

      public ActionType type()
      Returns the value of the type record component.
      Returns:
      the value of the type record component

    • parameters

      public List<ParamSpec> parameters()
      Returns the value of the parameters record component.
      Returns:
      the value of the parameters record component

    • handler

      public ActionHandler handler()
      Returns the value of the handler record component.
      Returns:
      the value of the handler record component

    • contract

      public ContractSpec contract()
      Returns the value of the contract record component.
      Returns:
      the value of the contract record component

    • inputGuardrail

      public InputGuardrailConfig inputGuardrail()
      Returns the value of the inputGuardrail record component.
      Returns:
      the value of the inputGuardrail record component

    • outputGuardrail

      public OutputGuardrailConfig outputGuardrail()
      Returns the value of the outputGuardrail record component.
      Returns:
      the value of the outputGuardrail record component