# Schema, identity and enums

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

<!-- java-contract: src/main/java/com/example/tnsai/docs/SchemaIdentityToolSchemaExample.java -->
```java
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

```java
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

```java
// 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.

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

### Usage

```java
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.

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

### Usage

```java
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>`

```java
// 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](actions.md).

### AgentVariant

`com.tnsai.enums.AgentVariant` names a quality, speed and cost tier: `HIGH`, `MEDIUM`, `MINI` or `AUTO`. See [Variants](variants.md) 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`.

## Related Documentation

- [Action System](actions.md): how ActionType routes to executors
- [Tools](../tools/register.md): POJO tool registration and generated parameter schemas
- [Variants](variants.md): the variant tiers and what reads them
- [Roles](roles.md): role-based action discovery with @ActionSpec