The core module provides JSON parameter schemas for LLM tools, agent identity and communication style modeling, decentralized identifiers (DIDs), and enums that control agent behavior.

ToolSchema

com.tnsai.schema.ToolSchema models the JSON Schema object used for a tool's parameters. A tool's name and description live in its action metadata, and the generator combines that metadata with the parameters schema.

Creating a Parameter Schema

ToolSchema parameters = ToolSchema.builder()
    .property("city", "string", "City name")
    .property(
        "unit",
        "string",
        "Temperature unit",
        List.of("celsius", "fahrenheit")
    )
    .required(List.of("city"))
    .build();

ToolSchema defaults type to "object". Each property carries a JSON Schema type, description, and optional enum values. Lombok-generated getters expose getType(), getProperties(), and getRequired().

ToolSchemaGenerator

com.tnsai.schema.ToolSchemaGenerator generates provider-neutral function schema maps from discovered role actions.

Generating Schemas

ToolSchemaGenerator generator = new ToolSchemaGenerator();

List<Map<String, Object>> schemas = generator.generateToolSchemas(roles);
Map<String, Object> schema = generator.generateToolSchema(action);

// Human-readable description for system prompts
String desc = generator.generateToolsDescription(roles);

Configuration

// Enable/disable example inclusion in schemas
generator.withExamples(true);

Java-to-JSON-Schema Type Mapping

Java Type	JSON Schema Type
`String`, `char`, `Character`	`"string"`
`int`, `Integer`, `long`, `Long`, `short`, `byte`	`"integer"`
`double`, `Double`, `float`, `Float`	`"number"`
`boolean`, `Boolean`	`"boolean"`
Arrays, `List`	`"array"`
Enums	`"string"` (with `enum` constraint)
Other	`"object"`

AgentIdentity

com.tnsai.models.agent.AgentIdentity represents a personality trait or characteristic that shapes agent behavior. Identities are included in the system prompt to influence communication style.

public final class AgentIdentity {
    private final String name;        // required, non-blank
    private final String description; // required, non-blank
}

Usage

AgentIdentity analytical = new AgentIdentity(
    "analytical",
    "Takes a data-driven approach to problem solving"
);

AgentIdentity empathetic = new AgentIdentity(
    "empathetic",
    "Shows understanding and consideration for user emotions"
);

// In an Agent subclass
@Override
protected List<AgentIdentity> getIdentities() {
    return List.of(
        new AgentIdentity("expert", "Deep knowledge in software engineering"),
        new AgentIdentity("patient", "Takes time to explain concepts clearly"),
        new AgentIdentity("thorough", "Considers all aspects before responding")
    );
}

Common Identity Types

Category	Examples
Cognitive	analytical, creative, logical, intuitive
Social	friendly, professional, empathetic, direct
Behavioral	proactive, thorough, efficient, cautious
Domain	expert, specialist, generalist

The class is immutable and thread-safe. It supports Jackson JSON serialization via @JsonCreator/@JsonProperty.

Communication (Style)

com.tnsai.models.agent.Communication is a record that defines how an agent expresses itself.

public record Communication(
    Tone tone,
    Formality formality,
    Verbosity verbosity
)

Usage

Communication style = new Communication(
    Tone.FRIENDLY,
    Formality.CASUAL,
    Verbosity.CONCISE
);

// Default style
Communication defaultStyle = Communication.defaultStyle();
// Tone.PROFESSIONAL, Formality.NEUTRAL, Verbosity.MODERATE

// Get description
String desc = style.getDescription();
// "Tone: Warm and approachable, Formality: ..., Verbosity: ..."

// Generate prompt section for LLM
String promptSection = style.generatePromptSection();

Null values default to: Tone.PROFESSIONAL, Formality.NEUTRAL, Verbosity.MODERATE.

DID (Decentralized Identifier)

com.tnsai.identity.DID implements W3C DID Core for agent identification.

Format: did:<method>:<method-specific-id>

// Parse from string
DID did = DID.parse("did:wba:example.com:agent-123");

// Create from components
DID did = new DID("wba", "example.com:agent-123");

// Factory methods
DID wba = DID.createWba("example.com", "agent-123");
// did:wba:example.com:agent-123

DID web = DID.createWeb("example.com");
// did:web:example.com

Methods

Method	Return	Description
`getMethod()`	`String`	DID method (e.g., `"wba"`, `"web"`, `"key"`)
`getMethodSpecificId()`	`String`	Method-specific identifier
`getDidString()`	`String`	Full DID string
`asString()`	`String`	Alias for `getDidString()`
`toURI()`	`URI`	DID as a `java.net.URI`
`isWba()`	`boolean`	Check if `did:wba`
`isWeb()`	`boolean`	Check if `did:web`

Validation: method must be lowercase alphanumeric ([a-z0-9]+). Invalid format throws IllegalArgumentException.

Core Enums

ActionType

com.tnsai.enums.ActionType sets how an action runs: LOCAL, WEB_SERVICE, LLM (a single model call, with no tools) or MCP_TOOL. See Actions.

AgentVariant

com.tnsai.enums.AgentVariant names a quality, speed and cost tier: HIGH, MEDIUM, MINI or AUTO. See Variants for the tiers and what reads them.

Tone

com.tnsai.enums.agent.Tone: communication tone.

Value	Description
`ANALYTICAL`	Analytical and logical
`EMPATHETIC`	Understanding and compassionate
`ASSERTIVE`	Direct and confident
`FRIENDLY`	Warm and approachable
`PROFESSIONAL`	Formal and business-like
`CREATIVE`	Imaginative and innovative

Formality

com.tnsai.enums.agent.Formality: language formality level.

Value	Description
`FORMAL`	Formal language and structure
`NEUTRAL`	Balanced formality
`CASUAL`	Relaxed and informal

Verbosity

com.tnsai.enums.agent.Verbosity: response length preference.

Value	Description
`CONCISE`	Brief and to the point
`MODERATE`	Balanced detail level
`DETAILED`	Comprehensive and thorough

AuthType

com.tnsai.enums.AuthType: authentication types for web service actions: NO_AUTH, BEARER, BASIC.

HttpMethod

com.tnsai.enums.HttpMethod: HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

Action System: how ActionType routes to executors
Tools: POJO tool registration and generated parameter schemas
Variants: the variant tiers and what reads them
Roles: role-based action discovery with @ActionSpec

Schema, identity and enums