structify 0.1.0 → 0.3.0

data/lib/structify/model.rb

@@ -3,10 +3,11 @@
 require "active_support/concern"
 require "active_support/core_ext/class/attribute"
 require "attr_json"
+require_relative "schema_serializer"
 
 module Structify
   # The Model module provides a DSL for defining LLM extraction schemas in your Rails models.
-  # It allows you to define fields, versioning, and assistant prompts for LLM-based data extraction.
+  # It allows you to define fields, versioning, and validation for LLM-based data extraction.
   #
   # @example
   #   class Article < ApplicationRecord
@@ -16,8 +17,6 @@ module Structify
   #       title "Article Extraction"
   #       description "Extract article metadata"
   #       version 1
-  #       assistant_prompt "Extract the following fields from the article"
-  #       llm_model "gpt-4"
   #
   #       field :title, :string, required: true
   #       field :summary, :text, description: "A brief summary of the article"
@@ -31,8 +30,40 @@ module Structify
       include AttrJson::Record
       class_attribute :schema_builder, instance_writer: false, default: nil
 
-      # Store all extracted data in the extracted_data JSON column
-      attr_json_config(default_container_attribute: :extracted_data)
+      # Use the configured default container attribute
+      attr_json_config(default_container_attribute: Structify.configuration.default_container_attribute)
+    end
+    
+    # Instance methods
+    def version_compatible_with?(required_version)
+      container_attribute = self.class.attr_json_config.default_container_attribute
+      record_data = self.send(container_attribute) || {}
+      record_version = record_data["version"] || 1
+      record_version >= required_version
+    end
+    
+    # Get the stored version of this record
+    def stored_version
+      container_attribute = self.class.attr_json_config.default_container_attribute
+      record_data = self.send(container_attribute) || {}
+      record_data["version"] || 1
+    end
+    
+    # Check if a version is within a given range/array of versions
+    # This is used in field accessors to check version compatibility
+    #
+    # @param version [Integer] The version to check
+    # @param range [Range, Array, Integer] The range, array, or single version to check against
+    # @return [Boolean] Whether the version is within the range
+    def version_in_range?(version, range)
+      case range
+      when Range
+        range.cover?(version)
+      when Array
+        range.include?(version)
+      else
+        version == range
+      end
     end
 
     # Class methods added to the including class
@@ -60,19 +91,6 @@ module Structify
         schema_builder&.version_number
       end
 
-      # Get the assistant prompt
-      #
-      # @return [String] The assistant prompt
-      def extraction_assistant_prompt
-        schema_builder&.assistant_prompt_str
-      end
-
-      # Get the LLM model name
-      #
-      # @return [String] The model name
-      def extraction_llm_model
-        schema_builder&.model_name
-      end
     end
   end
 
@@ -82,11 +100,9 @@ module Structify
     # @return [Array<Hash>] The field definitions
     # @return [String] The schema title
     # @return [String] The schema description
-    # @return [String] The assistant prompt
-    # @return [String] The LLM model name
     # @return [Integer] The schema version
-    attr_reader :model, :fields, :title_str, :description_str,
-                :assistant_prompt_str, :model_name, :version_number
+    # @return [Boolean] Whether thinking mode is enabled
+    attr_reader :model, :fields, :title_str, :description_str, :version_number, :thinking_enabled
 
     # Initialize a new SchemaBuilder
     #
@@ -94,9 +110,17 @@ module Structify
     def initialize(model)
       @model = model
       @fields = []
-      @assistant_prompt_str = nil
-      @model_name = nil
       @version_number = 1
+      @thinking_enabled = false
+    end
+    
+    # Enable or disable thinking mode
+    # When enabled, the LLM will be asked to provide chain of thought reasoning
+    #
+    # @param enabled [Boolean] Whether to enable thinking mode
+    # @return [void]
+    def thinking(enabled)
+      @thinking_enabled = enabled
     end
 
     # Set the schema title
@@ -121,24 +145,15 @@ module Structify
     # @return [void]
     def version(num)
       @version_number = num
-      model.attribute :version, :integer, default: num
+      
+      # Define version as an attr_json field so it's stored in extracted_data
+      model.attr_json :version, :integer, default: num
+      
+      # Store mapping of fields to their introduction version
+      @fields_by_version ||= {}
+      @fields_by_version[num] ||= []
     end
 
-    # Set the assistant prompt
-    #
-    # @param prompt [String] The prompt text
-    # @return [void]
-    def assistant_prompt(prompt)
-      @assistant_prompt_str = prompt.strip
-    end
-
-    # Set the LLM model name
-    #
-    # @param name [String] The model name
-    # @return [void]
-    def llm_model(name)
-      @model_name = name
-    end
 
     # Define a field in the schema
     #
@@ -147,40 +162,269 @@ module Structify
     # @param required [Boolean] Whether the field is required
     # @param description [String] The field description
     # @param enum [Array] Possible values for the field
+    # @param items [Hash] For array type, defines the schema for array items
+    # @param properties [Hash] For object type, defines the properties of the object
+    # @param min_items [Integer] For array type, minimum number of items
+    # @param max_items [Integer] For array type, maximum number of items
+    # @param unique_items [Boolean] For array type, whether items must be unique
+    # @param versions [Range, Array, Integer] The versions this field is available in (default: current version onwards)
     # @return [void]
-    def field(name, type, required: false, description: nil, enum: nil)
-      fields << {
+    def field(name, type, required: false, description: nil, enum: nil, 
+              items: nil, properties: nil, min_items: nil, max_items: nil, 
+              unique_items: nil, versions: nil)
+      
+      # Handle version information
+      version_range = if versions
+                        # Use the versions parameter if provided
+                        versions
+                      else
+                        # Default: field is available in all versions
+                        1..999
+                      end
+      
+      # Check if the field is applicable for the current schema version
+      field_available = version_in_range?(@version_number, version_range)
+      
+      # Skip defining the field in the schema if it's not applicable to the current version
+      unless field_available
+        # Still define an accessor that raises an appropriate error
+        define_version_range_accessor(name, version_range)
+        return
+      end
+      
+      # Calculate a simple introduced_in for backward compatibility
+      effective_introduced_in = case version_range
+                               when Range
+                                 version_range.begin
+                               when Array
+                                 version_range.min
+                               else
+                                 version_range
+                               end
+      
+      field_definition = {
         name: name,
         type: type,
         required: required,
         description: description,
-        enum: enum
+        version_range: version_range,
+        introduced_in: effective_introduced_in
       }
+      
+      # Add enum if provided
+      field_definition[:enum] = enum if enum
+      
+      # Array specific properties
+      if type == :array
+        field_definition[:items] = items if items
+        field_definition[:min_items] = min_items if min_items
+        field_definition[:max_items] = max_items if max_items
+        field_definition[:unique_items] = unique_items if unique_items
+      end
+      
+      # Object specific properties
+      if type == :object
+        field_definition[:properties] = properties if properties
+      end
+      
+      fields << field_definition
+      
+      # Track field by its version range
+      @fields_by_version ||= {}
+      @fields_by_version[effective_introduced_in] ||= []
+      @fields_by_version[effective_introduced_in] << name
+
+      # Map JSON Schema types to Ruby/AttrJson types
+      attr_type = case type
+                  when :integer, :number
+                    :integer
+                  when :array
+                    :json
+                  when :object
+                    :json
+                  when :boolean
+                    :boolean
+                  else
+                    type # string, text stay the same
+                  end
 
+      # Define custom accessor that checks version compatibility
+      define_version_range_accessors(name, attr_type, version_range)
+    end
+    
+    # Check if a version is within a given range/array of versions
+    #
+    # @param version [Integer] The version to check
+    # @param range [Range, Array, Integer] The range, array, or single version to check against
+    # @return [Boolean] Whether the version is within the range
+    def version_in_range?(version, range)
+      case range
+      when Range
+        # Handle endless ranges (Ruby 2.6+): 2.. means 2 and above
+        if range.end.nil?
+          version >= range.begin
+        else
+          range.cover?(version)
+        end
+      when Array
+        range.include?(version)
+      else
+        # A single integer means "this version and onwards"
+        version >= range
+      end
+    end
+    
+    # Define accessor methods that check version compatibility using the new version ranges
+    #
+    # @param name [Symbol] The field name
+    # @param type [Symbol] The field type for attr_json
+    # @param version_range [Range, Array, Integer] The versions this field is available in
+    # @return [void]
+    def define_version_range_accessors(name, type, version_range)
+      # Define the attr_json normally first
       model.attr_json name, type
+      
+      # Extract current version for error messages
+      schema_version = @version_number
+      
+      # Then override the reader method to check versions
+      model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        # Store original method
+        alias_method :_original_#{name}, :#{name}
+        
+        # Override reader to check version compatibility
+        def #{name}
+          # Get the container attribute and data
+          container_attribute = self.class.attr_json_config.default_container_attribute
+          record_data = self.send(container_attribute)
+          
+          # Get the version from the record data
+          record_version = record_data && record_data["version"] ? 
+                           record_data["version"] : 1
+          
+          # Check if record version is compatible with field's version range
+          field_version_range = #{version_range.inspect}
+          
+          # Handle field lifecycle based on version
+          unless version_in_range?(record_version, field_version_range)
+            # Check if this is a removed field (was valid in earlier versions but not current version)
+            if field_version_range.is_a?(Range) && field_version_range.begin <= record_version && field_version_range.end < #{schema_version}
+              raise Structify::RemovedFieldError.new(
+                "#{name}", 
+                field_version_range.end
+              )
+            # Check if this is a new field (only valid in later versions)
+            elsif (field_version_range.is_a?(Range) && field_version_range.begin > record_version) ||
+                  (field_version_range.is_a?(Integer) && field_version_range > record_version)
+              raise Structify::VersionRangeError.new(
+                "#{name}", 
+                record_version,
+                field_version_range
+              )
+            # Otherwise it's just not in the valid range
+            else
+              raise Structify::VersionRangeError.new(
+                "#{name}", 
+                record_version, 
+                field_version_range
+              )
+            end
+          end
+          
+          # Check for deprecated fields and show warning
+          if field_version_range.is_a?(Range) && 
+             field_version_range.begin < #{schema_version} && 
+             field_version_range.end < 999 && 
+             field_version_range.cover?(record_version)
+            ActiveSupport::Deprecation.warn(
+              "Field '#{name}' is deprecated as of version #{schema_version} and will be removed in version \#{field_version_range.end}."
+            )
+          end
+          
+          # Call original method
+          _original_#{name}
+        end
+      RUBY
+    end
+    
+    # Define accessor for fields that are not in the current schema version
+    # These will raise an appropriate error when accessed
+    #
+    # @param name [Symbol] The field name
+    # @param version_range [Range, Array, Integer] The versions this field is available in
+    # @return [void]
+    def define_version_range_accessor(name, version_range)
+      # Capture schema version to use in the eval block
+      schema_version = @version_number
+      
+      # Handle different version range types
+      version_range_type = case version_range
+                          when Range
+                            "range"
+                          when Array
+                            "array"
+                          else
+                            "integer"
+                          end
+                          
+      # Extract begin/end values for ranges
+      range_begin = case version_range
+                    when Range
+                      version_range.begin
+                    when Array
+                      version_range.min
+                    else
+                      version_range
+                    end
+                    
+      range_end = case version_range
+                  when Range
+                    version_range.end
+                  when Array
+                    version_range.max
+                  else
+                    version_range
+                  end
+      
+      model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        # Define an accessor that raises an error when accessed
+        def #{name}
+          # Based on the version_range type, create appropriate errors
+          case "#{version_range_type}"
+          when "range"
+            if #{range_begin} <= #{schema_version} && #{range_end} < #{schema_version}
+              # Removed field
+              raise Structify::RemovedFieldError.new("#{name}", #{range_end})
+            elsif #{range_begin} > #{schema_version}
+              # Field from future version
+              raise Structify::VersionRangeError.new("#{name}", #{schema_version}, #{version_range.inspect})
+            else
+              # Not in range for other reasons
+              raise Structify::VersionRangeError.new("#{name}", #{schema_version}, #{version_range.inspect})
+            end
+          when "array"
+            # For arrays, we can only check if the current version is in the array
+            raise Structify::VersionRangeError.new("#{name}", #{schema_version}, #{version_range.inspect})
+          else
+            # For integers, just report version mismatch
+            raise Structify::VersionRangeError.new("#{name}", #{schema_version}, #{version_range.inspect})
+          end
+        end
+        
+        # Define a writer that raises an error too
+        def #{name}=(value)
+          # Use the same error logic as the reader
+          self.#{name}
+        end
+      RUBY
     end
 
     # Generate the JSON schema representation
     #
     # @return [Hash] The JSON schema
     def to_json_schema
-      required_fields = fields.select { |f| f[:required] }.map { |f| f[:name].to_s }
-      properties_hash = fields.each_with_object({}) do |f, hash|
-        prop = { type: f[:type].to_s }
-        prop[:description] = f[:description] if f[:description]
-        prop[:enum] = f[:enum] if f[:enum]
-        hash[f[:name].to_s] = prop
-      end
-
-      {
-        name: title_str,
-        description: description_str,
-        parameters: {
-          type: "object",
-          required: required_fields,
-          properties: properties_hash
-        }
-      }
+      serializer = SchemaSerializer.new(self)
+      serializer.to_json_schema
     end
   end
 end

data/lib/structify/schema_serializer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Structify
+  # Handles serialization of schema definitions to different formats
+  class SchemaSerializer
+    # @return [Structify::SchemaBuilder] The schema builder to serialize
+    attr_reader :schema_builder
+
+    # Initialize a new SchemaSerializer
+    #
+    # @param schema_builder [Structify::SchemaBuilder] The schema builder to serialize
+    def initialize(schema_builder)
+      @schema_builder = schema_builder
+    end
+
+    # Generate the JSON schema representation
+    #
+    # @return [Hash] The JSON schema
+    def to_json_schema
+      # Get current schema version
+      current_version = schema_builder.version_number
+      
+      # Get fields that are applicable to the current schema version
+      fields = schema_builder.fields.select do |f|
+        # Check if the field has a version_range
+        if f[:version_range]
+          version_in_range?(current_version, f[:version_range])
+        # Legacy check for removed_in
+        elsif f[:removed_in]
+          f[:removed_in] > current_version
+        else
+          true
+        end
+      end
+      
+      # Get required fields (excluding fields not in the current version)
+      required_fields = fields.select { |f| f[:required] }.map { |f| f[:name].to_s }
+      
+      # Start with chain_of_thought if thinking mode is enabled
+      properties_hash = {}
+      if schema_builder.thinking_enabled
+        properties_hash["chain_of_thought"] = {
+          type: "string",
+          description: "Explain your thought process step by step before determining the final values."
+        }
+      end
+      
+      # Add all other fields
+      fields.each_with_object(properties_hash) do |f, hash|
+        # Start with the basic type
+        prop = { type: f[:type].to_s }
+        
+        # Add description if available
+        prop[:description] = f[:description] if f[:description]
+        
+        # Add enum if available
+        prop[:enum] = f[:enum] if f[:enum]
+        
+        # Handle array specific properties
+        if f[:type] == :array
+          # Add items schema
+          prop[:items] = f[:items] if f[:items]
+          
+          # Add array constraints
+          prop[:minItems] = f[:min_items] if f[:min_items]
+          prop[:maxItems] = f[:max_items] if f[:max_items]
+          prop[:uniqueItems] = f[:unique_items] if f[:unique_items]
+        end
+        
+        # Handle object specific properties
+        if f[:type] == :object && f[:properties]
+          prop[:properties] = {}
+          required_props = []
+          
+          # Process each property
+          f[:properties].each do |prop_name, prop_def|
+            prop[:properties][prop_name] = prop_def.dup
+            
+            # If a property is marked as required, add it to required list and remove from property definition
+            if prop_def[:required]
+              required_props << prop_name
+              prop[:properties][prop_name].delete(:required)
+            end
+          end
+          
+          # Add required array if we have required properties
+          prop[:required] = required_props unless required_props.empty?
+        end
+        
+        # Add version info to description only if requested by environment variable
+        # This allows for backward compatibility with existing tests
+        if ENV["STRUCTIFY_SHOW_VERSION_INFO"] && f[:version_range] && prop[:description]
+          version_info = format_version_range(f[:version_range])
+          prop[:description] = "#{prop[:description]} (Available in versions: #{version_info})"
+        elsif ENV["STRUCTIFY_SHOW_VERSION_INFO"] && f[:version_range]
+          prop[:description] = "Available in versions: #{format_version_range(f[:version_range])}"
+        end
+        
+        # Legacy: Add a deprecation notice to description
+        if f[:deprecated_in] && f[:deprecated_in] <= current_version
+          deprecation_note = "Deprecated in v#{f[:deprecated_in]}. "
+          prop[:description] = if prop[:description]
+                                "#{deprecation_note}#{prop[:description]}"
+                              else
+                                deprecation_note
+                              end
+        end
+        
+        hash[f[:name].to_s] = prop
+      end
+
+      {
+        name: schema_builder.title_str,
+        description: schema_builder.description_str,
+        parameters: {
+          type: "object",
+          required: required_fields,
+          properties: properties_hash
+        }
+      }
+    end
+    
+    private
+    
+    # Check if a version is within a given range/array of versions
+    #
+    # @param version [Integer] The version to check
+    # @param range [Range, Array, Integer] The range, array, or single version to check against
+    # @return [Boolean] Whether the version is within the range
+    def version_in_range?(version, range)
+      case range
+      when Range
+        # Handle endless ranges (Ruby 2.6+): 2.. means 2 and above
+        if range.end.nil?
+          version >= range.begin
+        else
+          range.cover?(version)
+        end
+      when Array
+        range.include?(version)
+      else
+        # A single integer means "this version and onwards"
+        version >= range
+      end
+    end
+    
+    # Format a version range for display in error messages
+    #
+    # @param versions [Range, Array, Integer] The version range to format
+    # @return [String] A human-readable version range
+    def format_version_range(versions)
+      if versions.is_a?(Range)
+        if versions.end.nil?
+          "#{versions.begin} and above"
+        else
+          "#{versions.begin} to #{versions.end}#{versions.exclude_end? ? ' (exclusive)' : ''}"
+        end
+      elsif versions.is_a?(Array)
+        versions.join(", ")
+      else
+        "#{versions} and above"  # Single integer means this version and onwards
+      end
+    end
+  end
+end

data/lib/structify/version.rb

@@ -1,3 +1,3 @@
 module Structify
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end