llm.rb 10.0.0 → 11.0.0

data/lib/llm/a2a/error.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class LLM::A2A
+  ##
+  # Generic A2A protocol error.
+  Error = Class.new(LLM::Error) do
+    ##
+    # @return [Integer, nil]
+    attr_reader :code
+
+    ##
+    # @return [Object, nil]
+    attr_reader :data
+
+    ##
+    # @param [String] message
+    # @param [Integer, nil] code
+    # @param [Object, nil] data
+    def initialize(message, code = nil, data = nil)
+      super(message)
+      @code = code
+      @data = data
+    end
+  end
+
+  ##
+  # Raised when the agent card cannot be fetched or parsed.
+  AgentCardError = Class.new(Error)
+
+  ##
+  # Raised when a task is not found.
+  TaskNotFoundError = Class.new(Error)
+
+  ##
+  # Raised when a task cannot be cancelled.
+  TaskNotCancelableError = Class.new(Error)
+
+  ##
+  # Raised when the agent does not support the requested operation.
+  UnsupportedOperationError = Class.new(Error)
+
+  ##
+  # Raised when a content type is not supported.
+  ContentTypeNotSupportedError = Class.new(Error)
+
+  ##
+  # Raised when the A2A protocol version is not supported.
+  VersionNotSupportedError = Class.new(Error)
+end

data/lib/llm/a2a/notifications.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class LLM::A2A
+  ##
+  # Groups push notification configuration operations.
+  class Notifications
+    ##
+    # @param [LLM::A2A] a2a
+    def initialize(a2a)
+      @a2a = a2a
+    end
+
+    ##
+    # Creates a push notification configuration for a task.
+    # @param [String] task_id
+    # @param [String] url
+    # @param [String, nil] token
+    # @param [Hash, nil] authentication
+    # @param [String, nil] id
+    # @return [LLM::Object]
+    def create(task_id, url:, token: nil, authentication: nil, id: nil)
+      @a2a.create_task_push_notification_config(task_id, url:, token:, authentication:, id:)
+    end
+
+    ##
+    # Retrieves a push notification configuration for a task.
+    # @param [String] task_id
+    # @param [String] id
+    # @return [LLM::Object]
+    def get(task_id, id)
+      @a2a.get_task_push_notification_config(task_id, id)
+    end
+
+    ##
+    # Lists push notification configurations for a task.
+    # @param [String] task_id
+    # @param [Integer, nil] page_size
+    # @param [String, nil] page_token
+    # @return [LLM::Object]
+    def list(task_id, page_size: nil, page_token: nil)
+      @a2a.list_task_push_notification_configs(task_id, page_size:, page_token:)
+    end
+
+    ##
+    # Deletes a push notification configuration for a task.
+    # @param [String] task_id
+    # @param [String] id
+    # @return [LLM::Object]
+    def delete(task_id, id)
+      @a2a.delete_task_push_notification_config(task_id, id)
+    end
+  end
+end

data/lib/llm/a2a/tasks.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class LLM::A2A
+  ##
+  # Groups task-oriented A2A operations.
+  class Tasks
+    ##
+    # @param [LLM::A2A] a2a
+    def initialize(a2a)
+      @a2a = a2a
+    end
+
+    ##
+    # Returns the current state of a task.
+    # @param [String] task_id
+    # @param [Integer, nil] history_length
+    # @return [LLM::Object]
+    def get(task_id, history_length: nil)
+      @a2a.get_task(task_id, history_length:)
+    end
+
+    ##
+    # Lists tasks with optional filtering.
+    # @param [String, nil] context_id
+    # @param [String, nil] status
+    # @param [Integer, nil] history_length
+    # @param [String, nil] status_timestamp_after
+    # @param [Boolean, nil] include_artifacts
+    # @param [Integer] page_size
+    # @param [String, nil] page_token
+    # @return [LLM::Object]
+    def list(context_id: nil, status: nil, history_length: nil, status_timestamp_after: nil,
+             include_artifacts: nil, page_size: 20, page_token: nil)
+      @a2a.list_tasks(context_id:, status:, history_length:, status_timestamp_after:,
+                      include_artifacts:, page_size:, page_token:)
+    end
+
+    ##
+    # Cancels a task in progress.
+    # @param [String] task_id
+    # @return [LLM::Object]
+    def cancel(task_id, metadata: nil)
+      @a2a.cancel_task(task_id, metadata:)
+    end
+
+    ##
+    # Subscribes to streaming updates for an existing task.
+    # @param [String] task_id
+    # @yieldparam [LLM::Object] event
+    # @return [void]
+    def subscribe(task_id, &on_event)
+      @a2a.subscribe_to_task(task_id, &on_event)
+    end
+  end
+end

data/lib/llm/a2a/transport/http.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+class LLM::A2A
+  module Transport
+    ##
+    # The {LLM::A2A::Transport::HTTP} class provides the HTTP+JSON/REST
+    # protocol binding for the A2A protocol. It sends JSON payloads to
+    # A2A agent endpoints and handles both synchronous responses and
+    # Server-Sent Events for streaming operations.
+    #
+    # This transport implements the HTTP+JSON/REST binding as defined
+    # in the A2A specification (Section 11).
+    class HTTP
+      include LLM::Transport::Utils
+
+      ##
+      # @param [String] url The base URL of the A2A agent
+      # @param [Hash<String, String>] headers Extra HTTP headers
+      # @param [Integer, nil] timeout The timeout in seconds
+      # @param [LLM::Transport, Class, nil] transport Override transport
+      # @param [String] protocol_version The A2A protocol version header
+      def initialize(url:, headers: {}, timeout: nil, transport: nil, protocol_version: "1.0")
+        @uri = URI.parse(url)
+        @headers = headers
+        @protocol_version = protocol_version
+        @transport = resolve_transport(@uri, transport, timeout)
+      end
+
+      ##
+      # Sends a GET request.
+      # @param [String] path The URL path
+      # @return [Hash]
+      def get(path, accept: "application/json")
+        req = Net::HTTP::Get.new(request_path(path), headers(accept:))
+        res = transport.request(req, owner: self)
+        parse_response(res)
+      end
+
+      ##
+      # Sends a POST request.
+      # @param [String] path The URL path
+      # @param [Hash] body The JSON body
+      # @return [Hash]
+      def post(path, body, content_type: "application/json", accept: "application/json")
+        req = Net::HTTP::Post.new(request_path(path), headers(content_type:, accept:))
+        req.body = LLM.json.dump(body)
+        res = transport.request(req, owner: self)
+        parse_response(res)
+      end
+
+      ##
+      # Sends a DELETE request.
+      # @param [String] path The URL path
+      # @return [Hash]
+      def delete(path, accept: "application/json")
+        req = Net::HTTP::Delete.new(request_path(path), headers(accept:))
+        res = transport.request(req, owner: self)
+        parse_response(res)
+      end
+
+      ##
+      # Sends a GET request with a streaming (SSE) response.
+      #
+      # The block is called for each event parsed from the event stream.
+      # @param [String] path The URL path
+      # @yieldparam [LLM::Object] event A stream event
+      # @return [void]
+      def get_stream(path, &on_event)
+        req = Net::HTTP::Get.new(request_path(path), headers(accept: "text/event-stream"))
+        stream(req, &on_event)
+      end
+
+      ##
+      # Sends a POST request with a streaming (SSE) response.
+      #
+      # The block is called for each event parsed from the event stream.
+      # @param [String] path The URL path
+      # @param [Hash] body The JSON body
+      # @yieldparam [LLM::Object] event A stream event
+      # @return [void]
+      def post_stream(path, body, content_type: "application/json", &on_event)
+        req = Net::HTTP::Post.new(request_path(path), headers(content_type:, accept: "text/event-stream"))
+        req.body = LLM.json.dump(body)
+        stream(req, &on_event)
+      end
+
+      private
+
+      attr_reader :transport
+
+      def headers(content_type: "application/json", accept: "application/json")
+        {
+          "A2A-Version" => @protocol_version,
+          "content-type" => content_type,
+          "accept" => accept
+        }.merge(@headers)
+      end
+
+      def request_path(path)
+        path = LLM::Utils.normalize_base_path(path)
+        path.empty? ? "/" : path
+      end
+
+      def stream(req, &on_event)
+        transport.request(req, owner: self) do |raw|
+          raw = LLM::Transport::Response.from(raw)
+          next raw unless raw.success?
+          decoder = LLM::Transport::StreamDecoder.new(&on_event)
+          raw.read_body { decoder << _1 }
+          decoder.free
+        end
+      end
+
+      def parse_response(res)
+        res = LLM::Transport::Response.from(res)
+        body = res.body.to_s
+        if res.success?
+          body.empty? ? {} : LLM.json.load(body)
+        else
+          handle_error(res.code, body)
+        end
+      end
+
+      def handle_error(code, body)
+        data = LLM.json.load(body) rescue {}
+        msg = data.dig("error", "message") || data["message"] || "HTTP #{code}"
+        raise LLM::A2A::Error.new(msg, code.to_i, data)
+      end
+    end
+  end
+end