{"id":22432617,"url":"https://github.com/xemantic/xemantic-ai-tool-schema","last_synced_at":"2025-10-16T01:31:50.945Z","repository":{"id":264350014,"uuid":"864516195","full_name":"xemantic/xemantic-ai-tool-schema","owner":"xemantic","description":"Kotlin multiplatform AI/LLM tool use (function calling) JSON Schema generator","archived":false,"fork":false,"pushed_at":"2025-01-29T22:12:08.000Z","size":199,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-29T23:20:04.318Z","etag":null,"topics":["agentic","agentic-ai","agents","ai","artificial-intelligence","artificialintelligence","function-calling","json-schema","kotlin","kotlin-library","kotlin-multiplatform","large-language-models","llm","schema","tool","tool-use"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xemantic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"xemantic"}},"created_at":"2024-09-28T12:32:46.000Z","updated_at":"2025-01-29T22:11:42.000Z","dependencies_parsed_at":"2024-12-09T16:25:40.088Z","dependency_job_id":"a8c14ea1-3eee-4094-b774-d4fe964b96bd","html_url":"https://github.com/xemantic/xemantic-ai-tool-schema","commit_stats":null,"previous_names":["xemantic/xemantic-json-schema"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xemantic%2Fxemantic-ai-tool-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xemantic%2Fxemantic-ai-tool-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xemantic%2Fxemantic-ai-tool-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xemantic%2Fxemantic-ai-tool-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xemantic","download_url":"https://codeload.github.com/xemantic/xemantic-ai-tool-schema/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236664547,"owners_count":19185516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","agentic-ai","agents","ai","artificial-intelligence","artificialintelligence","function-calling","json-schema","kotlin","kotlin-library","kotlin-multiplatform","large-language-models","llm","schema","tool","tool-use"],"created_at":"2024-12-05T22:12:21.056Z","updated_at":"2025-10-16T01:31:50.929Z","avatar_url":"https://github.com/xemantic.png","language":"Kotlin","funding_links":["https://github.com/sponsors/xemantic"],"categories":["Building","JSON"],"sub_categories":["Tools","语音合成"],"readme":"# xemantic-ai-tool-schema\n\nAI/LLM [tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) ([function calling](https://platform.openai.com/docs/guides/function-calling)) JSON Schema generator - a Kotlin multiplatform library\nwhich generates JSON Schema for Kotlin `@Serializable` classes.\n\n[\u003cimg alt=\"Maven Central Version\" src=\"https://img.shields.io/maven-central/v/com.xemantic.ai/xemantic-ai-tool-schema\"\u003e](https://central.sonatype.com/artifact/com.xemantic.ai/xemantic-ai-tool-schema)\n[\u003cimg alt=\"GitHub Release Date\" src=\"https://img.shields.io/github/release-date/xemantic/xemantic-ai-tool-schema\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/releases)\n[\u003cimg alt=\"license\" src=\"https://img.shields.io/github/license/xemantic/xemantic-ai-tool-schema?color=blue\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/blob/main/LICENSE)\n\n[\u003cimg alt=\"GitHub Actions Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/xemantic/xemantic-ai-tool-schema/build-main.yml\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/actions/workflows/build-main.yml)\n[\u003cimg alt=\"GitHub branch check runs\" src=\"https://img.shields.io/github/check-runs/xemantic/xemantic-ai-tool-schema/main\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/actions/workflows/build-main.yml)\n[\u003cimg alt=\"GitHub commits since latest release\" src=\"https://img.shields.io/github/commits-since/xemantic/xemantic-ai-tool-schema/latest\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/commits/main/)\n[\u003cimg alt=\"GitHub last commit\" src=\"https://img.shields.io/github/last-commit/xemantic/xemantic-ai-tool-schema\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/commits/main/)\n\n[\u003cimg alt=\"GitHub contributors\" src=\"https://img.shields.io/github/contributors/xemantic/xemantic-ai-tool-schema\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/graphs/contributors)\n[\u003cimg alt=\"GitHub commit activity\" src=\"https://img.shields.io/github/commit-activity/t/xemantic/xemantic-ai-tool-schema\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/commits/main/)\n[\u003cimg alt=\"GitHub code size in bytes\" src=\"https://img.shields.io/github/languages/code-size/xemantic/xemantic-ai-tool-schema\"\u003e]()\n[\u003cimg alt=\"GitHub Created At\" src=\"https://img.shields.io/github/created-at/xemantic/xemantic-ai-tool-schema\"\u003e](https://github.com/xemantic/xemantic-ai-tool-schema/commits)\n[\u003cimg alt=\"kotlin version\" src=\"https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fxemantic%2Fxemantic-ai-tool-schema%2Fmain%2Fgradle%2Flibs.versions.toml\u0026query=versions.kotlin\u0026label=kotlin\"\u003e](https://kotlinlang.org/docs/releases.html)\n[\u003cimg alt=\"discord users online\" src=\"https://img.shields.io/discord/811561179280965673\"\u003e](https://discord.gg/vQktqqN2Vn)\n[![Bluesky](https://img.shields.io/badge/Bluesky-0285FF?logo=bluesky\u0026logoColor=fff)](https://bsky.app/profile/xemantic.com)\n\n\u003e [!IMPORTANT]\n\u003e 🤖 **Build Your Own AI Agents** - Join our one-day Agentic AI \u0026 Creative Coding Workshop in Berlin (Spring 2025), led by AI hack Berlin hackathon winner Kazik Pogoda. Learn to create autonomous AI agents using Anthropic API, engineer advanced prompts, and give your agents tools to control machines. Workshops run Tuesdays (Feb 25 - Mar 25) at Prachtsaal Berlin, limited to 15 participants. 150 EUR contribution supports open source development (solidarity access available, no questions asked). All examples use Kotlin (crash course included) but focus on meta-principles of AI agent development. Details: \u003chttps://xemantic.com/ai/workshops\u003e\n\n## Why?\n\nThis library was created to fulfill the need of agentic AI projects created by [xemantic](https://xemantic.com/). In particular:\n\n* [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).\n* [claudine](https://github.com/xemantic/claudine) - AI Agent build on top of this SDK.\n\nThese 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.\n\nIn 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).\n\n\u003e [!TIP]\n\u003e 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.\n\n## Usage\n\nIn `build.gradle.kts` add:\n\n```kotlin\nplugins {\n    kotlin(\"multiplatform\") version \"2.1.0\" // (or jvm for jvm-only project)\n    kotlin(\"plugin.serialization\") version \"2.1.0\"\n}\n\n// ...\ndependencies {\n    implementation(\"com.xemantic.ai:xemantic-ai-tool-schema:1.1.2\")\n}\n```\n\nThen in your code you can define entities like this:\n\n```kotlin\n@Serializable\n@SerialName(\"address\")\n@Title(\"The full address\")\n@Description(\"An address of a person or an organization\")\ndata class Address(\n    val street: String,\n    val city: String,\n    @Description(\"A postal code not limited to particular country\")\n    @MinLength(3)\n    @MaxLength(10)\n    val postalCode: String,\n    @Pattern(\"[a-z]{2}\")\n    val countryCode: String,\n    @Format(StringFormat.EMAIL)\n    val email: String? = null\n)\n```\n\nAnd when `jsonSchemaOf()` function is invoked:\n\n```kotlin\nval schema = jsonSchemaOf\u003cAddress\u003e()\n```\n\nIt will produce a [JsonSchema](src/commonMain/kotlin/JsonSchema.kt) instance, which serializes to:\n\n```json\n{\n  \"type\": \"object\",\n  \"title\": \"The full address\",\n  \"description\": \"An address of a person or an organization\",\n  \"properties\": {\n    \"street\": {\n      \"type\": \"string\"\n    },\n    \"city\": {\n      \"type\": \"string\"\n    },\n    \"postalCode\": {\n      \"type\": \"string\",\n      \"description\": \"A postal code not limited to particular country\",\n      \"minLength\": 3,\n      \"maxLength\": 10\n    },\n    \"countryCode\": {\n      \"type\": \"string\",\n      \"pattern\": \"[a-z]{2}\"\n    },\n    \"email\": {\n      \"type\": \"string\",\n      \"format\": \"email\"\n    }\n  },\n  \"required\": [\n    \"street\",\n    \"city\",\n    \"postalCode\",\n    \"countryCode\"\n  ]\n}\n```\n\nAnd 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).\nWhen requesting a tool use, these LLMs will send a JSON payload adhering to this schema, therefore immediately deserializable as the original `@Serializable` Kotlin class.\n\nMore details and use cases in the [JsonSchemaGeneratorTest](src/commonTest/kotlin/generator/JsonSchemaGeneratorTest.kt).\n\n\u003e [!NOTE]\n\u003e 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.\n\n### Serializing Java `BigDecimal`s\n\nFor 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.\n\nSee [JavaBigDecimalToSchemaTest](src/jvmTest/kotlin/serialization/JavaBigDecimalToSchemaTest.kt) for details.\n\n### Serializing BigDecimal/monetary values in multiplatform way\n\nThere 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.\n\nSee also [xemantic-ai-money](https://github.com/xemantic/xemantic-ai-money]) project for a ready solution packaged as a library.\n\n## Development\n\nClone this repo and then in the project dir:\n\n```shell\n./gradlew build\n```\n\n## Non-recommended usage\n\n\u003e [!WARNING]\n\u003e Even though this library provides basic serializable representation of a JSON Schema, it is not meant to fully model general purpose JSON Schema.\n\u003e In particular, it should not be used for deserializing existing schemas from JSON.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxemantic%2Fxemantic-ai-tool-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxemantic%2Fxemantic-ai-tool-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxemantic%2Fxemantic-ai-tool-schema/lists"}