Package com.tnsai.models.role

package com.tnsai.models.role

Gaia methodology model classes for role-based agent design.

This package implements the Gaia methodology for multi-agent system design, developed by Wooldridge, Jennings, and Kinny. Gaia treats agents as organizational entities that fulfill specific Roles within a system.

Gaia Role Model

 ┌─────────────────────────────────────────────────────────────┐
 │                     Role Schema                              │
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
 │  ┌─────────────────────────────────────────────────────┐    │
 │  │               RoleIdentity                           │    │
 │  │  • name: Unique identifier                          │    │
 │  │  • goal: Primary objective                          │    │
 │  │  • domain: Area of expertise                        │    │
 │  └─────────────────────────────────────────────────────┘    │
 │                                                              │
 │  ┌─────────────────────────────────────────────────────┐    │
 │  │              Responsibilities                        │    │
 │  │                                                      │    │
 │  │  CoreDuty (Liveness)     SafetyProperty (Safety)    │    │
 │  │  ────────────────────    ─────────────────────────   │    │
 │  │  "Must eventually do"    "Must never/always do"     │    │
 │  │  • Collect data          • MUST_NEVER expose PII    │    │
 │  │  • Generate reports      • MUST_ALWAYS validate     │    │
 │  └─────────────────────────────────────────────────────┘    │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 

Model Classes

Class	Purpose	Gaia Concept
RoleIdentity	Name, goal, domain	Role Schema header
invalid reference CoreDuty	Required tasks	Liveness property
invalid reference SafetyProperty	Constraints	Safety property
invalid reference Responsibilities	Duty + Safety collection	Responsibilities schema
invalid reference Responsibility	Common interface	Abstract responsibility

Liveness vs Safety

In formal verification terms:

• Liveness (CoreDuty): Something good eventually happens
  Example: "The agent must eventually respond to queries"
• Safety (SafetyProperty): Something bad never happens
  Example: "The agent must never expose credentials"

Usage Example

 // Define role identity
 RoleIdentity identity = new RoleIdentity(
     "SecureAPIHandler",
     "Process API requests securely",
     "API Security"
 );

 // Define responsibilities
 Responsibilities responsibilities = Responsibilities.builder()
     .addDuty(new CoreDuty("Request Validation", "Validate all incoming requests"))
     .addDuty(new CoreDuty("Response Generation", "Generate appropriate responses"))
     .addSafety(new SafetyProperty(
         SafetyType.MUST_NEVER,
         "expose internal error details",
         "Prevents information disclosure"))
     .addSafety(new SafetyProperty(
         SafetyType.MUST_ALWAYS,
         "log authentication attempts",
         "Security audit requirement"))
     .build();
 

LLM Integration

Role models are converted to system prompt instructions that establish the agent's identity and behavioral constraints for the LLM.

See Also:

• RoleIdentity
• invalid reference

  CoreDuty

• invalid reference

  SafetyProperty

• invalid reference

  Responsibilities

• Role

Related Packages

Package	Description
com.tnsai.models	Data models for the TnsAI framework.
com.tnsai.models.agent	BDI (Belief-Desire-Intention) model classes for agent reasoning.
com.tnsai.models.chat	Multimodal content parts for LLM communication.

Classes

Class	Description
RoleIdentity	Represents the identity of a role in the Gaia methodology.