Package com.tnsai.metadata

Class ActionMetadata

java.lang.Object
com.tnsai.metadata.ActionMetadata
public class ActionMetadata extends Object
Immutable metadata about a Role method that becomes an Action. Extracted from method signature and @ActionSpec annotation via reflection.

Type-specific configuration is read from nested annotations:

For LLM actions, optional per-action overrides (llmSystemPrompt, llmTemperature) are read directly from @ActionSpec. Tool exposure is configured at the agent level via AgentBuilder.builtInTools(...) / .toolPojos(...); the dispatcher routes any @Tool method calls the LLM emits without requiring per-action declaration.

Following ADR-006: Immutable Models

  • Method name = Action name
  • Method signature = Action parameters
  • @ActionSpec annotation is MANDATORY for action discovery
  • Annotation provides action type and configuration

  • Constructor Details

  • Method Details

    • hasVariantOverride

      public boolean hasVariantOverride()
      Checks if this action has a variant override.
      Returns:
      true if action specifies a variant override

    • getVariantOverride

      public AgentVariant getVariantOverride()
      Gets the variant override for this action, if specified.
      Returns:
      the variant override, or null if not specified

    • getVariantFallback

      public AgentVariant getVariantFallback()
      Gets the fallback variant for this action.
      Returns:
      the fallback variant, or null if not specified

    • getVariantReason

      public String getVariantReason()
      Gets the reason for the variant override.
      Returns:
      the reason string

    • isVariantRecordStats

      public boolean isVariantRecordStats()
      Whether to record variant usage statistics.
      Returns:
      true if stats should be recorded

    • isIdempotent

      public boolean isIdempotent()
      Checks if this action is marked as idempotent. Idempotent actions can be safely retried without side effects.
      Returns:
      true if action is idempotent

    • hasIdempotencyKey

      public boolean hasIdempotencyKey()
      Checks if this action has an idempotency key defined.
      Returns:
      true if idempotency key is specified

    • hasExamples

      public boolean hasExamples()
      Checks if this action has usage examples defined.
      Returns:
      true if examples are present

    • getExamples

      public List<ToolExampleSpec> getExamples()
      Gets all usage examples (positive and negative) in declaration order.
      Returns:
      list of all examples; empty if none declared

    • getPositiveExamples

      public List<ToolExampleSpec> getPositiveExamples()
      Gets the positive (good) examples.
      Returns:
      list of positive examples

    • getNegativeExamples

      public List<ToolExampleSpec> getNegativeExamples()
      Gets the negative (bad) examples.
      Returns:
      list of negative examples

    • hasLLMParameters

      public boolean hasLLMParameters()
      Checks if this action has custom LLM parameters defined.
      Returns:
      true if @LLMParam annotations are present

    • getParametersForLLM

      public List<?> getParametersForLLM()
      Gets the parameters to expose to LLM. Returns custom LLM parameters if defined, otherwise returns method parameters.
      Returns:
      parameters for LLM tool schema

    • getSimpleReturnTypeName

      public String getSimpleReturnTypeName()
      Gets the simple return type name (without package).
      Returns:
      simple return type name

    • hasDescription

      public boolean hasDescription()
      Checks if this action has a description.
      Returns:
      true if description is not empty

    • hasParameters

      public boolean hasParameters()
      Checks if this action has parameters.
      Returns:
      true if parameters list is not empty

    • returnsVoid

      public boolean returnsVoid()
      Checks if this action returns void.
      Returns:
      true if return type is void

    • isWebService

      public boolean isWebService()
      Checks if this is a WebService action.
      Returns:
      true if type is WEB_SERVICE

    • isLLMAction

      public boolean isLLMAction()
      Checks if this is an LLM-based action.
      Returns:
      true if type is LLM

    • isDirectCode

      public boolean isDirectCode()
      Checks if this is a direct code action.
      Returns:
      true if type is LOCAL

    • isMcpTool

      public boolean isMcpTool()
      Checks if this is an MCP tool action.
      Returns:
      true if type is MCP_TOOL

    • getEndpoint

      public String getEndpoint()
      Gets the endpoint URL for WEB_SERVICE or MCP_TOOL actions.
      Returns:
      endpoint URL or empty string if not configured

    • getMcpApiKeyEnv

      public String getMcpApiKeyEnv()
      Gets the MCP API key environment variable name.
      Returns:
      environment variable name or empty string if not configured

    • isExposedToLLM

      public boolean isExposedToLLM()
      Checks if this action should be exposed to LLM as a callable tool.

      Exposed action types:

      • LOCAL — Direct method calls
      • WEB_SERVICE — REST API calls
      • LLM — LLM-driven actions (e.g., evaluation, strategy selection)

      NOT exposed:

      • MCP_TOOL — Exposed via separate MCP discovery mechanism
      • Actions with excludeFromLLM=true

      This method is used by ToolSchemaGenerator to determine which actions should be included in the LLM function calling schema.

      Returns:
      true if this action can be called by the LLM as a tool

    • isExcludedFromLLM

      public boolean isExcludedFromLLM()
      Checks if this action is excluded from LLM tool list.

      Excluded actions can still be called programmatically but won't appear in the agent's system prompt or tool definitions.

      Returns:
      true if excluded from LLM

    • getEffects

      public Effect[] getEffects()
      Gets the effects defined for this action.

      Effects describe how the action modifies state fields, used by the Planner for simulation and by EffectApplier for automatic application.

      Returns:
      array of effects, never null

    • isAutoApplyEffects

      public boolean isAutoApplyEffects()
      Checks if effects should be automatically applied after action execution.

      When true, the framework reads @Effect annotations and applies them to @State fields after the action method returns.

      Returns:
      true if effects should be auto-applied

    • toPromptString

      public String toPromptString()
      Creates a formatted string for prompt generation. Format: "name(param1: Type1, param2: Type2): ReturnType - description"
      Returns:
      formatted action string

    • getParameterCount

      public int getParameterCount()
      Gets the parameter count.
      Returns:
      number of parameters

    • getParameter

      public ParamSpec getParameter(int position)
      Gets a parameter by position.
      Parameters:
      position - parameter position (0-based)
      Returns:
      parameter metadata
      Throws:
      IndexOutOfBoundsException - if position is invalid

    • getMcpServerUrl

      public String getMcpServerUrl()
      Gets the MCP server URL for MCP_TOOL actions.
      Returns:
      MCP server URL or empty string

    • getMcpToolName

      public String getMcpToolName()
      Gets the specific MCP tool name.
      Returns:
      tool name or empty string (uses method name if empty)

    • getLlmSystemPrompt

      public String getLlmSystemPrompt()
      Gets the per-action LLM system-prompt override.
      Returns:
      system prompt or empty string when no override is set

    • hasLlmSystemPrompt

      public boolean hasLlmSystemPrompt()
      Checks whether a per-action LLM system-prompt override is present.
      Returns:
      true when getLlmSystemPrompt() is non-empty

    • getLlmTemperature

      public float getLlmTemperature()
      Gets the per-action LLM temperature override.
      Returns:
      temperature when overridden, or -1.0f when not

    • hasLlmTemperatureOverride

      public boolean hasLlmTemperatureOverride()
      Checks whether a per-action LLM temperature override is present.
      Returns:
      true when getLlmTemperature() is >= 0

    • getContentType

      public String getContentType()
      Gets the content type for web service requests.
      Returns:
      content type

    • getAccept

      public String getAccept()
      Gets the accept header value.
      Returns:
      accept value

    • isFollowRedirects

      public boolean isFollowRedirects()
      Checks if redirects should be followed.
      Returns:
      true if follow redirects

    • getRetryCount

      public int getRetryCount()
      Gets the retry count for web service.
      Returns:
      retry count

    • getRetryBackoffMs

      public int getRetryBackoffMs()
      Gets the retry backoff time in ms.
      Returns:
      backoff in ms

    • getApiKeyHeader

      public String getApiKeyHeader()
      Gets the API key header name for API_KEY auth.
      Returns:
      header name

    • isMcpCacheToolDefinitions

      public boolean isMcpCacheToolDefinitions()
      Checks if MCP tool definitions should be cached.
      Returns:
      true if caching enabled

    • getMcpCacheTtlSeconds

      public int getMcpCacheTtlSeconds()
      Gets the MCP cache TTL in seconds.
      Returns:
      cache TTL

    • isMcpValidateParameters

      public boolean isMcpValidateParameters()
      Checks if MCP parameters should be validated.
      Returns:
      true if validation enabled

    • getMcpStdioCommand

      public String getMcpStdioCommand()
      Gets the MCP stdio command.
      Returns:
      stdio command or empty

    • isMcpStdio

      public boolean isMcpStdio()
      Checks if MCP uses stdio transport.
      Returns:
      true if stdio command set

    • getMcpStdioArgs

      public String[] getMcpStdioArgs()
      Gets the MCP stdio arguments.
      Returns:
      stdio args array

    • getMcpStdioEnv

      public String[] getMcpStdioEnv()
      Gets the MCP stdio environment variables.
      Returns:
      env vars array

    • getMcpTimeout

      public int getMcpTimeout()
      Gets the MCP request timeout.
      Returns:
      timeout in ms

    • getMcpHeaders

      public Header[] getMcpHeaders()
      Gets the MCP custom headers.
      Returns:
      headers array

    • getMcpRetryCount

      public int getMcpRetryCount()
      Gets the MCP retry count.
      Returns:
      retry count

    • getMcpRetryBackoffMs

      public int getMcpRetryBackoffMs()
      Gets the MCP retry backoff.
      Returns:
      backoff in ms

    • webServiceConfig

      public WebServiceConfig webServiceConfig()
      Returns a grouped view of all web service configuration.

      Provides a cohesive object with HTTP endpoint, method, authentication, headers, and retry settings. Useful for executors that need multiple web service fields together.

      Returns:
      web service configuration record

    • mcpToolConfig

      public MCPToolConfig mcpToolConfig()
      Returns a grouped view of all MCP tool configuration.

      Provides a cohesive object with MCP server URL, authentication, cache settings, retry, and stdio transport configuration.

      Returns:
      MCP tool configuration record

    • contractConfig

      public ContractConfig contractConfig()
      Returns a grouped view of all contract and planning configuration.

      Provides a cohesive object with preconditions, postconditions, goal fulfillment, and state effects.

      Returns:
      contract configuration record

    • hasPrecondition

      public boolean hasPrecondition()
      Checks if this action has a precondition defined.
      Returns:
      true if precondition is not empty

    • getPrecondition

      public String getPrecondition()
      Gets the precondition expression.
      Returns:
      precondition string, never null

    • hasPostcondition

      public boolean hasPostcondition()
      Checks if this action has a postcondition defined.
      Returns:
      true if postcondition is not empty

    • getPostcondition

      public String getPostcondition()
      Gets the postcondition expression.
      Returns:
      postcondition string, never null

    • getFulfills

      public String[] getFulfills()
      Gets the goals that this action fulfills.
      Returns:
      array of goal names, never null

    • hasFulfills

      public boolean hasFulfills()
      Checks if this action fulfills any goals.
      Returns:
      true if fulfills array is not empty

    • getMustNever

      public String[] getMustNever()
      Gets the mustNever safety constraints for this action.
      Returns:
      array of mustNever statements, never null
      Since:
      0.9.0

    • hasMustNever

      public boolean hasMustNever()
      Checks if this action has any mustNever constraints.
      Returns:
      true if mustNever array is not empty
      Since:
      0.9.0

    • getMustAlways

      public String[] getMustAlways()
      Gets the mustAlways liveness guarantees for this action.
      Returns:
      array of mustAlways statements, never null
      Since:
      0.9.0

    • hasMustAlways

      public boolean hasMustAlways()
      Checks if this action has any mustAlways constraints.
      Returns:
      true if mustAlways array is not empty
      Since:
      0.9.0