Package com.tnsai.roles

Class RoleBuilder

java.lang.Object
com.tnsai.roles.RoleBuilder
public final class RoleBuilder extends Object
Fluent builder for creating Role instances without subclassing.

This builder provides a fluent API for constructing roles with custom identity and LLM configuration, ideal for:

  • Creating roles programmatically at runtime
  • Dynamic role configuration from external sources (JSON, YAML)
  • Testing with mock configurations

Safety constraints (mustNever / mustAlways) are now declared on @ActionSpec methods of the role class. Builder-built roles do not carry constraints — for safety-bound behavior, define a Role subclass with @ActionSpec-annotated methods.

Example usage: 


 Role role = RoleBuilder.create()
     .name("Analyst")
     .goal("Analyze data and provide insights")
     .domain("data_science")
     .llm(new OpenAIClient("gpt-4o"))
     .build();
Author:
TnsAI Team
See Also:

  • Method Details

    • create

      public static RoleBuilder create()

    • name

      public RoleBuilder name(String name)

    • goal

      public RoleBuilder goal(String goal)

    • domain

      public RoleBuilder domain(String domain)

    • llm

      public RoleBuilder llm(LLMClient llm)
      Sets the LLM client for this role.
      Parameters:
      llm - the LLM client, or null to use agent's LLM
      Returns:
      this builder

    • resilience

      public RoleBuilder resilience(ResilienceConfig resilience)
      Sets this role's resilience policy (TNS-567) — the programmatic equivalent of a class-level @Resilience. Applies to the role's actions via ActionExecutor when they have no method-level @Resilience. Models the runtime-enforced subset (retry + timeout); see ResilienceConfig. 
      
 RoleBuilder.create().name("payment").goal("Process payments")
     .resilience(ResilienceConfig.builder()
         .retry(RetryPolicy.builder().maxAttempts(3).build())
         .timeoutMs(5000)
         .build());
      Parameters:
      resilience - the resilience config (non-null; use ResilienceConfig.NONE for none)
      Returns:
      this builder
      Since:
      0.12.0 (TNS-567)

    • inputGuardrail

      public RoleBuilder inputGuardrail(InputGuardrailConfig inputGuardrail)
      Sets this role's class-level input guardrail (TNS-561) — the programmatic equivalent of a class-level @InputGuardrail. Applies to every action in the role; InputGuardrailEnforcer enforces it (a method-level @InputGuardrail annotation still overrides it). 
      
 RoleBuilder.create().name("support").goal("...")
     .inputGuardrail(InputGuardrailConfig.builder()
         .maxLength(10_000)
         .blockPatterns(List.of("ignore previous"))
         .build());
      Parameters:
      inputGuardrail - the input-guardrail config; null clears it
      Returns:
      this builder
      Since:
      0.12.0 (TNS-561)

    • outputGuardrail

      public RoleBuilder outputGuardrail(OutputGuardrailConfig outputGuardrail)
      Sets this role's class-level output guardrail (TNS-561) — the programmatic equivalent of a class-level @OutputGuardrail. Applies to every action in the role; OutputGuardrailEnforcer enforces it (a method-level @OutputGuardrail annotation still overrides it). 
      
 RoleBuilder.create().name("support").goal("...")
     .outputGuardrail(OutputGuardrailConfig.builder()
         .maxChars(2000)
         .onFailure(OutputGuardrail.FailureAction.TRUNCATE)
         .build());
      Parameters:
      outputGuardrail - the output-guardrail config; null clears it
      Returns:
      this builder
      Since:
      0.12.0 (TNS-561)

    • addAction

      public RoleBuilder addAction(ActionConfig action)
      Registers a programmatic action on this role (TNS-551) — the builder counterpart of an @ActionSpec-annotated method. The resulting Role dispatches it exactly like an annotation-discovered action.
      Parameters:
      action - the action config (see ActionConfig.local(java.lang.String, java.lang.String, com.tnsai.metadata.ActionHandler))
      Returns:
      this builder
      Since:
      0.11.0

    • actions

      public RoleBuilder actions(List<ActionConfig> actions)
      Registers multiple programmatic actions (TNS-551).
      Parameters:
      actions - the action configs (appended to any already added)
      Returns:
      this builder
      Since:
      0.11.0

    • build

      public Role build()
      Builds and returns the configured Role instance.
      Returns:
      the configured Role
      Throws:
      IllegalStateException - if required configuration is missing