dexter_llm 0.1.2

data/lib/dexter_llm/schema/validator.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  module Schema
+    class ValidationError < DexterLlm::Error
+      attr_reader :errors
+
+      def initialize(errors)
+        @errors = errors
+        super("Validation failed: #{errors.join(', ')}")
+      end
+    end
+
+    class Validator
+      def initialize(schema)
+        @schema = schema
+      end
+
+      def validate!(arguments)
+        errors = validate(arguments)
+        raise ValidationError.new(errors) if errors.any?
+        true
+      end
+
+      def validate(arguments)
+        errors = []
+        validate_object(arguments, @schema, [], errors)
+        errors
+      end
+
+      def valid?(arguments)
+        validate(arguments).empty?
+      end
+
+      private
+
+      def validate_object(value, schema, path, errors)
+        return unless schema["type"] == "object"
+
+        unless value.is_a?(Hash)
+          errors << "#{format_path(path)}: expected object, got #{value.class}"
+          return
+        end
+
+        properties = schema["properties"] || {}
+        required = schema["required"] || []
+
+        # Check required fields
+        required.each do |field|
+          unless value.key?(field) || value.key?(field.to_sym)
+            errors << "#{format_path(path + [ field ])}: is required"
+          end
+        end
+
+        # Validate each property
+        value.each do |key, val|
+          key_str = key.to_s
+          prop_schema = properties[key_str]
+          next unless prop_schema
+
+          required_field = required.include?(key_str)
+          validate_value(val, prop_schema, path + [ key_str ], errors, required: required_field)
+        end
+      end
+
+      def validate_value(value, schema, path, errors, required: false)
+        return if value.nil? && !required
+
+        type = schema["type"]
+        any_of = schema["anyOf"]
+
+        if any_of
+          validate_any_of(value, any_of, path, errors, required: required)
+          return
+        end
+
+        case type
+        when "string"
+          validate_string(value, schema, path, errors)
+        when "number"
+          validate_number(value, schema, path, errors)
+        when "integer"
+          validate_integer(value, schema, path, errors)
+        when "boolean"
+          validate_boolean(value, schema, path, errors)
+        when "null"
+          validate_null(value, path, errors)
+        when "array"
+          validate_array(value, schema, path, errors)
+        when "object"
+          validate_object(value, schema, path, errors)
+        end
+      end
+
+      def validate_string(value, schema, path, errors)
+        unless value.is_a?(String)
+          errors << "#{format_path(path)}: expected string, got #{value.class}"
+          return
+        end
+
+        if schema["enum"] && !schema["enum"].include?(value)
+          errors << "#{format_path(path)}: must be one of #{schema['enum'].inspect}"
+        end
+
+        if schema["minLength"] && value.length < schema["minLength"]
+          errors << "#{format_path(path)}: must be at least #{schema['minLength']} characters"
+        end
+
+        if schema["maxLength"] && value.length > schema["maxLength"]
+          errors << "#{format_path(path)}: must be at most #{schema['maxLength']} characters"
+        end
+
+        if schema["pattern"] && !Regexp.new(schema["pattern"]).match?(value)
+          errors << "#{format_path(path)}: must match pattern #{schema['pattern']}"
+        end
+      end
+
+      def validate_number(value, schema, path, errors)
+        unless value.is_a?(Numeric)
+          errors << "#{format_path(path)}: expected number, got #{value.class}"
+          return
+        end
+
+        validate_numeric_constraints(value, schema, path, errors)
+      end
+
+      def validate_integer(value, schema, path, errors)
+        unless value.is_a?(Integer)
+          errors << "#{format_path(path)}: expected integer, got #{value.class}"
+          return
+        end
+
+        validate_numeric_constraints(value, schema, path, errors)
+      end
+
+      def validate_numeric_constraints(value, schema, path, errors)
+        if schema["minimum"] && value < schema["minimum"]
+          errors << "#{format_path(path)}: must be >= #{schema['minimum']}"
+        end
+
+        if schema["maximum"] && value > schema["maximum"]
+          errors << "#{format_path(path)}: must be <= #{schema['maximum']}"
+        end
+
+        if schema["exclusiveMinimum"] && value <= schema["exclusiveMinimum"]
+          errors << "#{format_path(path)}: must be > #{schema['exclusiveMinimum']}"
+        end
+
+        if schema["exclusiveMaximum"] && value >= schema["exclusiveMaximum"]
+          errors << "#{format_path(path)}: must be < #{schema['exclusiveMaximum']}"
+        end
+
+        if schema["multipleOf"] && (value % schema["multipleOf"]) != 0
+          errors << "#{format_path(path)}: must be a multiple of #{schema['multipleOf']}"
+        end
+      end
+
+      def validate_boolean(value, _schema, path, errors)
+        unless value == true || value == false
+          errors << "#{format_path(path)}: expected boolean, got #{value.class}"
+        end
+      end
+
+      def validate_null(value, path, errors)
+        unless value.nil?
+          errors << "#{format_path(path)}: expected null, got #{value.class}"
+        end
+      end
+
+      def validate_array(value, schema, path, errors)
+        unless value.is_a?(Array)
+          errors << "#{format_path(path)}: expected array, got #{value.class}"
+          return
+        end
+
+        if schema["minItems"] && value.length < schema["minItems"]
+          errors << "#{format_path(path)}: must have at least #{schema['minItems']} items"
+        end
+
+        if schema["maxItems"] && value.length > schema["maxItems"]
+          errors << "#{format_path(path)}: must have at most #{schema['maxItems']} items"
+        end
+
+        items_schema = schema["items"]
+        return unless items_schema
+
+        value.each_with_index do |item, index|
+          validate_value(item, items_schema, path + [ index.to_s ], errors)
+        end
+      end
+
+      def validate_any_of(value, variants, path, errors, required: false)
+        variant_errors = []
+
+        variants.each do |variant_schema|
+          variant_errs = []
+          validate_value(value, variant_schema, path, variant_errs, required: required)
+          return if variant_errs.empty? # Valid against this variant
+          variant_errors << variant_errs
+        end
+
+        # None of the variants matched
+        errors << "#{format_path(path)}: does not match any of the allowed types"
+      end
+
+      def format_path(path)
+        return "root" if path.empty?
+        path.join(".")
+      end
+    end
+  end
+end

data/lib/dexter_llm/schema.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  module Schema
+    # Base class for defining reusable schemas
+    class Base
+      class << self
+        def string(name, **options, &block)
+          schema_definitions << [ :string, name, options, block ]
+        end
+
+        def number(name, **options, &block)
+          schema_definitions << [ :number, name, options, block ]
+        end
+
+        def integer(name, **options, &block)
+          schema_definitions << [ :integer, name, options, block ]
+        end
+
+        def boolean(name, **options, &block)
+          schema_definitions << [ :boolean, name, options, block ]
+        end
+
+        def null(name, **options)
+          schema_definitions << [ :null, name, options, nil ]
+        end
+
+        def object(name, **options, &block)
+          schema_definitions << [ :object, name, options, block ]
+        end
+
+        def array(name, **options, &block)
+          schema_definitions << [ :array, name, options, block ]
+        end
+
+        def any_of(name, **options, &block)
+          schema_definitions << [ :any_of, name, options, block ]
+        end
+
+        def schema_definitions
+          @schema_definitions ||= []
+        end
+
+        def inherited(subclass)
+          super
+          # Copy parent definitions to subclass
+          subclass.instance_variable_set(:@schema_definitions, schema_definitions.dup)
+        end
+      end
+
+      def to_json_schema
+        builder = Builder.new
+
+        self.class.schema_definitions.each do |type, name, options, block|
+          if block
+            builder.send(type, name, **options, &block)
+          else
+            builder.send(type, name, **options)
+          end
+        end
+
+        builder.to_json_schema
+      end
+    end
+  end
+end

data/lib/dexter_llm/session/compaction.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module DexterLlm::Session
+  module Compaction
+    SUMMARIZATION_PROMPT = <<~PROMPT
+      You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+      Include:
+      - Current progress and key decisions made
+      - Important context, constraints, or user preferences
+      - Absolute file paths of any relevant files that were read or modified
+      - What remains to be done (clear next steps)
+      - Any critical data, examples, or references needed to continue
+
+      Be concise, structured, and focused on helping the next LLM seamlessly continue the work.
+    PROMPT
+
+    class CutPointResult
+      attr_reader :first_kept_entry_id, :first_kept_entry_index, :turn_start_index, :is_split_turn
+
+      def initialize(first_kept_entry_id:, first_kept_entry_index:, turn_start_index: -1, is_split_turn: false)
+        @first_kept_entry_id = first_kept_entry_id
+        @first_kept_entry_index = first_kept_entry_index
+        @turn_start_index = turn_start_index
+        @is_split_turn = is_split_turn
+      end
+    end
+
+    class << self
+      def should_compact?(prompt_tokens, context_window, settings)
+        return false unless settings.enabled
+        prompt_tokens > context_window - settings.reserve_tokens
+      end
+
+      def compact(entries:, model:, client:, settings:, signal: nil, custom_instructions: nil)
+        # Don't compact if last entry is already a compaction
+        raise AlreadyCompactedError, "Session was just compacted" if entries.last&.type == :compaction
+
+        # Find previous compaction boundary
+        prev_compaction_idx = entries.rindex { |e| e.type == :compaction } || -1
+        boundary_start = prev_compaction_idx + 1
+        boundary_end = entries.length
+
+        # Get current token count from last assistant message usage
+        last_usage = find_last_assistant_usage(entries)
+        tokens_before = last_usage&.prompt_tokens.to_i
+
+        # Find cut point
+        cut_result = find_cut_point(entries, boundary_start, boundary_end, settings.keep_recent_tokens)
+
+        # Extract messages for summarization (before cut point)
+        history_end = cut_result.is_split_turn ? cut_result.turn_start_index : cut_result.first_kept_entry_index
+        history_messages = entries[boundary_start...history_end]
+          .select { |e| e.type == :message }
+          .map(&:message)
+
+        # Include previous summary if exists
+        if prev_compaction_idx >= 0
+          prev_summary = entries[prev_compaction_idx].summary
+          history_messages.unshift(DexterLlm::UserMessage.new("Previous session summary:\n#{prev_summary}"))
+        end
+
+        # Generate summary via LLM
+        summary = generate_summary(
+          messages: history_messages,
+          model: model,
+          client: client,
+          reserve_tokens: settings.reserve_tokens,
+          signal: signal,
+          custom_instructions: custom_instructions
+        )
+
+        Entry::Compaction.new(
+          summary: summary,
+          first_kept_entry_id: cut_result.first_kept_entry_id,
+          tokens_before: tokens_before
+        )
+      end
+
+      def find_cut_point(entries, start_index, end_index, keep_recent_tokens)
+        # Build list of valid cut points: user, assistant messages (never tool_result)
+        valid_cut_points = []
+        (start_index...end_index).each do |i|
+          entry = entries[i]
+          next unless entry.type == :message
+          role = entry.message.role
+          valid_cut_points << i if [ :user, :assistant ].include?(role)
+        end
+
+        if valid_cut_points.empty?
+          entry = entries[start_index]
+          entry_id = entry.respond_to?(:id) ? entry.id : nil
+          return CutPointResult.new(first_kept_entry_id: entry_id, first_kept_entry_index: start_index)
+        end
+
+        # Walk backwards, accumulating estimated tokens
+        accumulated = 0
+        cut_index = start_index
+
+        (end_index - 1).downto(start_index) do |i|
+          entry = entries[i]
+          next unless entry.type == :message
+
+          accumulated += DexterLlm::TokenEstimator.estimate_message_tokens(entry.message)
+
+          if accumulated >= keep_recent_tokens
+            # Find closest valid cut point at or after this entry
+            cut_index = valid_cut_points.find { |c| c >= i } || cut_index
+            break
+          end
+        end
+
+        # Determine if splitting mid-turn
+        cut_entry = entries[cut_index]
+        cut_entry_id = cut_entry.respond_to?(:id) ? cut_entry.id : nil
+
+        if cut_entry&.type == :message
+          is_user = cut_entry.message.role == :user
+          turn_start = is_user ? -1 : find_turn_start(entries, cut_index, start_index)
+
+          CutPointResult.new(
+            first_kept_entry_id: cut_entry_id,
+            first_kept_entry_index: cut_index,
+            turn_start_index: turn_start,
+            is_split_turn: !is_user && turn_start != -1
+          )
+        else
+          CutPointResult.new(
+            first_kept_entry_id: cut_entry_id,
+            first_kept_entry_index: cut_index
+          )
+        end
+      end
+
+      def estimate_prompt_tokens(messages)
+        DexterLlm::TokenEstimator.estimate_tokens(messages)
+      end
+
+      def calculate_prompt_tokens_from_usage(usage)
+        usage&.prompt_tokens.to_i
+      end
+
+      private
+
+      def find_last_assistant_usage(entries)
+        entries.reverse_each do |entry|
+          if entry.type == :message && entry.message.role == :assistant
+            return entry.message.usage
+          end
+        end
+        nil
+      end
+
+      def find_turn_start(entries, from_index, min_index)
+        # Walk backward to find the user message that started this turn
+        (from_index - 1).downto(min_index) do |i|
+          entry = entries[i]
+          next unless entry.type == :message
+          return i if entry.message.role == :user
+        end
+        -1
+      end
+
+      def generate_summary(messages:, model:, client:, reserve_tokens:, signal: nil, custom_instructions: nil)
+        signal&.throw_if_cancelled!
+
+        max_tokens = (0.8 * reserve_tokens).floor.clamp(1000, 16_000)
+
+        prompt = if custom_instructions
+          "#{SUMMARIZATION_PROMPT}\n\nAdditional focus: #{custom_instructions}"
+        else
+          SUMMARIZATION_PROMPT
+        end
+
+        summarization_messages = limit_messages_for_summary(
+          messages,
+          model: model,
+          reserve_tokens: reserve_tokens
+        ) + [ DexterLlm::UserMessage.new(prompt) ]
+
+        begin
+          response = client.complete(
+            model: model,
+            messages: summarization_messages,
+            max_tokens: max_tokens
+          )
+
+          response.text
+        rescue StandardError => e
+          raise DexterLlm::Session::CompactionError, "Summarization failed: #{e.message}"
+        end
+      end
+
+      def limit_messages_for_summary(messages, model:, reserve_tokens:)
+        context_window = model.respond_to?(:context_window) ? model.context_window : nil
+        return messages if context_window.nil?
+
+        max_prompt_tokens = context_window - reserve_tokens
+        return messages if max_prompt_tokens <= 0
+
+        kept = []
+        total = 0
+
+        messages.reverse_each do |msg|
+          msg_tokens = DexterLlm::TokenEstimator.estimate_message_tokens(msg)
+          break if total + msg_tokens > max_prompt_tokens && !kept.empty?
+
+          kept << msg
+          total += msg_tokens
+        end
+
+        kept.reverse
+      end
+    end
+  end
+end

data/lib/dexter_llm/session/compaction_settings.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module DexterLlm::Session
+  class CompactionSettings
+    attr_reader :enabled, :reserve_tokens, :keep_recent_tokens
+
+    def initialize(
+      enabled: true,
+      reserve_tokens: 16_384,
+      keep_recent_tokens: 20_000
+    )
+      @enabled = enabled
+      @reserve_tokens = reserve_tokens
+      @keep_recent_tokens = keep_recent_tokens
+    end
+  end
+end