generative_ui 0.0.1

data/lib/generative_ui/component_tree_validator.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  class ComponentTreeValidator
+    Result = Data.define(:valid, :errors) do
+      alias_method :valid?, :valid
+    end
+
+    TREE_KEY = '_tree'
+    MAX_COMPONENTS = 500
+    MAX_DEPTH = 64
+    MAX_REFS = 2_000
+
+    def self.call(component_set, catalog:)
+      new(component_set, catalog).call
+    end
+
+    def initialize(component_set, catalog)
+      @component_set = component_set
+      @catalog = catalog
+      @errors = {}
+      @edges = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def call
+      validate_admission_limits
+      return Result.new(valid: false, errors:) if errors.any?
+
+      validate_components
+      validate_structure
+      Result.new(valid: errors.empty?, errors:)
+    end
+
+    private
+
+    attr_reader :component_set, :catalog, :errors, :edges
+
+    def validate_admission_limits
+      tree_error("component limit exceeded (max #{MAX_COMPONENTS})") if component_set.components.size > MAX_COMPONENTS
+    end
+
+    def validate_components
+      component_set.components.each do |component|
+        result = ComponentValidator.call(component, catalog:)
+        result.errors.each { |message| component_error(component.id || '_component', message) } unless result.valid?
+      end
+    end
+
+    def validate_structure
+      component_set.duplicate_ids.each { |id| tree_error("duplicate component id '#{id}'") }
+      return tree_error('root component not found') unless component_set.root
+
+      collect_edges
+      walk_from_root
+      report_orphans
+    end
+
+    def collect_edges
+      @parents = {}
+      @ref_count = 0
+
+      component_set.components.each do |component|
+        definition = catalog.fetch(component.name)
+        next unless definition
+
+        definition.structural_refs.each do |ref|
+          extract_refs(component.attributes, ref.path).each do |field_path, child_id|
+            @ref_count += 1
+            tree_error("reference limit exceeded (max #{MAX_REFS})") if @ref_count == MAX_REFS + 1
+            source = "#{component.id}.#{field_path}"
+            validate_reference(component, ref, source, child_id)
+          end
+        end
+      end
+    end
+
+    def validate_reference(component, ref, source, child_id)
+      target = component_set.by_id[child_id]
+      return relation_error(source, "referenced component '#{child_id}' not found") unless target
+
+      if ref.only.present? && !ref.only.include?(target.name)
+        relation_error(source, "expected #{ref.only.join(' or ')}, got #{target.name}")
+      end
+
+      if (existing_parent = @parents[child_id])
+        tree_error("component '#{child_id}' referenced by both '#{existing_parent}' and '#{source}'")
+      else
+        @parents[child_id] = source
+      end
+
+      edges[component.id] << child_id
+    end
+
+    def extract_refs(value, path, rendered_path = [])
+      return [] if path.empty?
+
+      segment, *rest = path
+      if segment == :*
+        return [] unless value.is_a?(Array)
+
+        return value.each_with_index.flat_map do |item, index|
+          extract_refs(item, rest, rendered_path + [index])
+        end
+      end
+
+      return [] unless value.is_a?(Hash)
+
+      child = value[segment.to_s] || value[segment.to_sym]
+      current_path = rendered_path + [segment]
+
+      if rest.empty?
+        return child.map { |child_id| [format_path(current_path), child_id] } if child.is_a?(Array)
+
+        return child.nil? ? [] : [[format_path(current_path), child]]
+      end
+
+      extract_refs(child, rest, current_path)
+    end
+
+    def walk_from_root
+      @visited = Set.new
+      @in_progress = []
+      walk('root', 1)
+    end
+
+    def walk(id, depth)
+      if depth > MAX_DEPTH
+        tree_error("tree depth limit exceeded (max #{MAX_DEPTH})")
+        return
+      end
+
+      if @in_progress.include?(id)
+        cycle_start = @in_progress.index(id)
+        path = @in_progress[cycle_start..] + [id]
+        tree_error("cycle: #{path.join(' → ')}")
+        return
+      end
+
+      return if @visited.include?(id)
+
+      @in_progress << id
+      edges[id].each { |child_id| walk(child_id, depth + 1) }
+      @in_progress.pop
+      @visited << id
+    end
+
+    def report_orphans
+      (component_set.ids.compact.uniq - @visited.to_a).each do |id|
+        tree_error("orphan component '#{id}'")
+      end
+    end
+
+    def format_path(parts)
+      parts.each_with_object(+'') do |part, rendered|
+        if part.is_a?(Integer)
+          rendered << "[#{part}]"
+        else
+          rendered << '.' unless rendered.empty?
+          rendered << part.to_s
+        end
+      end
+    end
+
+    def tree_error(message)
+      (errors[TREE_KEY] ||= []) << message
+    end
+
+    def component_error(id, message)
+      (errors[id] ||= []) << message
+    end
+
+    def relation_error(path, message)
+      (errors[path] ||= []) << message
+    end
+  end
+end

data/lib/generative_ui/component_validator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json_schemer'
+
+module GenerativeUI
+  class ComponentValidator
+    Result = Data.define(:valid, :errors) do
+      alias_method :valid?, :valid
+    end
+
+    def self.call(component, catalog:)
+      new(component, catalog).call
+    end
+
+    def initialize(component, catalog)
+      @component = component
+      @catalog = catalog
+    end
+
+    def call
+      unless component.name.is_a?(String) && component.name.present?
+        return invalid(['component must be a non-empty string'])
+      end
+      return invalid(["unknown component: #{component.name}"]) unless catalog.fetch(component.name)
+
+      errors = JSONSchemer.schema(schema).validate(component.to_h).flat_map { |error| format_error(error) }
+      Result.new(valid: errors.empty?, errors:)
+    end
+
+    private
+
+    attr_reader :component, :catalog
+
+    def schema
+      JSON.parse(catalog.component_schema(component.name).to_json)
+    end
+
+    def invalid(errors)
+      Result.new(valid: false, errors:)
+    end
+
+    def format_error(error)
+      pointer = error.fetch('data_pointer', '')
+      property = pointer.delete_prefix('/').presence
+      type = error.fetch('type', 'invalid')
+
+      if type == 'required'
+        missing = error.dig('details', 'missing_keys') || []
+        missing.map { |key| "#{[property, key].compact.join('.')} required" }
+      elsif type == 'enum'
+        expected = error.fetch('schema', {}).fetch('enum', [])
+        ["#{property || 'component'} expected one of #{expected.inspect}, got #{error.fetch('data').inspect}"]
+      elsif %w[string number integer boolean array object].include?(type)
+        ["#{property || 'component'} expected #{type}, got #{value_type(error.fetch('data', nil))}"]
+      elsif type == 'schema' && error['schema'] == false
+        ["#{property || 'component'} is not allowed"]
+      else
+        ["#{property || 'component'} #{type}"]
+      end
+    end
+
+    def value_type(value)
+      case value
+      when String then 'string'
+      when Integer then 'integer'
+      when Numeric then 'number'
+      when TrueClass, FalseClass then 'boolean'
+      when Array then 'array'
+      when Hash
+        'object'
+      when NilClass
+        'null'
+      else
+        value.class.name
+      end
+    end
+  end
+end

data/lib/generative_ui/conventions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  module Conventions
+    @rules = {}
+
+    class << self
+      def register(adapter, &block)
+        @rules[adapter.to_sym] = block
+      end
+
+      def fetch(adapter)
+        @rules.fetch(adapter.to_sym) do
+          raise ArgumentError, "No convention registered for adapter: #{adapter.inspect}"
+        end
+      end
+    end
+
+    register(:partial)        { |name| "generative_ui/#{name.underscore}" }
+    register(:view_component) { |name| "GenerativeUI::#{name.camelize}Component" }
+  end
+end

data/lib/generative_ui/engine.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+
+module GenerativeUI
+  class Engine < ::Rails::Engine
+    initializer 'generative_ui.active_support_inflections', before: :load_config_initializers do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym 'UI'
+      end
+    end
+
+    initializer 'generative_ui.inflections', before: :set_autoload_paths do
+      next unless defined?(Rails.autoloaders) && Rails.autoloaders.zeitwerk_enabled?
+
+      Rails.autoloaders.main.inflector.inflect(
+        'generative_ui' => 'GenerativeUI'
+      )
+    end
+
+    initializer 'generative_ui.view_helper' do
+      ActiveSupport.on_load(:action_view) do
+        include GenerativeUI::ViewHelper
+      end
+    end
+  end
+end

data/lib/generative_ui/invalid_component_tree_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  class InvalidComponentTreeError < StandardError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super("Invalid generative UI component tree: #{errors.inspect}")
+    end
+  end
+end

data/lib/generative_ui/renderer.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  class Renderer
+    def initialize(catalog: :default)
+      @catalog_spec = catalog
+    end
+
+    def catalog=(value)
+      @catalog_spec = value
+      @catalog = nil
+    end
+
+    def catalog
+      @catalog ||= Catalog.coerce(@catalog_spec)
+    end
+
+    def call(component_set)
+      render_component_instance(component_set, component_set.root)
+    end
+
+    def render_component_instance(component_set, component)
+      definition = catalog.fetch(component.name)
+      raise ArgumentError, "Unknown generative component: #{component.name}" unless definition
+
+      attributes, additional_properties = materialized_attributes(component_set, component, definition)
+      render_component(definition:, attributes:, additional_properties:)
+    end
+
+    def render_component(definition:, attributes:, additional_properties:)
+      raise NotImplementedError, "#{self.class} must implement #render_component"
+    end
+
+    private
+
+    def materialized_attributes(component_set, component, definition)
+      props = deep_dup(component.attributes)
+      Array(definition&.structural_refs).each do |ref|
+        replace_ref!(props, ref.path) do |child_id|
+          render_component_instance(component_set, component_set.fetch(child_id))
+        end
+      end
+      split_declared_attributes(underscore_string_keys(props), definition)
+    end
+
+    def split_declared_attributes(props, definition)
+      declared_names = declared_attribute_names(definition)
+      attributes = {}
+      additional_properties = {}
+
+      props.each do |key, value|
+        if declared_names.include?(key)
+          attributes[key.to_sym] = deep_symbolize_keys(value)
+        else
+          additional_properties[key] = value
+        end
+      end
+
+      [attributes, additional_properties_enabled?(definition) ? additional_properties : nil]
+    end
+
+    def declared_attribute_names(definition)
+      schema = definition&.attributes_json_schema || {}
+      properties = schema[:properties] || schema['properties'] || {}
+      properties.keys.map { |key| key.to_s.underscore }
+    end
+
+    def additional_properties_enabled?(definition)
+      schema = definition&.attributes_json_schema || {}
+      schema[:additionalProperties] || schema['additionalProperties']
+    end
+
+    def replace_ref!(value, path, &block)
+      return if value.nil?
+
+      segment, *rest = path
+      if segment == :*
+        Array(value).each { |item| replace_ref!(item, rest, &block) }
+        return
+      end
+
+      key = matching_key(value, segment)
+      return unless key
+
+      if rest.empty?
+        child = value[key]
+        value[key] =
+          if child.is_a?(Array)
+            child.map(&block)
+          else
+            block.call(child)
+          end
+      else
+        replace_ref!(value[key], rest, &block)
+      end
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash then value.transform_values { |child| deep_dup(child) }
+      when Array then value.map { |child| deep_dup(child) }
+      else value
+      end
+    end
+
+    def underscore_string_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, child), transformed|
+          normalized = key.is_a?(String) ? key.underscore : key
+          transformed[normalized] = underscore_string_keys(child)
+        end
+      when Array
+        value.map { |child| underscore_string_keys(child) }
+      else
+        value
+      end
+    end
+
+    def matching_key(hash, segment)
+      return unless hash.is_a?(Hash)
+
+      [segment.to_s, segment.to_sym].find { |candidate| hash.key?(candidate) }
+    end
+
+    def deep_symbolize_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, child), transformed|
+          transformed[key.to_sym] = deep_symbolize_keys(child)
+        end
+      when Array
+        value.map { |child| deep_symbolize_keys(child) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/generative_ui/renderers/json.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  module Renderers
+    class Json < Renderer
+      def initialize(catalog: :default, mode: :materialized)
+        super(catalog:)
+        @mode = mode
+      end
+
+      def call(component_set)
+        return { 'components' => component_set.components.map(&:to_h) } if @mode == :flat
+        raise ArgumentError, "Unknown JSON render mode: #{@mode}" unless @mode == :materialized
+
+        super
+      end
+
+      def render_component(definition:, attributes:, additional_properties:)
+        props = attributes.dup
+        props.merge!(additional_properties) if additional_properties
+
+        { 'component' => definition.component, 'props' => props }.deep_stringify_keys
+      end
+    end
+  end
+end

data/lib/generative_ui/renderers/partial.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  module Renderers
+    class Partial < Renderer
+      ADAPTER = :partial
+
+      def initialize(view_context:, catalog: :default)
+        super(catalog:)
+        @view_context = view_context
+      end
+
+      def render_component(definition:, attributes:, additional_properties:)
+        locals = attributes.dup
+        locals[:additional_properties] = additional_properties unless additional_properties.nil?
+
+        @view_context.render(
+          partial: catalog.target_for(definition, ADAPTER),
+          locals:
+        )
+      end
+    end
+  end
+end

data/lib/generative_ui/renderers/view_component.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  module Renderers
+    class ViewComponent < Renderer
+      ADAPTER = :view_component
+
+      def initialize(view_context:, catalog: :default)
+        super(catalog:)
+        @view_context = view_context
+      end
+
+      def render_component(definition:, attributes:, additional_properties:)
+        component_class = resolve(catalog.target_for(definition, ADAPTER))
+        kwargs = attributes.dup
+        kwargs[:additional_properties] = additional_properties unless additional_properties.nil?
+        @view_context.render(component_class.new(**kwargs))
+      end
+
+      private
+
+      def resolve(target)
+        target.is_a?(String) ? target.constantize : target
+      end
+    end
+  end
+end

data/lib/generative_ui/structural_ref.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  StructuralRef = Data.define(
+    :path,
+    :cardinality,
+    :required,
+    :only,
+    :description,
+    :min_items,
+    :max_items
+  )
+end

data/lib/generative_ui/tool.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module GenerativeUI
+  class Tool < RubyLLM::Tool
+    attr_reader :catalog
+
+    def initialize(catalog: :default)
+      @catalog = Catalog.coerce(catalog)
+      raise ArgumentError, 'generative UI catalog is empty' if @catalog.empty?
+    end
+
+    def name
+      'generate_ui'
+    end
+
+    def description
+      <<~TEXT.strip
+        Render inline UI from the available component catalog.
+
+        Call this tool at most once per assistant turn. After it returns
+        {"status":"ok"}, the UI is shown to the user — do not call it again.
+
+        Arguments:
+        - components is a flat array of component instances.
+        - Each component is an object: { "id": "...", "component": "<Name>", ...attributes }
+          where "component" is the literal component name as a string.
+        - One component must have id="root".
+        - ComponentId fields reference one component id.
+        - ComponentIdList fields reference ordered arrays of component ids.
+        - The accepted payload must form one rooted tree.
+
+        Example payload (component names below must be from the catalog;
+        ids are arbitrary labels — suffix them with numbers so they are
+        clearly distinct from component names):
+        {
+          "components": [
+            { "id": "root",    "component": "<CatalogComponent>", ...attributes },
+            { "id": "title-1", "component": "<CatalogComponent>", ...attributes },
+            { "id": "body-1",  "component": "<CatalogComponent>", ...attributes }
+          ]
+        }
+
+        #{catalog.to_prompt}
+      TEXT
+    end
+
+    def params_schema
+      @params_schema ||= JSON.parse(catalog.tool_arguments_schema.to_json)
+    end
+
+    def execute(**args)
+      unknown = args.keys.map(&:to_s) - %w[components]
+      return invalid_arguments("unknown arguments: #{unknown.join(', ')}") if unknown.any?
+
+      components = args[:components]
+      return invalid_arguments('components must be an array') unless components.is_a?(Array)
+
+      set = ComponentSet.from_args(components)
+      validation = ComponentTreeValidator.call(set, catalog:)
+
+      if validation.valid?
+        { status: 'ok' }.to_json
+      else
+        { status: 'invalid', errors: validation.errors }.to_json
+      end
+    end
+
+    private
+
+    def invalid_arguments(message)
+      { status: 'invalid', errors: { '_arguments' => [message] } }.to_json
+    end
+  end
+end

data/lib/generative_ui/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  VERSION = '0.0.1'
+end