prompt_schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62c2a73666e89f46d35417027681166656c91a54481f283d913dd9f27dcab593
+  data.tar.gz: 63bc30999ca378e39ede7bb33954341d6cd3e3d5c5aa5c629de717b94fd8ccd6
+SHA512:
+  metadata.gz: 27f80256717d64e83e07f68dec2ced8c0b0d751a63ac9394ea0f36a70f9c8a29eecebbfcbe0d04a3c03f2611c06d665f21adb0ce63f93c8456aa3a1d4f235c7c
+  data.tar.gz: 49d75e170c6005f665374c5f1e7b052f5cb5137a24cb729fefd8aa172dfb6a3e09d76dbcd03c87cedb62c49063309ce6030eb7ae542c069f1693538a36aa7221

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,6 @@
+require:
+  - rubocop-inhouse
+
+inherit_gem:
+  rubocop-inhouse:
+    - config/default.yml

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-07-05
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nolan J Tait
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+# PromptSchema
+
+This is a library to give you BAML style JSON schemas that you can feed to an
+LLM using your existing `dry-schema` with annotated types.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add prompt_schema
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install prompt_schema
+```
+
+## Usage
+
+Schemas are defined as a class that wraps a regular `dry-schema`:
+
+```ruby
+schema = Dry::Schema.JSON do
+  required(:user).hash do
+    required(:email).maybe(:string)
+  end
+end
+
+prompt_schema = PromptSchema::Schema.new(schema)
+```
+
+For convenience you can use `define` to have this wrapping be done for you:
+
+```ruby
+schema = PromptSchema.define do
+  required(:user).hash do
+    required(:email).maybe(:string)
+  end
+end
+
+schema.is_a?(PromptSchema::Schema) #=> true
+schema.dry_schema.is_a?(Dry::Schema) #=> true
+
+result = schema.call({ user: { email: "email@example.com" }})
+result.success? #=> true
+```
+
+Using this schema we can print a ready to go prompt.
+
+```ruby
+schema.prompt
+```
+
+Which would return a string of a BAML style prompt:
+
+```
+Answer in JSON using this schema:
+{
+  user: {
+    email: string or null,
+  },
+}
+```
+
+To get the descriptions we can annotate our own types using `dry-types`:
+
+```ruby
+module Types
+  include Dry.Types()
+
+  Email = Types::String.meta(
+    description: "An email address",
+    example: "email@example.com"
+  )
+end
+
+schema = PromptSchema.define do
+  required(:user).hash do
+    required(:email).maybe(Types::Email)
+  end
+end
+
+schema.prompt
+```
+
+Which would now annotate the field
+
+```
+Answer in JSON using this schema:
+{
+  user: {
+    // An email address
+    // @example email@example.com
+    email: string or null,
+  },
+}
+```
+
+This can be useful to get the best parts of BAML in a ruby native way.
+
+## How it works
+
+All `Dry::Schema` objects have an Abstract Syntax Tree (AST) that we can tap
+into to build another representation.
+
+We turn the dry schema AST (and its corresponding type schema AST) into
+a structure that looks like this:
+
+```ruby
+schema = Dry::Schema.Params do
+  required(:user).hash do
+    required(:email).value(Types::Email)
+  end
+end
+
+compiled = PromptSchema.compile(schema)
+
+expected = {
+  keys: {
+    user: {
+      type: "hash",
+      required: true,
+      nullable: false,
+      keys: {
+        email: {
+          type: "string",
+          required: true,
+          nullable: false,
+          example: "email@example.com",
+          description: "An email address"
+        }
+      }
+    }
+  }
+}
+
+compiled == expected #=> true
+```
+
+Then we use a renderer to take this compiled schema and output a string that can
+be used as part of a prompt.
+
+Rendering of the prompt is handled through a Phlex component. You could take
+this same representation and write your own version.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nolantait/prompt_schema.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/prompt_schema/prompt.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PromptSchema
+  # Generates a prompt for an LLM based on a compiled schema.
+  class Prompt < Phlex::HTML
+    # @param schema [Hash] The compiled schema to generate the prompt for.
+    #   This should be the output of `PromptSchema::SchemaCompiler.call`.
+    # @example
+    #   PromptSchema::Prompt.new(schema).call
+    # @return [String] The generated prompt.
+    def initialize(schema)
+      @compiled = SchemaCompiler.call(schema)
+      @indentation = 0
+    end
+
+    def view_template
+      text "Answer in JSON using this schema:"
+      render_structure(@compiled[:keys])
+    end
+
+    private
+
+    def render_structure(keys, nullable: false, nested: false)
+      closing = [
+        "}",
+        (" or null" if nullable),
+        ("," if nested)
+      ].compact.join
+
+      inside("{", closing) do
+        render_keys(keys)
+      end
+    end
+
+    def render_keys(keys)
+      keys.each do |key, info|
+        item(key, info)
+      end
+    end
+
+    def item(key, info)
+      comment info[:description] if info[:description]
+      example info[:example] if info[:example]
+      handle_type(key, info)
+    end
+
+    def handle_type(key, info) # rubocop:disable Metrics/AbcSize
+      case info[:type]
+      when "array"
+        if info[:member].is_a?(Hash)
+          inside("#{key}: [", "],") do
+            render_structure(
+              info[:member][:keys],
+              nullable: info[:nullable],
+              nested: true
+            )
+          end
+        else
+          text("#{key}: #{info[:member]}[]")
+        end
+      when "hash"
+        inside("#{key}: {", "},") do
+          render_keys(info[:keys])
+        end
+      else
+        text("#{key}: ", newline: false)
+
+        types = [info[:type], ("null" if info[:nullable])]
+
+        text(
+          types.compact.join(" or "),
+          newline: false,
+          indent: false
+        )
+
+        text(",", indent: false)
+      end
+    end
+
+    def inside(opening, closing, &)
+      text opening
+      with_indentation(&)
+      text closing
+    end
+
+    def with_indentation
+      @indentation += 2
+      yield
+      @indentation -= 2
+    end
+
+    def comment(content, **)
+      text("// #{content}", **)
+    end
+
+    def example(content, **)
+      comment("@example #{content}", **)
+    end
+
+    def text(content, newline: true, indent: true)
+      plain " " * @indentation if indent
+      raw safe(content)
+      plain "\n" if newline
+    end
+  end
+end

data/lib/prompt_schema/schema.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PromptSchema
+  # Represents a Dry::Schema schema, providing methods to access its
+  # properties and to generate prompts based on the schema.
+  class Schema
+    attr_reader :dry_schema
+
+    def initialize(dry_schema)
+      @dry_schema = dry_schema
+    end
+
+    def [](...) = @dry_schema.[](...)
+    def call(...) = @dry_schema.call(...)
+
+    def prompt
+      Prompt.call(@dry_schema)
+    end
+  end
+end

data/lib/prompt_schema/schema_compiler.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module PromptSchema
+  # Compiles a Dry::Schema schema into a hash representation that can be used
+  # to generate prompts for LLMs.
+  class SchemaCompiler # rubocop:disable Metrics/ClassLength
+    EMPTY_HASH = {}.freeze
+
+    PREDICATE_TO_TYPE = {
+      array?: "array",
+      bool?: "bool",
+      date?: "date",
+      date_time?: "date_time",
+      decimal?: "float",
+      float?: "float",
+      hash?: "hash",
+      int?: "integer",
+      nil?: "nil",
+      str?: "string",
+      time?: "time"
+    }.freeze
+
+    attr_reader :keys
+
+    def self.call(schema) = new(schema).call
+
+    # @param schema [Dry::Schema::Schema] The schema to compile.
+    def initialize(schema)
+      @schema = schema
+      @type_schema = TypeSchemaCompiler.call(schema.type_schema.to_ast)
+      @keys = EMPTY_HASH.dup
+    end
+
+    # @return [Hash] The compiled schema as a hash.
+    def to_h
+      { keys: keys }
+    end
+
+    # @return [Hash] The compiled schema as a hash
+    def call
+      visit(@schema.to_ast)
+      to_h
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit(node, **)
+      meth, rest = node
+      public_send(:"visit_#{meth}", rest, **)
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_set(node, **opts)
+      key = opts[:key]
+      target = key ? self.class.new(@schema) : self
+
+      node.each { |child| target.visit(child, **opts.except(:member)) }
+
+      return unless key
+
+      target_info = opts[:member] ? { member: target.to_h } : target.to_h
+      type = opts[:member] ? "array" : "hash"
+      data = { **keys[key], type:, **target_info }
+
+      keys.update(key => data)
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_and(node, **)
+      left, right = node
+
+      visit(left, **)
+      visit(right, **)
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_implication(node, **)
+      case node
+      in [:not, [:predicate, [:nil?, _]]], el
+        visit(el, **, nullable: true)
+      else
+        node.each do |el|
+          visit(el, **, required: false)
+        end
+      end
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_each(node, **opts)
+      opts[:key_path] ||= []
+      opts[:key_path] << :items
+
+      visit(node, **opts, member: true)
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_key(node, **opts)
+      name, rest = node
+      opts[:key_path] ||= []
+      opts[:key_path] << name
+
+      visit(rest, **opts, key: name, required: true)
+      opts[:key_path].pop
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_predicate(node, **opts)
+      name, rest = node
+      key = opts[:key]
+
+      case name
+      when :key?
+        visit_predicate_key(rest, **opts)
+      when :type?
+        visit_predicate_type(rest, **opts)
+      else
+        visit_predicate_base_type(name, key, **opts)
+      end
+    end
+
+    # @param name [Symbol] The name of the predicate.
+    # @param key [Symbol] The key to assign the type to.
+    # @param opts [Hash] Additional options for assigning the type.
+    # @return [void]
+    def visit_predicate_base_type(name, key, **opts)
+      type = PREDICATE_TO_TYPE[name]
+      return unless type
+
+      assign_type(
+        key,
+        type,
+        **opts,
+        nullable: opts.fetch(:nullable, false)
+      )
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_predicate_key(node, **opts)
+      (_, name), = node
+      keys[name] ||= {}
+      keys[name] = { **keys[name], required: opts.fetch(:required, true) }
+    end
+
+    # @param node [Array] The AST node to visit.
+    # @param opts [Hash] Options for visiting the node.
+    # @return [void]
+    def visit_predicate_type(node, **opts)
+      (_type, type_class), _input = node
+      key = opts[:key]
+
+      if type_class.is_a?(Dry::Types::Type)
+        keys[key].merge!(type_class.meta)
+
+        assign_type(
+          key,
+          type_class.name.downcase,
+          **opts,
+          nullable: opts.fetch(:nullable, false)
+        )
+      else
+        visit(type_class.to_ast, **opts, key: key, member: true)
+      end
+    end
+
+    # @param key [Symbol] The key to assign the type to.
+    # @param type [String] The type to assign to the key.
+    # @param opts [Hash] Additional options for assigning the type.
+    # @return [void]
+    def assign_type(key, type, **opts)
+      if keys.dig(key, :type)
+        keys[key][:member] = type
+      else
+        keys[key][:type] = type
+        keys[key][:nullable] = opts.fetch(:nullable, false)
+      end
+
+      meta = @type_schema.dig(*opts[:key_path])
+      keys[key].merge!(meta.slice(:description, :example)) if meta
+    end
+  end
+end

data/lib/prompt_schema/type_schema_compiler.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module PromptSchema
+  # Compiles a Dry::Types AST into a type schema hash. This is required because
+  # we need to get the specific metadata information which is only available in
+  # the Dry::Types AST, not in the Dry::Schema AST.
+  class TypeSchemaCompiler
+    def self.call(ast) = new.call(ast)
+
+    def call(ast)
+      visit(ast)
+    end
+
+    private
+
+    def visit(node)
+      type, body = node
+      send("visit_#{type}", body)
+    end
+
+    def visit_schema(node)
+      keys, _options, _meta = node
+      keys.to_h { |key| visit(key) }
+    end
+
+    def visit_key(node)
+      name, required, type_node = node
+      type_info = visit(type_node)
+      [name, { required: required, **type_info }]
+    end
+
+    def visit_nominal(node)
+      klass, meta = node
+      {
+        type: dry_type_name(klass),
+        **meta
+      }
+    end
+
+    def visit_maybe(node)
+      inner = visit(node)
+      inner[:type] = "maybe.#{inner[:type]}"
+      inner
+    end
+
+    def visit_array(node)
+      member_node, meta = node
+
+      member_info = if member_node.is_a?(Array) && member_node.first == :schema
+        visit_schema(member_node.last)
+      elsif member_node.is_a?(Class)
+        { type: dry_type_name(member_node) }
+      else
+        visit(member_node)
+      end
+
+      {
+        type: "array",
+        items: member_info,
+        **meta
+      }
+    end
+
+    def visit_sum(node)
+      *types, meta = node
+      type_names = types.map { |t| visit(t)[:type] }
+      {
+        type: type_names.join(" | "),
+        **meta
+      }
+    end
+
+    def visit_map(node)
+      key_type, value_type, meta = node
+      {
+        type: "map[#{visit(key_type)[:type]} => #{visit(value_type)[:type]}]",
+        **meta
+      }
+    end
+
+    def visit_constrained(node)
+      base_type, rule = node
+      base = visit(base_type)
+      base[:rule] = rule
+      base
+    end
+
+    def visit_constructor(node)
+      base_type, _fn = node
+      visit(base_type)
+    end
+
+    def visit_lax(node)
+      visit(node)
+    end
+
+    def visit_enum(node)
+      type_node, mapping = node
+      {
+        type: "enum(#{visit(type_node)[:type]})",
+        values: mapping.values
+      }
+    end
+
+    def visit_any(meta)
+      {
+        type: "any",
+        **meta
+      }
+    end
+
+    def dry_type_name(klass)
+      Dry::Types.identifier(klass) || klass.name || klass.to_s
+    end
+  end
+end

data/lib/prompt_schema/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PromptSchema
+  VERSION = "0.1.0"
+end

data/lib/prompt_schema.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "debug"
+
+require "dry/schema"
+require "dry/types"
+require "phlex"
+
+require_relative "prompt_schema/version"
+require_relative "prompt_schema/type_schema_compiler"
+require_relative "prompt_schema/schema_compiler"
+require_relative "prompt_schema/schema"
+require_relative "prompt_schema/prompt"
+
+module PromptSchema
+  class Error < StandardError; end
+
+  # Defines a schema using Dry::Schema and returns a Schema instance.
+  #
+  # @example
+  # PromptSchema.define do
+  #  required(:name).filled(:string)
+  # end
+  #
+  # @return [PromptSchema::Schema]
+  def self.define(&)
+    dry_schema = Dry::Schema.JSON(&)
+    Schema.new(dry_schema)
+  end
+
+  # Compiles a schema into a format suitable for generating prompts.
+  # This is a wrapper around `PromptSchema::SchemaCompiler.call`.
+  #
+  # @example
+  # PromptSchema.compile(schema)
+  #
+  # @param schema [Dry::Schema::Schema] The schema to compile.
+  # @return [Hash] The compiled schema as a hash.
+  def self.compile(schema)
+    SchemaCompiler.call(schema)
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: prompt_schema
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nolan J Tait
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: phlex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Generate BAML style prompts from dry-schema that can get and check structured
+  responses from LLMs
+email:
+- nolanjtait@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/prompt_schema.rb
+- lib/prompt_schema/prompt.rb
+- lib/prompt_schema/schema.rb
+- lib/prompt_schema/schema_compiler.rb
+- lib/prompt_schema/type_schema_compiler.rb
+- lib/prompt_schema/version.rb
+homepage: https://github.com/nolantait/prompt_schema
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nolantait/prompt_schema
+  source_code_uri: https://github.com/nolantait/prompt_schema
+  changelog_uri: https://github.com/nolantait/prompt_schema
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.0
+specification_version: 4
+summary: Generate prompt schemas for LLMs to get and check structured data.
+test_files: []