dexkit 0.9.0 → 0.11.0

data/lib/dex/query.rb

@@ -3,6 +3,7 @@
 require "active_model"
 
 require_relative "query/backend"
+require_relative "query/export"
 require_relative "query/filtering"
 require_relative "query/sorting"
 
@@ -17,7 +18,11 @@ module Dex
     extend ActiveModel::Naming
     include ActiveModel::Conversion
 
+    extend Registry
+
     class << self
+      include ContextDSL
+
       def scope(&block)
         raise ArgumentError, "scope requires a block." unless block
 
@@ -31,6 +36,14 @@ module Dex
       end
 
       def new(scope: nil, sort: nil, **kwargs)
+        mappings = context_mappings
+        unless mappings.empty?
+          ambient = Dex.context
+          mappings.each do |prop_name, context_key|
+            next if kwargs.key?(prop_name)
+            kwargs[prop_name] = ambient[context_key] if ambient.key?(context_key)
+          end
+        end
         instance = super(**kwargs)
         instance.instance_variable_set(:@_injected_scope, scope)
         sort_str = sort&.to_s
@@ -96,6 +109,30 @@ module Dex
         subclass.instance_variable_set(:@_sort_default, _sort_default) if _sort_default
       end
 
+      # Export
+
+      def to_h
+        Export.build_hash(self)
+      end
+
+      def to_json_schema
+        Export.build_json_schema(self)
+      end
+
+      def export(format: :hash)
+        unless %i[hash json_schema].include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash, :json_schema"
+        end
+
+        sorted = registry.sort_by(&:name)
+        sorted.map do |klass|
+          case format
+          when :hash then klass.to_h
+          when :json_schema then klass.to_json_schema
+          end
+        end
+      end
+
       def from_params(params, scope: nil, **overrides)
         pk = model_name.param_key
         nested = _extract_nested_params(params, pk)
@@ -139,6 +176,10 @@ module Dex
 
       private
 
+      def _context_prop_declared?(name)
+        respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
+      end
+
       def _extract_nested_params(params, pk)
         hash = if params.respond_to?(:to_unsafe_h)
           params.to_unsafe_h

data/lib/dex/test_log.rb

@@ -2,7 +2,18 @@
 
 module Dex
   module TestLog
-    Entry = Data.define(:type, :name, :operation_class, :params, :result, :duration, :caller_location)
+    Entry = Data.define(
+      :type,
+      :name,
+      :operation_class,
+      :params,
+      :result,
+      :duration,
+      :caller_location,
+      :execution_id,
+      :trace_id,
+      :trace
+    )
 
     @_entries = []
     @_mutex = Mutex.new
@@ -42,14 +53,61 @@ module Dex
         return "No operations called." if entries.empty?
 
         lines = ["Operations called (#{entries.size}):"]
-        entries.each_with_index do |entry, i|
+        nodes = entries.each_with_index.map { |entry, index| { entry: entry, index: index } }
+        by_id = nodes.to_h { |node| [node[:entry].execution_id, node] }
+        children = Hash.new { |hash, key| hash[key] = [] }
+        roots = []
+
+        nodes.each do |node|
+          parent_id = _parent_operation_id(node[:entry])
+          if parent_id && by_id[parent_id]
+            children[parent_id] << node
+          else
+            roots << node
+          end
+        end
+
+        counter = 0
+        render = lambda do |node, depth|
+          counter += 1
+          entry = node[:entry]
           status = entry.result.ok? ? "OK" : "ERR(#{entry.result.code})"
           duration_ms = entry.duration ? format("%.1fms", entry.duration * 1000) : "n/a"
-          lines << "  #{i + 1}. #{entry.name} [#{status}] #{duration_ms}"
-          lines << "     params: #{entry.params.inspect}" unless entry.params.nil? || entry.params.empty?
+          indent = "   " * depth
+          id = entry.execution_id ? " (#{_display_id(entry.execution_id)})" : ""
+
+          lines << "  #{indent}#{counter}. #{entry.name}#{id} [#{status}] #{duration_ms}"
+          lines << "  #{indent}   params: #{entry.params.inspect}" unless entry.params.nil? || entry.params.empty?
+
+          children.fetch(entry.execution_id, []).sort_by { |child| child[:index] }.each do |child|
+            render.call(child, depth + 1)
+          end
         end
+
+        roots.sort_by { |node| node[:index] }.each { |node| render.call(node, 0) }
         lines.join("\n")
       end
+
+      private
+
+      def _frame_type(frame)
+        return unless frame
+
+        (frame[:type] || frame["type"])&.to_sym
+      end
+
+      def _display_id(id)
+        prefix, suffix = id.to_s.split("_", 2)
+        return id.to_s unless suffix
+
+        "#{prefix}_#{suffix[0, 7]}"
+      end
+
+      def _parent_operation_id(entry)
+        frames = Array(entry.trace)[0...-1]
+        parent = frames.reverse.find { |frame| _frame_type(frame) == :operation }
+        parent && (parent[:id] || parent["id"])
+      end
     end
   end
 end

data/lib/dex/timeout.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Dex
+  class Timeout < StandardError
+    attr_reader :timeout, :ticket_id, :operation_name
+
+    def initialize(timeout:, ticket_id:, operation_name:)
+      @timeout = timeout.to_f
+      @ticket_id = ticket_id
+      @operation_name = operation_name
+      super("#{operation_name} did not complete within #{@timeout}s (ticket: #{ticket_id})")
+    end
+  end
+end

data/lib/dex/tool.rb

@@ -2,11 +2,22 @@
 
 module Dex
   module Tool
+    QUERY_TOOL_OPTIONS = %i[scope serialize limit only_filters except_filters only_sorts].freeze
+
     module_function
 
-    def from(operation_class)
+    def from(klass, **opts)
       _require_ruby_llm!
-      _build_tool(operation_class)
+
+      if klass < Dex::Query
+        _validate_query_tool_options!(klass, opts)
+        _build_query_tool(klass, **opts)
+      elsif klass < Dex::Operation
+        _reject_unknown_options!(klass, opts)
+        _build_tool(klass)
+      else
+        raise ArgumentError, "expected a Dex::Operation or Dex::Query subclass, got #{klass}"
+      end
     end
 
     def all
@@ -35,7 +46,9 @@ module Dex
         "Dex::Tool requires the ruby-llm gem. Add `gem 'ruby_llm'` to your Gemfile."
     end
 
-    def _build_tool(operation_class) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    # --- Operation tools ---
+
+    def _build_tool(operation_class)
       op = operation_class
       schema = op.contract.to_json_schema
       tool_description = _tool_description(op)
@@ -77,7 +90,374 @@ module Dex
       parts.join("\n")
     end
 
-    def _build_explain_tool # rubocop:disable Metrics/MethodLength
+    def _reject_unknown_options!(_klass, opts)
+      return if opts.empty?
+
+      raise ArgumentError, "#{opts.keys.first}: is not a valid option for Operation tools"
+    end
+
+    # --- Query tools ---
+
+    def _validate_query_tool_options!(klass, opts)
+      unknown = opts.keys - QUERY_TOOL_OPTIONS
+      unless unknown.empty?
+        raise ArgumentError, "unknown option#{"s" if unknown.size > 1}: #{unknown.map { |k| "#{k}:" }.join(", ")}"
+      end
+
+      label = klass.name || klass.inspect
+
+      unless opts.key?(:scope)
+        raise ArgumentError, "#{label} is a Dex::Query. Query tools require scope: and serialize:.\n" \
+          "Example: Dex::Tool.from(#{label},\n" \
+          "  scope: -> { Current.user.orders },\n" \
+          "  serialize: ->(record) { record.as_json(only: [:id, :name]) })"
+      end
+
+      unless opts.key?(:serialize)
+        raise ArgumentError, "#{label} is a Dex::Query. Query tools require serialize:.\n" \
+          "Example: Dex::Tool.from(#{label},\n" \
+          "  scope: -> { Current.user.orders },\n" \
+          "  serialize: ->(record) { record.as_json(only: [:id, :name]) })"
+      end
+
+      unless klass._scope_block
+        raise ArgumentError, "#{label} has no scope block. Define scope { ... } in the query class."
+      end
+
+      unless opts[:scope].respond_to?(:call)
+        raise ArgumentError, "scope: must respond to call (lambda or proc)"
+      end
+
+      unless opts[:serialize].respond_to?(:call)
+        raise ArgumentError, "serialize: must respond to call (lambda or proc)"
+      end
+
+      if opts.key?(:limit)
+        unless opts[:limit].is_a?(Integer) && opts[:limit] > 0
+          raise ArgumentError, "limit: must be a positive integer"
+        end
+      end
+
+      if opts.key?(:only_filters) && opts.key?(:except_filters)
+        raise ArgumentError, "only_filters: and except_filters: are mutually exclusive"
+      end
+
+      declared_filters = klass.filters
+      if opts.key?(:only_filters)
+        context_mapped = klass.context_mappings.keys.to_set
+        opts[:only_filters].each do |f|
+          f_sym = f.to_sym
+          unless declared_filters.include?(f_sym)
+            raise ArgumentError, "unknown filter :#{f}. Declared: #{declared_filters.inspect}"
+          end
+
+          if context_mapped.include?(f_sym)
+            raise ArgumentError, "filter :#{f} is context-mapped and automatically excluded from " \
+              "tool schema. Remove it from only_filters:"
+          end
+
+          prop = klass.literal_properties.find { |p| p.name == f_sym }
+          if prop && _ref_type?(prop.type)
+            raise ArgumentError, "filter :#{f} backs a _Ref prop and is automatically excluded from " \
+              "tool schema. Remove it from only_filters:"
+          end
+        end
+      end
+
+      if opts.key?(:except_filters)
+        opts[:except_filters].each do |f|
+          unless declared_filters.include?(f.to_sym)
+            raise ArgumentError, "unknown filter :#{f} in except_filters. Declared: #{declared_filters.inspect}"
+          end
+        end
+      end
+
+      declared_sorts = klass.sorts
+      if opts.key?(:only_sorts)
+        opts[:only_sorts].each do |s|
+          unless declared_sorts.include?(s.to_sym)
+            raise ArgumentError, "unknown sort :#{s}. Declared: #{declared_sorts.inspect}"
+          end
+        end
+
+        default_sort = klass._sort_default
+        if default_sort
+          bare = default_sort.delete_prefix("-").to_sym
+          unless opts[:only_sorts].map(&:to_sym).include?(bare)
+            raise ArgumentError, "query default sort #{default_sort} is not in only_sorts. " \
+              "Include it or change the query's default"
+          end
+        end
+      end
+
+      if klass.respond_to?(:literal_properties)
+        klass.literal_properties.each do |prop|
+          if %i[limit offset].include?(prop.name)
+            raise ArgumentError, "#{label} declares prop :#{prop.name} which conflicts with " \
+              "the tool's pagination parameter. Rename the prop"
+          end
+        end
+      end
+
+      _validate_satisfiable_props!(klass, opts)
+    end
+
+    def _validate_satisfiable_props!(klass, opts)
+      return unless klass.respond_to?(:literal_properties)
+
+      context_keys = klass.context_mappings.keys.to_set
+      visible = _compute_visible_filters(klass, opts[:only_filters], opts[:except_filters])
+      excluded = _query_excluded_prop_names(klass, visible)
+
+      klass.literal_properties.each do |prop|
+        next unless excluded.include?(prop.name)
+        next unless prop.required?
+        next if context_keys.include?(prop.name)
+
+        if _ref_type?(prop.type)
+          raise ArgumentError, "prop :#{prop.name} (_Ref) is auto-excluded from the tool schema " \
+            "but is required with no default and no context mapping — the tool could never execute"
+        else
+          raise ArgumentError, "excluding filter :#{prop.name} hides required prop :#{prop.name} " \
+            "which has no default and no context mapping — the tool could never execute"
+        end
+      end
+    end
+
+    def _build_query_tool(klass, scope:, serialize:, limit: 50, only_filters: nil, except_filters: nil, only_sorts: nil)
+      max_limit = limit
+      scope_lambda = scope
+      serialize_lambda = serialize
+
+      visible_filters = _compute_visible_filters(klass, only_filters, except_filters)
+      allowed_sorts = only_sorts ? only_sorts.map(&:to_sym) : klass.sorts
+
+      schema = _query_params_schema(klass, visible_filters, allowed_sorts, max_limit)
+      tool_desc = _query_tool_description(klass, visible_filters, allowed_sorts, max_limit)
+      tool_name = "dex_query_#{(klass.name || "query").gsub("::", "_").downcase}"
+
+      stripped_param_keys = klass.context_mappings.keys.to_set
+      invisible_filters = klass.filters.to_set - visible_filters.to_set
+      stripped_param_keys.merge(invisible_filters)
+
+      query_class = klass
+
+      Class.new(RubyLLM::Tool) do
+        define_method(:name) { tool_name }
+        define_method(:description) { tool_desc }
+        define_method(:params_schema) { schema }
+
+        define_method(:execute) do |**params|
+          params = params.transform_keys(&:to_sym)
+
+          req_limit = [(params.delete(:limit) || max_limit).to_i, max_limit].min
+          req_limit = max_limit if req_limit <= 0
+          req_offset = [params.delete(:offset).to_i, 0].max
+
+          sort_value = params.delete(:sort)&.to_s
+          if sort_value && !sort_value.empty?
+            bare = sort_value.delete_prefix("-").to_sym
+            valid = allowed_sorts.include?(bare)
+            if valid && sort_value.start_with?("-")
+              sort_def = query_class._sort_registry[bare]
+              valid = false if sort_def&.custom
+            end
+            sort_value = nil unless valid
+          else
+            sort_value = nil
+          end
+
+          stripped_param_keys.each { |k| params.delete(k) }
+
+          injected_scope = scope_lambda.call
+
+          overrides = {}
+          overrides[:sort] = sort_value if sort_value
+          query = query_class.from_params(params, scope: injected_scope, **overrides)
+
+          records = query.resolve
+
+          total = begin
+            result = records.count
+            result.is_a?(Integer) ? result : nil
+          rescue
+            nil
+          end
+
+          records = records.offset(req_offset).limit(req_limit)
+
+          serialized = records.map { |r| serialize_lambda.call(r) }
+
+          { records: serialized, total: total, limit: req_limit, offset: req_offset }
+        rescue ArgumentError, Literal::TypeError => e
+          { error: "invalid_params", message: e.message }
+        rescue => e
+          { error: "query_failed", message: e.message }
+        end
+      end.new
+    end
+
+    def _query_tool_description(klass, visible_filters, allowed_sorts, max_limit)
+      parts = []
+      text = klass.description || klass.name || "Query"
+      parts << (text.end_with?(".") ? text : "#{text}.")
+
+      if visible_filters.any?
+        filter_descs = visible_filters.map { |f| _query_filter_desc(klass, f) }
+        parts << "Filters: #{filter_descs.join(", ")}."
+      end
+
+      if allowed_sorts.any?
+        default_sort = klass._sort_default
+        sort_descs = allowed_sorts.map do |s|
+          bare_default = default_sort&.delete_prefix("-")
+          if bare_default && bare_default.to_sym == s
+            "#{s} (default: #{default_sort})"
+          else
+            s.to_s
+          end
+        end
+        parts << "Sorts: #{sort_descs.join(", ")}."
+      end
+
+      parts << "Returns up to #{max_limit} results per page. Use offset to paginate."
+
+      parts.join("\n")
+    end
+
+    def _query_filter_desc(klass, filter_name)
+      descs = klass.respond_to?(:prop_descriptions) ? klass.prop_descriptions : {}
+      prop_desc = descs[filter_name]
+
+      prop = klass.literal_properties.find { |p| p.name == filter_name }
+      return filter_name.to_s unless prop
+
+      inner_type = prop.type
+      inner_type = inner_type.type if inner_type.is_a?(Literal::Types::NilableType)
+
+      if inner_type.respond_to?(:primitives) && inner_type.primitives&.any?
+        values = inner_type.primitives.to_a.map(&:to_s)
+        "#{filter_name} (#{_join_with_or(values)})"
+      elsif prop_desc
+        "#{filter_name} (#{prop_desc})"
+      else
+        filter_name.to_s
+      end
+    end
+
+    def _join_with_or(values)
+      case values.size
+      when 1 then values.first
+      when 2 then "#{values.first} or #{values.last}"
+      else "#{values[..-2].join(", ")}, or #{values.last}"
+      end
+    end
+
+    def _query_params_schema(klass, visible_filters, allowed_sorts, max_limit)
+      properties = {}
+      required = []
+
+      excluded = _query_excluded_prop_names(klass, visible_filters)
+      descs = klass.respond_to?(:prop_descriptions) ? klass.prop_descriptions : {}
+
+      if klass.respond_to?(:literal_properties)
+        klass.literal_properties.each do |prop|
+          next if excluded.include?(prop.name)
+
+          prop_desc = descs[prop.name]
+          schema = TypeSerializer.to_json_schema(prop.type, desc: prop_desc)
+          properties[prop.name.to_s] = schema
+          required << prop.name.to_s if prop.required?
+        end
+      end
+
+      if allowed_sorts.any?
+        sort_values = []
+        allowed_sorts.each do |s|
+          sort_def = klass._sort_registry[s]
+          sort_values << s.to_s
+          sort_values << "-#{s}" unless sort_def.custom
+        end
+
+        default_sort = klass._sort_default
+        sort_desc = "Sort order. Prefix with - for descending."
+        sort_desc += " Default: #{default_sort}" if default_sort
+
+        properties["sort"] = {
+          type: "string",
+          enum: sort_values,
+          description: sort_desc
+        }
+      end
+
+      properties["limit"] = {
+        type: "integer",
+        description: "Maximum number of results (default: #{max_limit}, max: #{max_limit})"
+      }
+      properties["offset"] = {
+        type: "integer",
+        description: "Number of results to skip (default: 0)"
+      }
+
+      result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+      result[:type] = "object"
+      result[:properties] = properties
+      result[:required] = required unless required.empty?
+      result[:additionalProperties] = false
+      result
+    end
+
+    def _compute_visible_filters(klass, only_filters, except_filters)
+      context_keys = klass.context_mappings.keys.to_set
+
+      filters = klass.filters.dup
+      filters.reject! { |f| context_keys.include?(f) }
+      filters.reject! do |f|
+        prop = klass.literal_properties.find { |p| p.name == f }
+        prop && _ref_type?(prop.type)
+      end
+
+      if only_filters
+        only_set = only_filters.map(&:to_sym).to_set
+        filters.select! { |f| only_set.include?(f) }
+      elsif except_filters
+        except_set = except_filters.map(&:to_sym).to_set
+        filters.reject! { |f| except_set.include?(f) }
+      end
+
+      filters
+    end
+
+    def _query_excluded_prop_names(klass, visible_filters)
+      return Set.new unless klass.respond_to?(:literal_properties)
+
+      context_keys = klass.context_mappings.keys.to_set
+      visible_set = visible_filters.to_set
+      all_filters = klass.filters.to_set
+
+      excluded = Set.new
+      excluded.merge(context_keys)
+
+      klass.literal_properties.each do |prop|
+        excluded << prop.name if _ref_type?(prop.type)
+      end
+
+      invisible_filters = all_filters - visible_set
+      excluded.merge(invisible_filters)
+
+      excluded
+    end
+
+    def _ref_type?(type)
+      return true if type.is_a?(Dex::RefType)
+      return _ref_type?(type.type) if type.respond_to?(:type)
+
+      false
+    end
+
+    # --- Explain tool ---
+
+    def _build_explain_tool
       Class.new(RubyLLM::Tool) do
         define_method(:name) { "dex_explain" }
         define_method(:description) { "Check if an operation can be executed with given params, without running it." }
@@ -110,6 +490,9 @@ module Dex
       end.new
     end
 
-    private_class_method :_require_ruby_llm!, :_build_tool, :_tool_description, :_build_explain_tool
+    private_class_method :_require_ruby_llm!, :_build_tool, :_tool_description, :_build_explain_tool,
+      :_reject_unknown_options!, :_validate_query_tool_options!, :_validate_satisfiable_props!,
+      :_build_query_tool, :_query_tool_description, :_query_filter_desc, :_join_with_or,
+      :_query_params_schema, :_compute_visible_filters, :_query_excluded_prop_names, :_ref_type?
   end
 end