prompt-structure/ai.koog.prompt.structure.json/JsonStructuredData/Companion/createJsonStructure

createJsonStructure

fun <TStruct> createJsonStructure(id: String, serializer: KSerializer<TStruct>, json: Json = defaultJson, schemaGenerator: JsonSchemaGenerator = StandardJsonSchemaGenerator.Default, descriptionOverrides: Map<String, String> = emptyMap(), excludedProperties: Set<String> = emptySet(), examples: List<TStruct> = emptyList(), definitionPrompt: (builder: TextContentBuilderBase<*>, structuredData: JsonStructuredData<TStruct>) -> TextContentBuilderBase<*> = ::defaultDefinitionPrompt): JsonStructuredData<TStruct>(source)

Factory method to create JSON structure with auto-generated JSON schema.

Example usage:

@Serializable
@SerialName("LatLon")
@LLMDescription("Coordinates of the location in latitude and longitude format")
data class LatLon(
    @property:LLMDescription("Latitude of the location")
    val lat: Double,
    @property:LLMDescription("Longitude of the location")
    val lon: Double
)

@Serializable
@SerialName("WeatherDatapoint")
@LLMDescription("Weather datapoint for a given timestamp in the given location")
data class WeatherDatapoint(
    @property:LLMDescription("Forecast timestamp")
    val timestampt: Long,
    @property:LLMDescription("Forecast temperature in Celsius")
    val temperature: Double,
    @property:LLMDescription("Precipitation in mm/h")
    val precipitation: Double,
)

@Serializable
@SerialName("Weather")
data class Weather(
    @property:LLMDescription("Country code of the location")
    val countryCode: String,
    @property:LLMDescription("City name of the location")
    val cityName: String,
    @property:LLMDescription("Coordinates of the location")
    val latLon: LatLon,
    val forecast: List<WeatherDatapoint>,
)

val weatherStructure = JsonStructuredData.createJsonStructure<WeatherForecast>(
    id = "WeatherForecast",
    serializer = WeatherForecast.serializer(),
    // some models don't work well with full json schema, so you may try simple, but it has more limitations (e.g. limited polymorphism)
    schemaGenerator = FullJsonSchemaGenerator,
    descriptionOverrides = mapOf(
        // type descriptions
        "Weather" to "Weather forecast for a given location", // the class doesn't have description annotation, this will add description
        "WeatherDatapoint" to "Weather data at a given time", // the class has description annotation, this will override description

        // property descriptions
        "Weather.forecast" to "List of forecasted weather conditions for a given location", // the property doesn't have description annotation, this will add description
        "Weather.countryCode" to "Country code of the location in the ISO2 format", // the property has description annotation, this will override description
    ),
    // You can also exclude properties from schema generation completely
    excludedProperties = setOf("Weather.cityName"),
)

Parameters

Unique identifier for the structure.

serializer

Serializer used for converting the data to and from JSON.

json

JSON configuration instance used for serialization.

schemaGenerator

JSON schema generator

descriptionOverrides

Optional map of serial class names and property names to descriptions. If a property/type is already described with ai.koog.agents.core.tools.annotations.LLMDescription annotation, value from the map will override this description.

excludedProperties

Optional set of property names to exclude from the schema generation.

examples

List of example data items that conform to the structure, used for demonstrating valid formats.

definitionPrompt

Prompt with definition, explaining the structure to the LLM when the manual mode for structured output is used. Default is JsonStructuredData.defaultDefinitionPrompt

inline fun <TStruct> createJsonStructure(json: Json = defaultJson, schemaGenerator: JsonSchemaGenerator = StandardJsonSchemaGenerator.Default, descriptionOverrides: Map<String, String> = emptyMap(), excludedProperties: Set<String> = emptySet(), examples: List<TStruct> = emptyList(), noinline definitionPrompt: (builder: TextContentBuilderBase<*>, structuredData: JsonStructuredData<TStruct>) -> TextContentBuilderBase<*> = ::defaultDefinitionPrompt): JsonStructuredData<TStruct>(source)