Package com.tnsai.roles

package com.tnsai.roles

Role definitions and capabilities for agents in the TnsAI framework.

This package implements the Gaia methodology concept of Roles. In Gaia, a Role defines the abstract functionality that an agent provides, independent of any specific agent implementation.

Gaia Role Model

 ┌─────────────────────────────────────────────────────────────┐
 │                         Role                                 │
 ├─────────────────────────────────────────────────────────────┤
 │  RoleIdentity                                                │
 │  ├── name: "DataAnalyst"                                    │
 │  ├── goal: "Extract insights from data"                     │
 │  └── domain: "Business Intelligence"                        │
 ├─────────────────────────────────────────────────────────────┤
 │  Responsibilities                                            │
 │  ├── Core Duties (Liveness)                                 │
 │  │   ├── "Collect data from sources"                        │
 │  │   └── "Generate analysis reports"                        │
 │  └── Safety Properties (Safety)                             │
 │      ├── MUST_NEVER "expose raw data"                       │
 │      └── MUST_ALWAYS "validate inputs"                      │
 ├─────────────────────────────────────────────────────────────┤
 │  Capabilities                                                │
 │  ├── "Data analysis and visualization"                      │
 │  └── "Statistical modeling"                                 │
 └─────────────────────────────────────────────────────────────┘
 

Creating a Role

 public class AnalystRole extends Role {
     @Override
     protected RoleIdentity getIdentity() {
         return new RoleIdentity(
             "DataAnalyst",
             "Analyze datasets and provide actionable insights",
             "Business Intelligence"
         );
     }

     @Override
     protected Responsibilities getResponsibilities() {
         return Responsibilities.builder()
             .addDuty(new CoreDuty("Data Collection", "Gather data from multiple sources"))
             .addDuty(new CoreDuty("Analysis", "Apply statistical methods"))
             .addSafety(new SafetyProperty(SafetyType.MUST_NEVER, "expose PII", "Privacy"))
             .build();
     }

     @Override
     protected List<Capability> getCapabilities() {
         return List.of(
             new Capability("SQL querying", "Expert"),
             new Capability("Statistical analysis", "Advanced")
         );
     }
 }
 

Role Components

Component	Purpose	Gaia Concept
RoleIdentity	Name, goal, domain	Role Schema
CoreDuty	What the role must do	Liveness Property
SafetyProperty	Constraints and invariants	Safety Property
Capability	Skills and abilities	Agent Type capability

Role vs Agent

In Gaia methodology:

• Role: Abstract specification of functionality (this package)
• Agent: Concrete entity that plays one or more Roles (com.tnsai.agents)

See Also:

• Role
• RoleIdentity
• Capability

Related Packages

Package	Description
com.tnsai	TnsAI Java SDK - A multi-agent framework with BDI architecture and Gaia methodology.
com.tnsai.roles.annotations	Role annotations for declarative role definition.
com.tnsai.roles.export	Role export system for converting TnsAI roles to various formats.
com.tnsai.roles.metadata	Role metadata extraction from annotations and class definitions.
com.tnsai.roles.registry	Centralized role registration and lookup service.

Class	Description
ConfigurableRole	A fully configurable Role implementation created via RoleBuilder.
Role	Abstract base class for organizational roles in the Gaia methodology.
RoleBuilder	Fluent builder for creating Role instances without subclassing.
RoleInitializationException	Exception thrown when role initialization fails.