generative_ui 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df2a6ce2fc73069777780c94ee27b0b5a42d547967e3fc2a10c71b000c8b8dfa
+  data.tar.gz: fc79d3abe16ad49b5cca16d3afe605ec9dd324a88d212ae497c90f602452373b
+SHA512:
+  metadata.gz: e8d303d2d70e8e2bee59e84cbe7e512494233361a347c4e938550f21ddae1e6937c4e60cba11a3a9358388d7751f315388f074d4656c2a4309e75972918db988
+  data.tar.gz: c5b6c4c975352d732b1f91696f4f3f65677bbc9654e3e6ce39c0aa071044e36b4d3deacb9fc28e8ed9c2ca43417fd662b15d9b25505b219a3b306f300ca1d43a

data/LICENSE.txt

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2026 Andrey Samsonov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

data/README.md

@@ -0,0 +1,370 @@
+# GenerativeUI
+
+GenerativeUI lets RubyLLM apps render model-generated UI from a declared component catalog. The wire shape is inspired by A2UI: the model emits a validated component tree, and your app renders it with Rails partials, ViewComponent, JSON, or a custom renderer.
+
+> Disclaimer: GenerativeUI is currently experimental and under active development. Its APIs, behavior, and integration patterns may change without notice, and it is not recommended for production use yet.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "generative_ui"
+```
+
+## Quick start
+
+Create `app/models/application_generative_catalog.rb`:
+
+```ruby
+class ApplicationGenerativeCatalog < GenerativeUI::Catalog
+  component "Text" do
+    desc "Render plain text."
+    attributes { string :text }
+  end
+
+  component "Card" do
+    desc "Group a title with generated body content."
+    attributes do
+      one_component :title, only: "Text"
+      many_components :children, only: "Text"
+    end
+  end
+end
+```
+
+Component attributes use `RubyLLM::Schema`. Structural refs use `one_component` for one child id and `many_components` for ordered child ids.
+
+Register the default catalog explicitly:
+
+```ruby
+# config/initializers/generative_ui.rb
+GenerativeUI.configure do |config|
+  config.catalog :default, "ApplicationGenerativeCatalog"
+end
+```
+
+Use a string in the initializer so Rails can autoload/reload the catalog class normally.
+
+The default `:partial` renderer maps component names to partials. For this quick start, create the two partials used by the catalog above:
+
+```erb
+<%# app/views/generative_ui/_card.html.erb %>
+<%# locals: (title:, children:) %>
+<section style="border:2px solid #7c3aed;border-radius:16px;padding:16px;background:#faf5ff">
+  <header style="font-size:22px;font-weight:700;color:#5b21b6"><%= title %></header>
+  <% children.each do |child| %>
+    <div style="margin-top:10px"><%= child %></div>
+  <% end %>
+</section>
+```
+
+```erb
+<%# app/views/generative_ui/_text.html.erb %>
+<%# locals: (text:) %>
+<p style="margin:0;color:#111827;line-height:1.45"><%= text %></p>
+```
+
+Give a RubyLLM Rails chat a catalog-bound generate-UI tool. This assumes RubyLLM's Rails chat UI is installed:
+
+```bash
+bin/rails generate ruby_llm:install
+bin/rails db:migrate
+bin/rails generate ruby_llm:chat_ui
+```
+
+```ruby
+tool = GenerativeUI::Tool.new
+
+chat = Chat.create!
+chat.with_instructions(<<~PROMPT)
+  Tool guidance:
+  - Use generate_ui for responses that should be rendered as UI from the available components.
+  - IMPORTANT: after calling generate_ui, do not add a final text answer.
+    The tool call itself is the user-visible UI response.
+PROMPT
+chat.with_tool(tool)
+
+chat.ask("What programming language was designed to make developers happy and also turned out to be especially token-efficient for LLMs? Name its iconic web framework too, and present the answer as a titled card with one short explanation.")
+```
+
+`GenerativeUI::Tool.new` and `render_generative_ui` use the configured `:default` catalog unless you pass `catalog:`.
+
+The `Tool guidance` section tells the model **when** to use the tool and that the tool call is the user-visible answer. The tool description itself tells the model **how** to construct valid arguments from the selected catalog.
+
+Render the chat transcript:
+
+```erb
+<%= render @chat.messages %>
+```
+
+The gem ships two Rails chat partials for RubyLLM's default message views:
+
+```text
+app/views/messages/tool_calls/_generate_ui.html.erb
+app/views/messages/tool_results/_generate_ui.html.erb
+```
+
+The shipped tool-call partial renders valid `generate_ui` calls. The tool-result partial is empty so validation status payloads stay out of the transcript.
+
+The partial hides only `InvalidComponentTreeError`; configuration and rendering errors still raise.
+
+**Catalog identity in Rails.** Persisted tool-call arguments do not store catalog identity. If you use named catalogs, build the tool and render with the same catalog:
+
+```ruby
+tool = GenerativeUI::Tool.new(catalog: :support)
+chat.with_tool(tool)
+```
+
+```erb
+<%# app/views/messages/tool_calls/_generate_ui.html.erb %>
+<% begin %>
+  <%= render_generative_ui tool_call.arguments, catalog: :support %>
+<% rescue GenerativeUI::InvalidComponentTreeError %>
+<% end %>
+```
+
+If one transcript can contain UI calls from different catalogs, use a shared render catalog or route catalogs in your overridden partial.
+
+Renderers receive materialized Ruby attributes: declared fields are `snake_case`, `one_component` refs become one rendered fragment, and `many_components` refs become arrays.
+
+## How it works
+
+The gem is built around the bundled [`GenerativeUI::Tool`](lib/generative_ui/tool.rb). It uses a tool call as the transport for the generated UI tree. The call arguments contain the full payload: component names, declared attributes, and structural references between components.
+
+```json
+{
+  "components": [
+    { "id": "root", "component": "Card", "title": "title-1", "children": ["body-1"] },
+    { "id": "title-1", "component": "Text", "text": "Ruby and Ruby on Rails" },
+    { "id": "body-1", "component": "Text", "text": "Ruby was designed to make developers happy, and Rails became its iconic web framework." }
+  ]
+}
+```
+
+JSON Schema constrains each component's attributes. Runtime validation handles tree rules that schema cannot express: root, refs, cycles, reachability, and `only:` targets.
+
+The tool returns only validation status, not rendered UI:
+
+```json
+{ "status": "ok" }
+```
+
+or:
+
+```json
+{ "status": "invalid", "errors": { "...": ["..."] } }
+```
+
+Each component declaration contributes one component to the catalog. It declares the component name, its model-facing description, its attribute schema, structural references to other components, and optional render-target metadata. The selected catalog is then compiled into both tool guidance and the provider-facing schema for `GenerativeUI::Tool`.
+
+## Plain RubyLLM
+
+Rails chat views are just one integration path. Plain RubyLLM uses the same catalog and tool; capture the `generate_ui` call and render its arguments yourself:
+
+```ruby
+tool = GenerativeUI::Tool.new(catalog: MyCatalog)
+ui_call = nil
+
+chat = RubyLLM.chat
+  .with_instructions(<<~PROMPT)
+    Tool guidance:
+    - Use generate_ui for responses that should be rendered as UI from the available components.
+    - IMPORTANT: after calling generate_ui, do not add a final text answer.
+      The tool call itself is the user-visible UI response.
+  PROMPT
+  .with_tools(tool)
+  .before_tool_call do |call|
+    ui_call = call if call.name == "generate_ui"
+  end
+
+chat.ask("What programming language was designed to make developers happy and also turned out to be especially token-efficient for LLMs? Name its iconic web framework too, and present the answer as a titled card with one short explanation.")
+
+GenerativeUI.render(ui_call.arguments, catalog: MyCatalog, renderer: :json)
+# => {
+#      "component" => "Card",
+#      "props" => {
+#        "title" => { "component" => "Text", "props" => { "text" => "Ruby and Ruby on Rails" } },
+#        "children" => [
+#          {
+#            "component" => "Text",
+#            "props" => {
+#              "text" => "Ruby was created to make developers happy, and its concise style is often very token-efficient; its iconic framework is Ruby on Rails."
+#            }
+#          }
+#        ]
+#      }
+#    }
+```
+
+`Renderers::Json` returns nested JSON by default; pass a renderer instance for options such as `mode: :flat`:
+
+```ruby
+renderer = GenerativeUI::Renderers::Json.new(mode: :flat)
+GenerativeUI.render(ui_call.arguments, catalog: MyCatalog, renderer:)
+```
+
+## Named catalogs
+
+```ruby
+class SupportCatalog < GenerativeUI::Catalog
+  component "TicketSummary" do
+    attributes { string :summary }
+  end
+end
+
+GenerativeUI.configure do |config|
+  config.catalog :support, SupportCatalog
+end
+```
+
+Pass the registered name where the default would go:
+
+```ruby
+GenerativeUI::Tool.new(catalog: :support)
+render_generative_ui(args, catalog: :support)
+```
+
+Prefer `snake_case` in the Ruby DSL. Tool schemas and payloads use `camelCase`; unsafe acronym forms such as `imageURL` are rejected.
+
+```ruby
+attributes do
+  array :tab_items do
+    object do
+      string :display_name
+    end
+  end
+end
+```
+
+```json
+{
+  "tabItems": [
+    { "displayName": "..." }
+  ]
+}
+```
+
+Structural references can also appear inside nested value schemas:
+
+```ruby
+attributes do
+  array :tab_items do
+    object do
+      string :title
+      one_component :content
+    end
+  end
+end
+```
+
+**Subclassing.** Catalog declarations are per class; subclasses do not inherit components. Share declarations with a module if needed:
+
+```ruby
+module SharedComponents
+  def self.included(base)
+    base.component("Text") { attributes { string :text } }
+  end
+end
+
+class ChatCatalog < GenerativeUI::Catalog
+  include SharedComponents
+  component("ChatBubble") { attributes { string :text } }
+end
+```
+
+## `present_with` and the resolution chain
+
+`present_with` binds a component to a render target at two scopes:
+
+1. **Per-component override** — `present_with :adapter, target` inside a `component` block.
+2. **Catalog-wide default** — `present_with :adapter do |name| … end` at the catalog class level. The block receives the component name and returns the target.
+3. **Built-in `Conventions`** — gem fallback, used when neither scope above provides a target.
+
+Built-in fallbacks:
+
+| Adapter           | Fallback                                                                 |
+|-------------------|--------------------------------------------------------------------------|
+| `:partial`        | `"generative_ui/#{name.underscore}"` (e.g. `"generative_ui/card"`)       |
+| `:view_component` | `"GenerativeUI::#{name.camelize}Component"` → `constantize` to the class |
+| `:json`           | No target — JSON renderer serializes the component tree directly         |
+
+Use `present_with` to redirect individual components or to set a catalog-wide convention that differs from the gem default:
+
+```ruby
+class ApplicationGenerativeCatalog < GenerativeUI::Catalog
+  present_with :partial do |name|
+    "components/#{name.underscore}"
+  end
+
+  component "Text" do
+    desc "Render plain text."
+    attributes { string :text }
+    present_with :partial, "shared/widgets/text"
+  end
+end
+```
+
+Apps using ViewComponent declare bindings for the `:view_component` adapter instead — same DSL, different target type:
+
+```ruby
+component "Card" do
+  attributes { ... }
+  present_with :view_component, CardComponent
+end
+```
+
+With the ViewComponent renderer, declared attributes and materialized refs arrive as keyword arguments:
+
+```ruby
+class GenerativeUI::CardComponent < ViewComponent::Base
+  def initialize(title:, children:)
+    @title = title
+    @children = children
+  end
+end
+```
+
+## Validation model
+
+Provider-facing schemas guide generation; runtime validation decides what the application accepts.
+
+For a complete tool call, accepted components must form exactly one rooted tree:
+
+- one component has `id: "root"`;
+- ids are unique;
+- every structural reference resolves;
+- every component is reachable from `root`;
+- cycles and shared children are rejected;
+- `only:` constraints match the referenced component types.
+
+`id` syntax is otherwise unconstrained in v1.
+
+## Renderers
+
+The gem ships with:
+
+- `GenerativeUI::Renderers::Partial`
+- `GenerativeUI::Renderers::ViewComponent`
+- `GenerativeUI::Renderers::Json`
+
+Register a custom renderer when your app uses another rendering system. The factory receives `view_context` and returns an object responding to `call(component_set)`:
+
+```ruby
+GenerativeUI.configure do |config|
+  config.register_renderer(:phlex) do |view_context|
+    PhlexRenderer.new(view_context:)
+  end
+
+  config.default_renderer = :phlex
+end
+```
+
+Then choose it per call if needed:
+
+```erb
+<%= render_generative_ui tool_call.arguments, catalog: :support, renderer: :phlex %>
+```
+
+## License
+
+MIT.

data/app/helpers/generative_ui/view_helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  module ViewHelper
+    def render_generative_ui(arguments, catalog: :default, renderer: nil)
+      renderer ||= GenerativeUI.configuration.default_renderer
+      GenerativeUI.render(arguments, catalog:, renderer:, view_context: self)
+    end
+  end
+end

data/app/views/messages/tool_calls/_generate_ui.html.erb

@@ -0,0 +1,6 @@
+<% begin %>
+  <%= render_generative_ui tool_call.arguments, catalog: :default %>
+<% rescue GenerativeUI::InvalidComponentTreeError => e %>
+  <%# Invalid attempts stay hidden; subscribe to the notification below to log/report them. %>
+  <% ActiveSupport::Notifications.instrument('invalid_tree.generative_ui', error: e, tool_call: tool_call) %>
+<% end %>

data/app/views/messages/tool_results/_generate_ui.html.erb

@@ -0,0 +1 @@
+<%# GenerativeUI::Tool results are control messages for the model, not user-visible transcript content. %>

data/generative_ui.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/generative_ui/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "generative_ui"
+  spec.version       = GenerativeUI::VERSION
+  spec.authors       = [ "Andrey Samsonov" ]
+  spec.email         = [ "me@samsonov.io" ]
+
+  spec.summary       = "Catalog-driven generative UI for RubyLLM and Rails"
+  spec.description   = "Define a safe component catalog, expose it as a RubyLLM tool schema, validate model-generated component trees, and render them with Rails partials, ViewComponent, or JSON."
+  spec.homepage      = "https://github.com/kryzhovnik/generative_ui"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir[
+    "lib/**/*",
+    "app/**/*",
+    "README.md",
+    "LICENSE*",
+    "generative_ui.gemspec"
+  ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_dependency "activesupport", ">= 7.0"
+  spec.add_dependency "ruby_llm",      "~> 1.15"
+  spec.add_dependency "json_schemer",  "~> 2.5"
+end

data/lib/generative_ui/attributes.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module GenerativeUI
+  class Attributes
+    METADATA_KEY = :_generative_ui_structural_ref
+
+    module StructuralDsl
+      def one_component(name, description: nil, required: true, only: nil)
+        add_property(
+          name,
+          {
+            type: 'string',
+            description: description,
+            Attributes::METADATA_KEY => {
+              cardinality: :one,
+              only: Attributes.normalize_only(only)
+            }
+          }.compact,
+          required: required
+        )
+      end
+
+      def many_components(name, description: nil, required: true, only: nil, min_items: nil, max_items: nil)
+        add_property(
+          name,
+          {
+            type: 'array',
+            items: { type: 'string' },
+            description: description,
+            minItems: min_items,
+            maxItems: max_items,
+            Attributes::METADATA_KEY => {
+              cardinality: :many,
+              only: Attributes.normalize_only(only)
+            }
+          }.compact,
+          required: required
+        )
+      end
+    end
+
+    module LocalSchemaBuilders
+      def object_schema(description: nil, of: nil, &block)
+        return determine_object_reference(of, description) if of
+
+        sub_schema = Class.new(self)
+        result = sub_schema.class_eval(&block)
+
+        if result.is_a?(Hash) && result['$ref'] && sub_schema.properties.empty?
+          result.merge(description ? { description: description } : {})
+        elsif schema_class?(result) && sub_schema.properties.empty?
+          schema_class_to_inline_schema(result).merge(description ? { description: description } : {})
+        else
+          {
+            type: 'object',
+            properties: sub_schema.properties,
+            required: sub_schema.required_properties,
+            additionalProperties: sub_schema.additional_properties,
+            description: description
+          }.compact
+        end
+      end
+    end
+
+    class Schema < RubyLLM::Schema
+      extend StructuralDsl
+      extend LocalSchemaBuilders
+
+      class << self
+        def create(&block)
+          Class.new(self).tap { |schema_class| schema_class.class_eval(&block) }
+        end
+      end
+    end
+
+    class << self
+      def build(&block)
+        schema_class = Schema.create(&block)
+        new(schema_class)
+      end
+
+      def normalize_only(value)
+        return nil if value.nil?
+
+        Array(value).map(&:to_s)
+      end
+    end
+
+    attr_reader :schema_class
+
+    def initialize(schema_class)
+      @schema_class = schema_class
+    end
+
+    def json_schema
+      @json_schema ||= camelize_schema(schema_class.new.to_json_schema.fetch(:schema))
+    end
+
+    def structural_refs
+      @structural_refs ||= extract_structural_refs(json_schema)
+    end
+
+    private
+
+    def camelize_schema(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, child), transformed|
+          transformed[key] = case key.to_sym
+                             when :properties
+                               child.each_with_object({}) do |(property, schema), properties|
+                                 properties[camelize_name(property)] = camelize_schema(schema)
+                               end
+                             when :required
+                               child.map { |name| camelize_name(name) }
+                             else
+                               camelize_schema(child)
+                             end
+        end
+      when Array
+        value.map { |child| camelize_schema(child) }
+      else
+        value
+      end
+    end
+
+    def camelize_name(name)
+      name.to_s.camelize(:lower).to_sym
+    end
+
+    def extract_structural_refs(schema)
+      refs = []
+      walk_schema(schema, [], refs)
+      refs
+    end
+
+    def walk_schema(schema, path, refs)
+      return unless schema.is_a?(Hash)
+
+      if (metadata = schema[METADATA_KEY])
+        refs << StructuralRef.new(
+          path: path,
+          cardinality: metadata.fetch(:cardinality),
+          required: required_path?(path),
+          only: metadata[:only],
+          description: schema[:description] || schema['description'],
+          min_items: schema[:minItems] || schema['minItems'],
+          max_items: schema[:maxItems] || schema['maxItems']
+        )
+      end
+
+      properties = schema[:properties] || schema['properties'] || {}
+      properties.each do |name, child|
+        walk_schema(child, path + [name.to_sym], refs)
+      end
+
+      items = schema[:items] || schema['items']
+      walk_schema(items, path + [:*], refs) if items
+
+      Array(schema[:oneOf] || schema['oneOf']).each { |child| walk_schema(child, path, refs) }
+      Array(schema[:anyOf] || schema['anyOf']).each { |child| walk_schema(child, path, refs) }
+    end
+
+    def required_path?(path)
+      current = json_schema
+
+      path.each do |segment|
+        if segment == :*
+          current = current[:items] || current['items']
+          next
+        end
+
+        required = current[:required] || current['required'] || []
+        return false unless required.map(&:to_sym).include?(segment)
+
+        current = (current[:properties] || current['properties']).fetch(segment)
+      end
+
+      true
+    end
+  end
+end