llm.rb 10.0.0 → 11.1.0

data/lib/llm/a2a/card/skill.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class LLM::A2A::Card
+  ##
+  # Represents a single skill/capability of an agent.
+  class Skill
+    ##
+    # @param [Hash] data
+    def initialize(data)
+      @data = LLM::Object.from(data)
+    end
+
+    ##
+    # Returns the unique identifier for the skill.
+    # @return [String]
+    def id
+      @data.id
+    end
+
+    ##
+    # Returns the human-readable skill name.
+    # @return [String]
+    def name
+      @data.name
+    end
+
+    ##
+    # Returns the detailed skill description.
+    # @return [String]
+    def description
+      @data.description
+    end
+
+    ##
+    # Returns capability tags for the skill.
+    # @return [Array<String>]
+    def tags
+      @data.tags || []
+    end
+
+    ##
+    # Returns example prompts for the skill.
+    # @return [Array<String>]
+    def examples
+      @data.examples || []
+    end
+
+    ##
+    # Returns the supported input media types.
+    # @return [Array<String>]
+    def input_modes
+      @data.inputModes || @data.input_modes || []
+    end
+
+    ##
+    # Returns the supported output media types.
+    # @return [Array<String>]
+    def output_modes
+      @data.outputModes || @data.output_modes || []
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{LLM::Utils.object_id(self)} @id=#{id.inspect} @name=#{name.inspect}>"
+    end
+  end
+end

data/lib/llm/a2a/card.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+class LLM::A2A
+  ##
+  # Represents an A2A Agent Card — a self-describing manifest for an
+  # agent that provides metadata including the agent's identity,
+  # capabilities, skills, supported communication methods, and security
+  # requirements.
+  #
+  # Agent Cards are published at `/.well-known/agent-card.json` and
+  # allow clients to discover an agent's capabilities before interacting.
+  #
+  # @example
+  #   a2a = LLM::A2A.rest(url: "https://agent.example.com")
+  #   card = a2a.card
+  #   puts card.name          # => "GeoSpatial Route Planner Agent"
+  #   puts card.description   # => "Provides advanced route planning..."
+  #   card.skills.each { |s| puts "#{s.name}: #{s.description}" }
+  class Card
+    require_relative "card/skill"
+    require_relative "card/interface"
+    require_relative "card/capabilities"
+    require_relative "card/provider"
+
+    ##
+    # @param [Hash] data The raw Agent Card JSON data
+    def initialize(data)
+      @data = LLM::Object.from(data)
+    end
+
+    ##
+    # Returns a human-readable name for the agent.
+    # @return [String]
+    def name
+      @data.name
+    end
+
+    ##
+    # Returns a human-readable description of the agent.
+    # @return [String]
+    def description
+      @data.description
+    end
+
+    ##
+    # Returns the agent version.
+    # @return [String]
+    def version
+      @data.version
+    end
+
+    ##
+    # Returns the advertised A2A protocol version.
+    # @return [String, nil]
+    def protocol_version
+      @data.protocolVersion || @data.protocol_version
+    end
+
+    ##
+    # Returns the documentation URL, when present.
+    # @return [String, nil]
+    def documentation_url
+      @data.documentationUrl || @data.documentation_url
+    end
+
+    ##
+    # Returns the icon URL, when present.
+    # @return [String, nil]
+    def icon_url
+      @data.iconUrl || @data.icon_url
+    end
+
+    ##
+    # Returns the skills provided by the agent.
+    # @return [Array<LLM::A2A::Card::Skill>]
+    def skills
+      @skills ||= (@data.skills || []).map { Skill.new(_1) }
+    end
+
+    ##
+    # Returns the interfaces supported by the agent.
+    # @return [Array<LLM::A2A::Card::Interface>]
+    def interfaces
+      @interfaces ||= (@data.supportedInterfaces || @data.supported_interfaces || []).map { Interface.new(_1) }
+    end
+
+    ##
+    # Returns the optional capabilities declaration.
+    # @return [LLM::A2A::Card::Capabilities, nil]
+    def capabilities
+      raw = @data.capabilities
+      raw ? Capabilities.new(raw) : nil
+    end
+
+    ##
+    # Returns the agent card signatures.
+    # @return [Array<LLM::Object>]
+    def signatures
+      @signatures ||= (@data.signatures || []).map { LLM::Object.from(_1) }
+    end
+
+    ##
+    # Returns the security scheme definitions.
+    # @return [Hash<String, Hash>, nil]
+    def security_schemes
+      @data.securitySchemes || @data.security_schemes
+    end
+
+    ##
+    # Returns the security requirements.
+    # @return [Array<Hash>, nil]
+    def security_requirements
+      @data.security || @data.security_requirements
+    end
+
+    ##
+    # Returns the declared provider information.
+    # @return [LLM::A2A::Card::Provider, nil]
+    def provider
+      raw = @data.provider
+      raw ? Provider.new(raw) : nil
+    end
+
+    ##
+    # Returns the default input media types.
+    # @return [Array<String>]
+    def default_input_modes
+      @data.defaultInputModes || @data.default_input_modes || []
+    end
+
+    ##
+    # Returns the default output media types.
+    # @return [Array<String>]
+    def default_output_modes
+      @data.defaultOutputModes || @data.default_output_modes || []
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{LLM::Utils.object_id(self)} @name=#{name.inspect} @skills=#{skills.size}>"
+    end
+  end
+end

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