[FEATURE] Support JSON schema for tool definitions

[gjtorikian]

Scope check

• This is core LLM communication (not application logic)
• This benefits most users (not just my use case)
• This can't be solved in application code with current RubyLLM
• I read the Contributing Guide

Due diligence

• I searched existing issues
• I checked the documentation

What problem does this solve?

Currently, defining tools with RubyLLM requires using a DSL. The DSL for defining parameters really only supports a handful of schema definitions: the name of the property, its type, and whether or not it's required.

I had the need to make a parameter include a default value, and while I could just add to the DSL, it would be more flexible to simply support JSON schemas, just like chatting with output schemas. Supporting JSON schema would resolve the issue of not providing default and allow for the full range of JSON schema properties (enums, min/max values, etc).

Furthermore, while initially investigating this, it seems like several providers each use their own function to format tooling.

• Anthropic tools support JSON schema, and the provider uses Tool.function_for function to format these
• Gemini supports a subset of JSON schema, and the provider uses its own function_decleration_for function to format these
• OpenAI tools support JSON schema, and it—you guessed it—uses its own function tool_for to format these

Although each provider needs its own formatting, the logic between them often overlaps, making an additive change like this require updates in at least three places.

Proposed solution

First, I would consolidate the various tool assemblages into one module as much as possible.

For actually supporting the schema, I would introduce a function called with_schema, that takes a block whose return should be the schema you expect the tool to have. Something like:

class Weather < RubyLLM::Tool
  with_schema do
    {
      type: 'function',
      name: 'get_weather',
      description: 'Retrieves current weather for the given location.',
      parameters: {
        type: 'object',
        properties: {
          location: {
            type: 'string',
            description: 'City and country e.g. Bogotá, Colombia'
          },
          units: {
            type: 'string',
            enum: %w[
              celsius
              fahrenheit
            ],
            description: 'Units the temperature will be returned in.'
          }
        },
        required: %w[
          location
          units
        ],
        additionalProperties: false
      },
      strict: true
    }
  end

  def execute(latitude:, longitude:)
    # ...
  end
end

I don't mind doing this consolidation work and opening a PR! But I wouldn't take such an undertaking without prior approval. ✌️

Why this belongs in RubyLLM

Because calling tools with JSON schemas is a core feature of these APIs.

[crmne]

I doubt you searched: #76

Due diligence

• I searched existing issues[x] I checked the documentation

[gjtorikian]

I doubt you searched: #76

I did. That issue (and its associated PR) is talking about expanding the DSL; I'm talking about supporting raw JSON schema. Despite the title, no one mentions this as an option.

Well, I'm happy it's on the radar. There are so many PRs open, without comment, let alone with CI checks run, that I doubted this project was maintained.

[crmne]

21 commits only today: https://github.com/crmne/ruby_llm/commits/main/

[tpaulshippy]

I did. That issue (and its associated PR) is talking about expanding the DSL; I'm talking about supporting raw JSON schema. Despite the title, no one mentions this as an option.

We have attempted to solve this problem in numerous ways as I mentioned here:
#112
#124

I think we are waiting on either this or this

[tpaulshippy]

There are so many PRs open, without comment, let alone with CI checks run

You are not wrong about this.

[gjtorikian]

We have attempted to solve this problem in numerous ways as I mentioned

Yowza, thanks for these links as context. As I said, I only searched to see if there was interest in raw JSON schema; I interpreted the issues I had found to be solely about tweaking the DSL. I see now that you all have been discussing this for far longer, so thank you for collating those. It seems like the DSL is the preferred way.

[tpaulshippy]

I doubted this project was maintained.

This part of your comment is pretty unfair. There are new releases coming out all the time and I had a PR get merged just last weekend. Carmine is very active, and the project is definitely getting maintained.

[gjtorikian]

I think insulting people who ask questions is pretty unfair, too. I can appreciate a popular project needing guidelines to limit easily answerable questions, but the fact remains that proposing a new way to define inputs isn't the same as enhancing the existing DSL. To be honest, I'm still not sure

But yes, it was rude, because I was upset, and I apologize to @crmne. ✌️

[crmne]

No worries @gjtorikian. Apology accepted.

Let's ship! 🚀

[bricolage]

I've just submitted PR #337 as a proof-of-concept for using RubyLLM::Schema, for OpenAI and Anthropic. @crmne @tpaulshippy

[beydogan]

Here is a monkey patch for anyone needs this now until its released: https://gist.github.com/beydogan/05056695ff4a656358940997c5bf1157

its only for OpenAI. In rails, you can put it in an initializer.