# Schema, Identity, and Enums

TnsAI.Core 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; 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` -- execution method for actions.

| Value | Description |
|-------|-------------|
| `LOCAL` | Direct Java method invocation |
| `WEB_SERVICE` | HTTP API calls |
| `LLM` | LLM with tool selection |
| `MCP_TOOL` | Model Context Protocol |

### AgentVariant

`com.tnsai.enums.AgentVariant` -- quality/speed/cost tiers.

| Variant | Quality | Speed | Cost | Description |
|---------|---------|-------|------|-------------|
| `HIGH` | MAX | SLOW | HIGH | Complex/critical tasks |
| `MEDIUM` | BALANCED | NORMAL | MEDIUM | Regular development |
| `MINI` | BASIC | FAST | LOW | Quick fixes |
| `AUTO` | ADAPTIVE | ADAPTIVE | OPTIMAL | Task-based selection |

```java
agent.setVariant(AgentVariant.HIGH);

// Auto-select based on task keywords
AgentVariant suggested = AgentVariant.forTask("Complex refactoring");  // HIGH
AgentVariant suggested = AgentVariant.forTask("Fix typo");             // MINI
```

Key methods: `isQualityFocused()`, `isSpeedFocused()`, `isCostOptimized()`, `forTask(String)`.

Sub-enums: `Quality` (MAX/BALANCED/BASIC/ADAPTIVE), `Speed` (SLOW/NORMAL/FAST/ADAPTIVE), `Cost` (HIGH/MEDIUM/LOW/OPTIMAL).

### 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.

### Verbosity

`com.tnsai.enums.agent.Verbosity` -- response length preference.

### 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](../fundamentals/action-system.md) -- how ActionType routes to executors
- [Tools](../../capabilities/tools/registration.md) -- POJO tool registration and generated parameter schemas
- [Variants](../behavior/variants.md) -- detailed variant configuration
- [Advanced Agent Features](../advanced.md) -- how identities and variants are used
- [Roles](../fundamentals/roles.md) -- role-based action discovery with @ActionSpec