Schema, Identity, and Enums

public record ToolDefinition(
    String name,            // required, non-blank
    String description,     // defaults to ""
    Map<String, Object> parameters,  // JSON Schema object, never null
    String endpoint,        // optional API endpoint, defaults to ""
    String apiKeyEnvVar     // optional env var name for API key
)

// Builder (recommended)
ToolDefinition tool = ToolDefinition.builder()
    .name("search_weather")
    .description("Get weather for a city")
    .addParameter("city", "string", "City name", true)
    .addParameter("unit", "string", "Temperature unit", false)
    .addEnumParameter("format", "Output format", List.of("json", "text"), false)
    .endpoint("https://api.weather.com/v1")
    .apiKeyEnvVar("WEATHER_API_KEY")
    .build();

// Simple (no parameters)
ToolDefinition simple = ToolDefinition.of("get_time", "Returns current UTC time");

// From OpenAI-format map
ToolDefinition parsed = ToolDefinition.fromMap(existingMap);

// To OpenAI function calling format
Map<String, Object> map = tool.toMap();
// {"type": "function", "function": {"name": ..., "description": ..., "parameters": ...}}

// Batch conversions
List<ToolDefinition> defs = ToolDefinition.fromMaps(listOfMaps);
List<Map<String, Object>> maps = ToolDefinition.toMaps(listOfDefs);

ToolSchemaGenerator generator = new ToolSchemaGenerator();

// Typed ToolDefinition records (preferred)
List<ToolDefinition> defs = generator.generateToolDefinitions(roles);

// Single action
ToolDefinition def = generator.generateToolDefinition(action);

// From a standalone Tool
ToolDefinition def = generator.generateToolDefinition(tool);

// Legacy Map format
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);

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

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

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")
    );
}

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

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();

// 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

agent.setVariant(AgentVariant.HIGH);

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