Class: PatientLLM::Schema

Inherits:
Object
  • Object
show all
Defined in:
lib/patient_llm/schema.rb

Overview

A minimal JSON Schema builder used by the Agent DSL for tool parameters and structured output. It deliberately covers only the common cases — primitive types, enums, required fields, arrays, and nested objects. Pass a raw JSON Schema hash anywhere a schema is accepted for anything beyond that.

Examples:

schema = PatientLLM::Schema.build do
  field :summary, :string, "A short summary", required: true
  field :confidence, :number
  field :tags, array: :string
  field :status, :string, enum: ["draft", "final"]
  field :author, :object do
    field :name, :string, required: true
  end
end

Constant Summary collapse

TYPES =

JSON Schema primitive type names accepted by #field.

%w[string number integer boolean object array null].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Schema

Returns a new instance of Schema.



36
37
38
39
 
# File 'lib/patient_llm/schema.rb', line 36

def initialize
  @properties = {}
  @required = []
end

Class Method Details

.build { ... } ⇒ Hash

Build a JSON Schema object hash from a block of #field declarations.

Yields:

  • the block declaring fields, evaluated in the builder's context

Returns:

  • (Hash) —

    the JSON Schema hash



29
30
31
32
33
 
# File 'lib/patient_llm/schema.rb', line 29

def build(&block)
  builder = new
  builder.instance_eval(&block) if block
  builder.to_h
end

Instance Method Details

#field(name, type = nil, description = nil, required: false, enum: nil, array: nil) { ... } ⇒ Hash Also known as: param

Declare a field on the object schema.

Parameters:

  • name (Symbol, String) —

    the field name

  • type (Symbol, String, Hash, nil) (defaults to: nil) —

    the JSON Schema type, or a raw JSON Schema hash used as-is

  • description (String, nil) (defaults to: nil) —

    a description of the field

  • required (Boolean) (defaults to: false) —

    whether the field is required

  • enum (Array, nil) (defaults to: nil) —

    allowed values for the field

  • array (Symbol, String, Hash, nil) (defaults to: nil) —

    declare an array whose items are this type (or raw schema hash); use with a block for arrays of objects

Yields:

  • an optional block declaring a nested object's fields (with type :object or array: :object)

Returns:

  • (Hash) —

    the field's schema

Raises:

  • (ArgumentError) 


54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/patient_llm/schema.rb', line 54

def field(name, type = nil, description = nil, required: false, enum: nil, array: nil, &block)
  raise ArgumentError, "pass either a type or array:, not both" if type && array

  property =
    if array
      {"type" => "array", "items" => item_schema(array, &block)}
    elsif type
      item_schema(type, &block)
    elsif block
      item_schema(:object, &block)
    else
      raise ArgumentError, "field #{name.inspect} requires a type, array:, or a block"
    end

  property["description"] = description.to_s if description
  property["enum"] = PromptBuilder.jsonify(enum) if enum

  @properties[name.to_s] = property
  @required << name.to_s if required
  property
end

#to_h ⇒ Hash

The JSON Schema hash for the declared fields.

Returns:

  • (Hash) 


80
81
82
83
84
 
# File 'lib/patient_llm/schema.rb', line 80

def to_h
  schema = {"type" => "object", "properties" => @properties}
  schema["required"] = @required unless @required.empty?
  schema
end