xemantic/xemantic-ai-tool-schema

AI/LLM 도구 사용 (function calling) JSON Schema 생성기 - Kotlin @Serializable 클래스를 위한 JSON Schema를 생성하는 Kotlin 멀티플랫폼 (multiplatform) 라이브러리입니다.

이 라이브러리는 xemantic에서 제작한 에이전트형 AI (agentic AI) 프로젝트들의 필요성을 충족하기 위해 만들어졌습니다. 특히 다음과 같은 프로젝트들이 있습니다:

• anthropic-sdk-kotlin - Anthropic SDK의 비공식 Kotlin 멀티플랫폼 (multiplatform) 변형 버전.
• claudine - 이 SDK를 기반으로 구축된 AI 에이전트 (AI Agent).

이 프로젝트들은 많은 대규모 언어 모델 (Large Language Models, LLM)이 제공하는 도구 사용 (function calling) 기능에 크게 의존합니다. xemantic-ai-tool-schema 덕분에, 추가적인 제약 조건이 포함될 수 있는 Kotlin 클래스를 LLM이 제공하는 JSON 도구 사용 입력으로부터 자동으로 인스턴스화할 수 있습니다. 이러한 방식을 통해 모델을 위한 JSON 스키마 (JSON schema)를 정의하는 모든 수동 단계를 피할 수 있어, 과정 중의 오류 가능성을 줄이고 AI 에이전트에게 전달되는 복잡한 데이터 구조도 빠르게 개발할 수 있습니다.

요약하자면, xemantic-ai-tool-schema 라이브러리는 kotlinx.serialization에 따라 @Serializable로 표시된 모든 Kotlin 클래스로부터 JSON 스키마 (JSON Schema)를 생성할 수 있습니다.

팁 (Tip)

Python의 Pydantic 라이브러리의 유사한 기능에 익숙하실 수도 있지만, 표준 Kotlin 직렬화 (serialization)가 이미 모델 메타데이터 제공 기능을 수행하고 있으므로 이 비유는 오해를 불러일으킬 수 있습니다.

build.gradle.kts에 다음을 추가하세요:

plugins {
kotlin("multiplatform") version "2.2.20" // (또는 jvm 전용 프로젝트의 경우 jvm)
kotlin("plugin.serialization") version "2.2.20"
...
}

그 다음 코드에서 다음과 같이 엔티티 (entities)를 정의할 수 있습니다:

@Serializable
@SerialName("address")
@Title("The full address")
...

그리고 jsonSchemaOf() 함수가 호출될 때:

val schema = jsonSchemaOf<Address>()

다음과 같이 직렬화되는 JsonSchema 인스턴스를 생성합니다:

{
"type": "object",
"title": "The full address",
...

그리고 이것은 OpenAI API 및 Anthropic API와 같은 대규모 언语言 모델 (Large Language Model, LLM) API가 수용하는 입력입니다.

도구 사용 (tool use)을 요청할 때, 이러한 LLM들은 이 스키마 (schema)를 준수하는 JSON 페이로드 (payload)를 전송하며, 따라서 원래의 @Serializable Kotlin 클래스로 즉시 역직렬화 (deserializable)될 수 있습니다.

자세한 내용과 사용 사례는 JsonSchemaGeneratorTest에서 확인할 수 있습니다.

참고

JsonSchema의 어떤 인스턴스에 대해서든 toString() 함수를 호출하면, 유효한 JSON 스키마의 보기 좋게 출력된 (pretty printed) String 표현이 생성되며, 이는 결과적으로 Kotlin 클래스를 직렬화된 JSON으로 설명합니다. 이 기능은 테스트 및 디버깅에 유용합니다.

JVM 전용 프로젝트의 경우, java.math.BigDecimal 직렬화를 지정할 수 있습니다. 이는 소수 (decimal) 숫자를 문자열로 직렬화하고, BigDecimal 속성의 생성된 JSON 스키마에 description 및 pattern 속성을 추가합니다.

자세한 내용은 JavaBigDecimalToSchemaTest를 참조하십시오.

이 프로젝트의 테스트에는 Money라고 정의된 인터페이스가 있습니다. 이는 기본 소수 숫자 및 산술 제공자 (arithmetics provider)와 독립적으로 통화 금액을 정의하고 직렬화하는 방법을 설명합니다.

라이브러리로 패키징된 완성된 솔루션은 xemantic-ai-money 프로젝트를 참조하십시오.

이 저장소를 클론(Clone)한 후 프로젝트 디렉토리에서 다음을 실행하십시오:

./gradlew build

경고

이 라이브러리는 JSON 스키마의 기본적인 직렬화 가능한 표현을 제공하지만, 범용 JSON 스키마를 완전히 모델링하기 위한 용도는 아닙니다. 특히, JSON으로부터 기존 스키마를 역직렬화 (deserializing)하는 용도로 사용해서는 안 됩니다.