Package com.tnsai.roles.metadata

Class RoleSpecExtractor

java.lang.Object

com.tnsai.roles.metadata.RoleSpecExtractor

public final class RoleSpecExtractor
extends Object

Extracts role metadata from annotations.

Provides utilities to extract RoleIdentity, action metadata (including action-bound mustNever / mustAlways safety constraints), state, intentions, and LLM configuration from annotation-based Role definitions.

Usage Example

 if (RoleSpecExtractor.hasRoleIdentityAnnotation(MyRole.class)) {
     RoleIdentity identity = RoleSpecExtractor.extractIdentity(MyRole.class).orElseThrow();
 }
 List<ResponsibilityInfo> actionResp =
     RoleSpecExtractor.extractResponsibilitiesFromActions(MyRole.class);
 

Author:

TnsAI Team

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	RoleSpecExtractor.CachedRoleMetadata	Cached bundle of all extracted metadata for a role class.
static final record	RoleSpecExtractor.LLMExportSpec	Immutable LLM configuration extracted from a role's @RoleSpec.llm() (@LLMSpec) for the role-export subsystem.
static final record	RoleSpecExtractor.ResponsibilityInfo	Immutable responsibility information extracted from @ActionSpec.
static final record	RoleSpecExtractor.StateInfo	Immutable state information extracted from @State annotation.
static final record	RoleSpecExtractor.StateValue	State with runtime value.

Method Summary

Modifier and Type	Method	Description
static void	clearCache()
static String	deriveRoleName(Class<?> clazz)
static RoleSpecExtractor.CachedRoleMetadata	extractAll(Class<?> clazz)
static Optional<RoleIdentity>	extractIdentity(Class<?> clazz)
static List<String>	extractIntentionsFromActions(Class<?> clazz)
static Optional<RoleSpecExtractor.LLMExportSpec>	extractLLMSpec(Class<?> clazz)
static List<RoleSpecExtractor.ResponsibilityInfo>	extractResponsibilitiesFromActions(Class<?> clazz)	Extracts responsibilities from @ActionSpec annotated methods.
static List<RoleSpecExtractor.StateInfo>	extractStateFromFields(Class<?> clazz)
static List<RoleSpecExtractor.StateValue>	extractStateValues(Object role)
static String	getDescription(Class<?> clazz)
static String	getVersion(Class<?> clazz)
static boolean	hasLLMConfig(Class<?> clazz)
static boolean	hasRoleIdentityAnnotation(Class<?> clazz)
static boolean	hasStateFields(Class<?> clazz)
static boolean	usesAnnotations(Class<?> clazz)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

clearCache

public static void clearCache()

hasRoleIdentityAnnotation

public static boolean hasRoleIdentityAnnotation(Class<?> clazz)

hasLLMConfig

public static boolean hasLLMConfig(Class<?> clazz)

usesAnnotations

public static boolean usesAnnotations(Class<?> clazz)

extractIdentity

public static Optional<RoleIdentity> extractIdentity(Class<?> clazz)

extractLLMSpec

public static Optional<RoleSpecExtractor.LLMExportSpec> extractLLMSpec(Class<?> clazz)

deriveRoleName

public static String deriveRoleName(Class<?> clazz)

getDescription

public static String getDescription(Class<?> clazz)

getVersion

public static String getVersion(Class<?> clazz)

extractStateFromFields

public static List<RoleSpecExtractor.StateInfo> extractStateFromFields(Class<?> clazz)

extractStateValues

public static List<RoleSpecExtractor.StateValue> extractStateValues(Object role)

extractIntentionsFromActions

public static List<String> extractIntentionsFromActions(Class<?> clazz)

extractResponsibilitiesFromActions

public static List<RoleSpecExtractor.ResponsibilityInfo> extractResponsibilitiesFromActions(Class<?> clazz)

Extracts responsibilities from @ActionSpec annotated methods.

Each entry carries the readable name, description, original method name, declared invariants, and the safety constraints (mustNever / mustAlways) the action declares.

Parameters:

clazz - the class to scan

Returns:

list of responsibility information per action

hasStateFields

public static boolean hasStateFields(Class<?> clazz)

extractAll

public static RoleSpecExtractor.CachedRoleMetadata extractAll(Class<?> clazz)