ag-ui 0.1.0

data/data/generate-ag-ui-schema.py

@@ -0,0 +1,50 @@
+# Generates data/ag_ui.json from the reference Python SDK's pydantic models
+# (clone github.com/ag-ui-protocol/ag-ui and point AG_UI_SDK at sdks/python).
+#
+# Run: uv run --with pydantic data/generate-ag-ui-schema.py [/path/to/ag-ui/sdks/python]
+#
+# Output shape mirrors a2a's data/a2a.json: a single top-level "definitions"
+# map keyed by model class name, refs rewritten to #/definitions/<Model>.
+# Wire keys are camelCase (by_alias), matching @ag-ui/core exactly.
+
+import inspect
+import json
+import os
+import sys
+
+sdk = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("AG_UI_SDK", "/tmp/ag-ui/sdks/python")
+sys.path.insert(0, sdk)
+
+from pydantic import BaseModel  # noqa: E402
+from pydantic.json_schema import models_json_schema  # noqa: E402
+
+from ag_ui.core import capabilities, events, types  # noqa: E402
+
+models = []
+for mod in (types, events, capabilities):
+    for _name, obj in sorted(vars(mod).items()):
+        if (
+            inspect.isclass(obj)
+            and issubclass(obj, BaseModel)
+            and obj.__module__ == mod.__name__
+            and obj.__name__ != "ConfiguredBaseModel"
+        ):
+            models.append(obj)
+
+_, top = models_json_schema(
+    [(m, "validation") for m in models],
+    by_alias=True,
+    ref_template="#/definitions/{model}",
+)
+
+out = {
+    "$comment": f"Generated by data/generate-ag-ui-schema.py from ag-ui sdks/python ({len(models)} models). Do not edit.",
+    "definitions": top["$defs"],
+}
+
+dest = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ag_ui.json")
+with open(dest, "w") as f:
+    json.dump(out, f, indent=2, sort_keys=True)
+    f.write("\n")
+
+print(f"wrote {dest}: {len(out['definitions'])} definitions")

data/lib/ag_ui/a2ui/catalog.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "net/http"
+require "uri"
+require "ag_ui"
+
+module AgUi
+  module A2ui
+    # The A2UI component catalog — the app's own UI vocabulary, served by
+    # the frontend (e.g. GET /api/copilotkit/catalog) and fetched once at
+    # boot, mirroring the Node sidecar (doc 09 §5): 20 retries x 3s, and
+    # on total failure A2UI DEGRADES (tool still injected, no schema)
+    # rather than failing the boot.
+    #
+    #   catalog = AgUi::A2ui::Catalog.fetch(url: ENV["AI_CATALOG_URL"])
+    #   catalog&.catalog_id  #=> "host://ai-catalog"
+    #
+    Catalog = Data.define(:catalog_id, :components) do
+      # Wire shape: { "catalogId" => "...", "components" => {...} }
+      def self.from_wire(data)
+        unless data.is_a?(Hash) && data["catalogId"] && data["components"]
+          raise ArgumentError, "malformed catalog: expected catalogId + components"
+        end
+
+        new(catalog_id: data["catalogId"], components: data["components"])
+      end
+
+      def self.fetch(url:, retries: 20, interval: 3, http: nil, logger: Console)
+        http ||= ->(u) { Net::HTTP.get_response(URI(u)) }
+
+        attempt = 0
+        loop do
+          attempt += 1
+          begin
+            response = http.call(url)
+            unless response.is_a?(Net::HTTPSuccess)
+              raise "HTTP #{response.code}"
+            end
+
+            catalog = from_wire(JSON.parse(response.body))
+            logger.info(
+              self,
+              "loaded A2UI catalog #{catalog.catalog_id} " \
+              "(#{catalog.components.length} components) from #{url}",
+            )
+            break catalog
+          rescue => e
+            if attempt >= retries
+              logger.warn(
+                self,
+                "A2UI catalog unreachable after #{attempt} attempts " \
+                "(#{e.message}) — degrading (tool without schema)",
+              )
+              break nil
+            end
+            sleep interval
+          end
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "AgUi::A2ui::Catalog" do
+  ok_body = JSON.generate({
+    "catalogId" => "host://ai-catalog",
+    "components" => { "Card" => { "description" => "A card", "props" => {} } },
+  })
+
+  fake_response = Struct.new(:body, :code) do
+    def is_a?(klass) = klass == Net::HTTPSuccess || super
+  end
+
+  it "parses the wire shape" do
+    catalog = AgUi::A2ui::Catalog.from_wire(JSON.parse(ok_body))
+    catalog.catalog_id.should == "host://ai-catalog"
+    catalog.components.keys.should == ["Card"]
+  end
+
+  it "rejects malformed catalogs" do
+    lambda { AgUi::A2ui::Catalog.from_wire({ "nope" => 1 }) }.should.raise(ArgumentError)
+  end
+
+  it "fetches with retries and returns the catalog" do
+    calls = 0
+    http = ->(_url) do
+      calls += 1
+      raise "conn refused" if calls < 3
+
+      fake_response.new(ok_body, "200")
+    end
+
+    catalog = AgUi::A2ui::Catalog.fetch(url: "http://x/catalog", retries: 5, interval: 0, http: http)
+    catalog.catalog_id.should == "host://ai-catalog"
+    calls.should == 3
+  end
+
+  it "degrades to nil after exhausting retries" do
+    http = ->(_url) { raise "conn refused" }
+    AgUi::A2ui::Catalog.fetch(url: "http://x/catalog", retries: 2, interval: 0, http: http)
+      .should.be.nil
+  end
+end

data/lib/ag_ui/a2ui/recovery.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ag_ui"
+
+module AgUi
+  module A2ui
+    # A2UI error-recovery loop — Ruby port of the toolkit's recovery.py.
+    #
+    # The toolkit cannot bind/invoke a model, so the adapter supplies
+    # `invoke_subagent` (its model call, receives (prompt, attempt) and
+    # returns the render_a2ui args hash or nil) and `build_envelope` (its
+    # prepared operations envelope). This module owns the validate→retry
+    # loop using the SAME validate_components the middleware uses, so the
+    # retry decision and the paint decision agree.
+    module Recovery
+      module_function
+
+      # Default attempt cap (initial try + retries). Configurable per call.
+      MAX_A2UI_ATTEMPTS = 3
+
+      # Activity type the middleware/client use for the recovery status channel.
+      A2UI_RECOVERY_ACTIVITY_TYPE = "a2ui_recovery"
+
+      NO_TOOL_CALL_ERROR = {
+        "code" => "empty_components",
+        "path" => "components",
+        "message" => "Sub-agent did not call render_a2ui",
+      }.freeze
+
+      # Render structured errors as a compact, model-readable list.
+      def format_validation_errors(errors)
+        errors.map { |e| "- [#{e["code"]}] #{e["path"]}: #{e["message"]}" }.join("\n")
+      end
+
+      # Append a fix-it block describing the prior attempt's errors.
+      def augment_prompt_with_validation_errors(prompt, errors)
+        if errors.empty?
+          prompt
+        else
+          "#{prompt}\n\n## Previous attempt was invalid — fix these and regenerate:\n" \
+            "#{format_validation_errors(errors)}\n"
+        end
+      end
+
+      # Drive the validate→retry loop. Returns {"envelope", "attempts",
+      # "ok"}: the validated envelope on success, or a structured
+      # a2ui_recovery_exhausted envelope once the cap is hit. Never retries
+      # an attempt whose components validated.
+      def run_generation_with_recovery(base_prompt:, invoke_subagent:, build_envelope:,
+                                       catalog: nil, config: nil, on_attempt: nil)
+        max_attempts = (config || {})["maxAttempts"] || MAX_A2UI_ATTEMPTS
+        attempts = []
+        last_errors = []
+
+        (1..max_attempts).each do |attempt|
+          prompt = augment_prompt_with_validation_errors(base_prompt, last_errors)
+          args = invoke_subagent.call(prompt, attempt)
+
+          record =
+            if args.nil? || args.empty?
+              { "attempt" => attempt, "ok" => false, "errors" => [NO_TOOL_CALL_ERROR] }
+            else
+              components = args["components"].is_a?(Array) ? args["components"] : []
+              data = args["data"].is_a?(Hash) ? args["data"] : {}
+              result = Validate.validate_components(components: components, data: data, catalog: catalog)
+              { "attempt" => attempt, "ok" => result["valid"], "errors" => result["errors"] }
+            end
+
+          attempts << record
+          on_attempt&.call(record)
+
+          if record["ok"]
+            break { "envelope" => build_envelope.call(args), "attempts" => attempts, "ok" => true }
+          end
+
+          last_errors = record["errors"]
+        end.then do |result|
+          if result.is_a?(Hash)
+            result
+          else
+            {
+              "envelope" => exhausted_envelope(max_attempts, attempts),
+              "attempts" => attempts,
+              "ok" => false,
+            }
+          end
+        end
+      end
+
+      def exhausted_envelope(max_attempts, attempts)
+        JSON.generate(
+          {
+            "error" => "Failed to generate valid A2UI after #{max_attempts} attempt(s)",
+            "code" => "a2ui_recovery_exhausted",
+            "attempts" => attempts,
+          },
+        )
+      end
+    end
+  end
+end
+
+__END__
+
+describe "AgUi::A2ui::Recovery" do
+  # Fixtures ported verbatim from the toolkit's test_recovery.py.
+  recovery = AgUi::A2ui::Recovery
+
+  catalog = { "components" => {
+    "Row" => { "required" => ["children"] },
+    "HotelCard" => { "required" => %w[name rating] },
+  } }
+
+  root = { "id" => "root", "component" => "Row",
+           "children" => { "componentId" => "card", "path" => "/items" } }
+  good_card = { "id" => "card", "component" => "HotelCard",
+                "name" => { "path" => "name" }, "rating" => { "path" => "rating" } }
+  bad_card = { "id" => "card", "component" => "HotelCard", "name" => { "path" => "name" } }
+
+  good_args = { "surfaceId" => "s1", "components" => [root, good_card],
+                "data" => { "items" => [{ "name" => "Ritz", "rating" => 4.8 }] } }
+  bad_args = { "surfaceId" => "s1", "components" => [root, bad_card],
+               "data" => { "items" => [{ "name" => "Ritz", "rating" => 4.8 }] } }
+
+  build_envelope = ->(args) { JSON.generate({ "a2ui_operations" => args["components"] }) }
+
+  it "exposes the upstream defaults" do
+    recovery::MAX_A2UI_ATTEMPTS.should == 3
+    recovery::A2UI_RECOVERY_ACTIVITY_TYPE.should == "a2ui_recovery"
+  end
+
+  it "augments prompts with a fix-it block only when there are errors" do
+    errors = [{ "code" => "missing_required_prop", "path" => "components[1].rating",
+                "message" => "missing required prop 'rating'" }]
+
+    recovery.augment_prompt_with_validation_errors("BASE", []).should == "BASE"
+
+    out = recovery.augment_prompt_with_validation_errors("BASE", errors)
+    out.should.include?("BASE")
+    out.should.include?("rating")
+    out.should.include?(recovery.format_validation_errors(errors))
+  end
+
+  it "returns the envelope on a valid first attempt" do
+    calls = []
+    result = recovery.run_generation_with_recovery(
+      base_prompt: "P", catalog: catalog,
+      invoke_subagent: ->(_prompt, attempt) { calls << attempt; good_args },
+      build_envelope: build_envelope,
+    )
+
+    result["ok"].should == true
+    result["attempts"].length.should == 1
+    calls.should == [1]
+    JSON.parse(result["envelope"]).key?("a2ui_operations").should == true
+  end
+
+  it "recovers on the second attempt with error feedback in the prompt" do
+    prompts = []
+    result = recovery.run_generation_with_recovery(
+      base_prompt: "P", catalog: catalog,
+      invoke_subagent: ->(prompt, attempt) { prompts << prompt; attempt == 1 ? bad_args : good_args },
+      build_envelope: build_envelope,
+    )
+
+    result["ok"].should == true
+    result["attempts"].length.should == 2
+    result["attempts"][0]["ok"].should == false
+    result["attempts"][1]["ok"].should == true
+    prompts[1].should.include?("rating")
+  end
+
+  it "returns the exhausted envelope after the attempt cap" do
+    seen = []
+    result = recovery.run_generation_with_recovery(
+      base_prompt: "P", catalog: catalog,
+      invoke_subagent: ->(_p, _a) { bad_args },
+      build_envelope: build_envelope,
+      on_attempt: ->(record) { seen << record },
+    )
+
+    result["ok"].should == false
+    result["attempts"].length.should == recovery::MAX_A2UI_ATTEMPTS
+    seen.length.should == recovery::MAX_A2UI_ATTEMPTS
+
+    parsed = JSON.parse(result["envelope"])
+    parsed["code"].should == "a2ui_recovery_exhausted"
+    parsed["error"].to_s.empty?.should == false
+    parsed["attempts"].should.be.kind_of(Array)
+  end
+
+  it "honours a maxAttempts override" do
+    calls = []
+    result = recovery.run_generation_with_recovery(
+      base_prompt: "P", catalog: catalog, config: { "maxAttempts" => 2 },
+      invoke_subagent: ->(_p, attempt) { calls << attempt; bad_args },
+      build_envelope: build_envelope,
+    )
+
+    result["ok"].should == false
+    calls.length.should == 2
+  end
+
+  it "treats a missing tool call as retryable" do
+    result = recovery.run_generation_with_recovery(
+      base_prompt: "P", catalog: catalog,
+      invoke_subagent: ->(_p, attempt) { attempt == 1 ? nil : good_args },
+      build_envelope: build_envelope,
+    )
+
+    result["ok"].should == true
+    result["attempts"].length.should == 2
+    result["attempts"][0]["ok"].should == false
+  end
+end