Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xemantic/xemantic-ai-tool-schema
A Kotlin multiplatform JSON Schema library
https://github.com/xemantic/xemantic-ai-tool-schema
Last synced: about 1 month ago
JSON representation
A Kotlin multiplatform JSON Schema library
- Host: GitHub
- URL: https://github.com/xemantic/xemantic-ai-tool-schema
- Owner: xemantic
- License: apache-2.0
- Created: 2024-09-28T12:32:46.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-12-01T19:00:28.000Z (about 1 month ago)
- Last Synced: 2024-12-01T19:19:07.069Z (about 1 month ago)
- Language: Kotlin
- Size: 132 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome_ai_agents - Xemantic-Ai-Tool-Schema - Kotlin multiplatform AI/LLM tool use (function calling) JSON Schema generator (Building / Tools)
- awesome_ai_agents - Xemantic-Ai-Tool-Schema - Kotlin multiplatform AI/LLM tool use (function calling) JSON Schema generator (Building / Tools)
README
# xemantic-ai-tool-schema
A Kotlin multiplatform JSON Schema library. Useful for AI and LLMs'
[tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)
([function calling](https://platform.openai.com/docs/guides/function-calling)),
as it generates JSON Schema for Kotlin `@Serializable` classes.
[
](https://central.sonatype.com/namespace/com.xemantic.ai)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/releases)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/blob/main/LICENSE)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/actions/workflows/build-main.yml)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/actions/workflows/build-main.yml)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/commits/main/)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/commits/main/)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/graphs/contributors)
[
](https://github.com/xemantic/xemantic-ai-tool-schema/commits/main/)
[
]()
[
](https://github.com/xemantic/xemantic-ai-tool-schema/commit/39c1fa4c138d4c671868c973e2ad37b262ae03c2)
[
](https://kotlinlang.org/docs/releases.html)
[
](https://discord.gg/vQktqqN2Vn)
[
](https://discord.gg/vQktqqN2Vn)
[
](https://x.com/KazikPogoda)
## Why?
This library was created to fulfill the need of agentic AI projects created by
[xemantic](https://xemantic.com/). In particular:
* [anthropic-sdk-kotlin](https://github.com/xemantic/anthropic-sdk-kotlin) - an unofficial Kotlin multiplatform variant
of [Anthropic SDK](https://docs.anthropic.com/en/api/client-sdks).
* [claudine](https://github.com/xemantic/claudine) - AI Agent build on top of this SDK.
These projects are heavily dependent on
[tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)
([function calling](https://platform.openai.com/docs/guides/function-calling)) functionality
provided by many Large Language Models. Thanks to `xemantic-ai-tool-schema`, a Kotlin class,
with possible additional constraints, can be automatically instantiated from
the JSON tool use input provided by the LLM. This way any manual steps of defining JSON schema
for the model are avoided, which reduce a chance for errors in the process, and allows to
rapidly develop even complex data structures passed to an AI agent.
In short the `xemantic-ai-tool-schema` library can generate a
[JSON Schema](https://json-schema.org/) from any Kotlin class marked as `@Serializable`,
according to [kotlinx.serialization](https://kotlinlang.org/docs/serialization.html).
> [!TIP]
> You might be familiar with similar functionality of the
> [Pydantic](https://docs.pydantic.dev/latest/concepts/json_schema/#generating-json-schema)
> Python library, however, the standard Kotlin serialization is already fulfilling model
> metadata provisioning, so this analogy might be misleading.
## Usage
In `build.gradle.kts` add:
```kotlin
plugins {
kotlin("multiplatform") version "2.1.0" // (or jvm for jvm-only project)
kotlin("plugin.serialization") version "2.1.0"
}
// ...
dependencies {
implementation("com.xemantic.ai:xemantic-ai-tool-schema:0.1.1")
}
```
Then in your code you can define entities like this:
```kotlin
@Serializable
@SerialName("address")
@Title("The full address")
@Description("An address of a person or an organization")
data class Address(
val street: String,
val city: String,
@Description("A postal code not limited to particular country")
@MinLength(3)
@MaxLength(10)
val postalCode: String,
@Pattern("[a-z]{2}")
val countryCode: String,
@Format(StringFormat.EMAIL)
val email: String? = null
)
```
And when `jsonSchemaOf()` function is invoked:
```kotlin
val schema = jsonSchemaOf
()
```
It will produce a [JsonSchema](src/commonMain/kotlin/JsonSchema.kt) instance, which
serializes to:
```json
{
"type": "object",
"title": "The full address",
"description": "An address of a person or an organization",
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"postalCode": {
"type": "string",
"description": "A postal code not limited to particular country",
"minLength": 3,
"maxLength": 10
},
"countryCode": {
"type": "string",
"pattern": "[a-z]{2}"
},
"email": {
"type": "string",
"format": "email"
}
},
"required": [
"street",
"city",
"postalCode",
"countryCode"
]
}
```
And this is the input accepted by Large Language Model APIs like
[OpenAI API](https://platform.openai.com/docs/api-reference/introduction)
and [Anthropic API](https://docs.anthropic.com/en/api/getting-started). When requesting a tool use, these LLMs
will send a JSON payload like adhering to this schema, therefore
immediately deserializable as the original `@Serializable` Kotlin class.
More details and use cases in the [JsonSchemaGeneratorTest](src/commonTest/kotlin/generator/JsonSchemaGeneratorTest.kt).
> [!NOTE]
> When calling `toString()` function on any instance of `JsonSchema`, it will also produce a
> pretty printed `String` representation of a valid JSON schema,
> which in turn describes the Kotlin class as a serialized JSON.
> This functionality is useful for testing and debugging.
### Serializing Java `BigDecimal`s
For JVM-only projects, it is possible to specify `java.math.BigDecimal` serialization.
It will serialize decimal numbers to strings, and add `description` and `pattern`
properties to generated JSON Schema of a `BigDecimal` property.
See [JavaBigDecimalToSchemaTest](src/jvmTest/kotlin/serialization/JavaBigDecimalToSchemaTest.kt)
for details.
### Serializing BigDecimal/monetary values in multiplatform way
There is an interface called [Money](src/commonTest/kotlin/test/Money.kt)
defined in the tests of this project. It explains how to define and serialize monetary
amounts independently of the underlying decimal number and arithmetics provider.
## Development
Clone this repo and then in the project dir:
```shell
./gradlew build
```
## Non-recommended usage
> [!WARNING]
> Even though this library provides basic serializable representation of a JSON Schema, it is not
> meant to fully model general purpose JSON Schema. In particular, it should not be used for deserializing
> existing schemas from JSON.