a2a-ruby 1.0.0

data/lib/a2a/types/task.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module A2A
+  module Types
+    ##
+    # Represents a task in the A2A protocol
+    #
+    # A task represents a unit of work that can be executed by an agent.
+    # It includes status information, artifacts, message history, and metadata.
+    #
+    class Task < A2A::Types::BaseModel
+      attr_reader :id, :context_id, :kind, :status, :artifacts, :history, :metadata
+
+      ##
+      # Initialize a new task
+      #
+      # @param id [String] Unique task identifier
+      # @param context_id [String] Context identifier for grouping related tasks
+      # @param status [TaskStatus, Hash] Current task status
+      # @param kind [String] Task kind (always "task")
+      # @param artifacts [Array<Artifact>, nil] Task artifacts
+      # @param history [Array<Message>, nil] Message history
+      # @param metadata [Hash, nil] Additional metadata
+      def initialize(id:, context_id:, status:, kind: KIND_TASK, artifacts: nil, history: nil, metadata: nil)
+        @id = id
+        @context_id = context_id
+        @kind = kind
+        @status = status.is_a?(TaskStatus) ? status : TaskStatus.from_h(status)
+        @artifacts = artifacts&.map { |a| a.is_a?(Artifact) ? a : Artifact.from_h(a) }
+        @history = history&.map { |m| m.is_a?(Message) ? m : Message.from_h(m) }
+        @metadata = metadata
+
+        validate!
+      end
+
+      ##
+      # Add an artifact to the task
+      #
+      # @param artifact [Artifact] The artifact to add
+      def add_artifact(artifact)
+        @artifacts ||= []
+        @artifacts << artifact
+      end
+
+      ##
+      # Add a message to the history
+      #
+      # @param message [Message] The message to add
+      def add_message(message)
+        @history ||= []
+        @history << message
+      end
+
+      ##
+      # Update the task status
+      #
+      # @param new_status [TaskStatus, Hash] The new status
+      def update_status(new_status)
+        @status = new_status.is_a?(TaskStatus) ? new_status : TaskStatus.from_h(new_status)
+      end
+
+      ##
+      # Check if the task is in a terminal state
+      #
+      # @return [Boolean] True if the task is completed, canceled, failed, or rejected
+      def terminal?
+        %w[completed canceled failed rejected].include?(@status.state)
+      end
+
+      ##
+      # Check if the task can be canceled
+      #
+      # @return [Boolean] True if the task can be canceled
+      def cancelable?
+        %w[submitted working input-required].include?(@status.state)
+      end
+
+      private
+
+      def validate!
+        validate_required(:id, :context_id, :status, :kind)
+        validate_inclusion(:kind, [KIND_TASK])
+        validate_type(:status, TaskStatus)
+        validate_array_type(:artifacts, Artifact) if @artifacts
+        validate_array_type(:history, Message) if @history
+      end
+    end
+
+    ##
+    # Represents the status of a task
+    #
+    class TaskStatus < A2A::Types::BaseModel
+      attr_reader :state, :message, :progress, :result, :error, :updated_at
+
+      ##
+      # Initialize a new task status
+      #
+      # @param state [String] The current state
+      # @param message [String, nil] Optional status message
+      # @param progress [Float, nil] Progress percentage (0.0 to 1.0)
+      # @param result [Object, nil] Task result (for completed tasks)
+      # @param error [Hash, nil] Error information (for failed tasks)
+      # @param updated_at [String, nil] ISO 8601 timestamp of last update
+      def initialize(state:, message: nil, progress: nil, result: nil, error: nil, updated_at: nil)
+        @state = state
+        @message = message
+        @progress = progress
+        @result = result
+        @error = error
+        @updated_at = updated_at || Time.now.utc.iso8601
+
+        validate!
+      end
+
+      ##
+      # Check if the status indicates success
+      #
+      # @return [Boolean] True if the task completed successfully
+      def success?
+        @state == TASK_STATE_COMPLETED && @error.nil?
+      end
+
+      ##
+      # Check if the status indicates failure
+      #
+      # @return [Boolean] True if the task failed
+      def failure?
+        @state == TASK_STATE_FAILED || !@error.nil?
+      end
+
+      ##
+      # Check if the task is still active
+      #
+      # @return [Boolean] True if the task is still being processed
+      def active?
+        %w[submitted working input-required].include?(@state)
+      end
+
+      private
+
+      def validate!
+        validate_required(:state, :updated_at)
+        validate_inclusion(:state, VALID_TASK_STATES)
+
+        return unless @progress
+
+        validate_type(:progress, Numeric)
+        return if @progress.between?(0.0, 1.0)
+
+        raise ArgumentError, "progress must be between 0.0 and 1.0"
+      end
+    end
+  end
+end

data/lib/a2a/types.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "types/base_model"
+require_relative "types/agent_card"
+require_relative "types/message"
+require_relative "types/task"
+require_relative "types/part"
+require_relative "types/artifact"
+require_relative "types/events"
+require_relative "types/push_notification"
+require_relative "types/security"
+
+##
+# Type definitions for the A2A protocol
+#
+# This module contains all the data types used in the A2A protocol,
+# including messages, tasks, agent cards, and various supporting types.
+#
+module A2A
+  module Types
+    # Transport protocol constants
+    TRANSPORT_JSONRPC = "JSONRPC"
+    TRANSPORT_GRPC = "GRPC"
+    TRANSPORT_HTTP_JSON = "HTTP+JSON"
+
+    # Valid transport protocols
+    VALID_TRANSPORTS = [TRANSPORT_JSONRPC, TRANSPORT_GRPC, TRANSPORT_HTTP_JSON].freeze
+
+    # Message roles
+    ROLE_USER = "user"
+    ROLE_AGENT = "agent"
+
+    # Valid message roles
+    VALID_ROLES = [ROLE_USER, ROLE_AGENT].freeze
+
+    # Task states
+    TASK_STATE_SUBMITTED = "submitted"
+    TASK_STATE_WORKING = "working"
+    TASK_STATE_INPUT_REQUIRED = "input-required"
+    TASK_STATE_COMPLETED = "completed"
+    TASK_STATE_CANCELED = "canceled"
+    TASK_STATE_FAILED = "failed"
+    TASK_STATE_REJECTED = "rejected"
+    TASK_STATE_AUTH_REQUIRED = "auth-required"
+    TASK_STATE_UNKNOWN = "unknown"
+
+    # Valid task states
+    VALID_TASK_STATES = [
+      TASK_STATE_SUBMITTED,
+      TASK_STATE_WORKING,
+      TASK_STATE_INPUT_REQUIRED,
+      TASK_STATE_COMPLETED,
+      TASK_STATE_CANCELED,
+      TASK_STATE_FAILED,
+      TASK_STATE_REJECTED,
+      TASK_STATE_AUTH_REQUIRED,
+      TASK_STATE_UNKNOWN
+    ].freeze
+
+    # Part kinds
+    PART_KIND_TEXT = "text"
+    PART_KIND_FILE = "file"
+    PART_KIND_DATA = "data"
+
+    # Valid part kinds
+    VALID_PART_KINDS = [PART_KIND_TEXT, PART_KIND_FILE, PART_KIND_DATA].freeze
+
+    # Object kinds
+    KIND_MESSAGE = "message"
+    KIND_TASK = "task"
+
+    # Security scheme types
+    SECURITY_TYPE_API_KEY = "apiKey"
+    SECURITY_TYPE_HTTP = "http"
+    SECURITY_TYPE_OAUTH2 = "oauth2"
+    SECURITY_TYPE_OPENID_CONNECT = "openIdConnect"
+    SECURITY_TYPE_MUTUAL_TLS = "mutualTLS"
+
+    # Valid security scheme types
+    VALID_SECURITY_TYPES = [
+      SECURITY_TYPE_API_KEY,
+      SECURITY_TYPE_HTTP,
+      SECURITY_TYPE_OAUTH2,
+      SECURITY_TYPE_OPENID_CONNECT,
+      SECURITY_TYPE_MUTUAL_TLS
+    ].freeze
+  end
+end

data/lib/a2a/utils/helpers.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "base64"
+
+##
+# Common utility helper methods
+#
+# Provides various utility methods for UUID generation, string manipulation,
+# encoding/decoding, and other common operations used throughout the A2A gem.
+#
+module A2A
+  module Utils
+    module Helpers
+      class << self
+        ##
+        # Generate a UUID
+        #
+        # @return [String] A new UUID string
+        def generate_uuid
+          SecureRandom.uuid
+        end
+
+        ##
+        # Generate a random hex string
+        #
+        # @param length [Integer] Length of the hex string (default: 16)
+        # @return [String] Random hex string
+        def generate_hex(length = 16)
+          SecureRandom.hex(length)
+        end
+
+        ##
+        # Generate a secure random token
+        #
+        # @param length [Integer] Length of the token (default: 32)
+        # @return [String] Base64-encoded random token
+        def generate_token(length = 32)
+          Base64.urlsafe_encode64(SecureRandom.random_bytes(length), padding: false)
+        end
+
+        ##
+        # Generate a hash of a string
+        #
+        # @param string [String] String to hash
+        # @param algorithm [Symbol] Hash algorithm (:sha256, :sha1, :md5)
+        # @return [String] Hex-encoded hash
+        def hash_string(string, algorithm: :sha256)
+          case algorithm
+          when :sha256
+            Digest::SHA256.hexdigest(string)
+          when :sha1
+            Digest::SHA1.hexdigest(string)
+          when :md5
+            Digest::MD5.hexdigest(string)
+          else
+            raise ArgumentError, "Unsupported hash algorithm: #{algorithm}"
+          end
+        end
+
+        ##
+        # Safely parse JSON with error handling
+        #
+        # @param json_string [String] JSON string to parse
+        # @param default [Object] Default value if parsing fails
+        # @return [Object] Parsed JSON or default value
+        def safe_json_parse(json_string, default: nil)
+          JSON.parse(json_string)
+        rescue JSON::ParserError
+          default
+        end
+
+        ##
+        # Deep merge two hashes
+        #
+        # @param hash1 [Hash] First hash
+        # @param hash2 [Hash] Second hash
+        # @return [Hash] Merged hash
+        def deep_merge(hash1, hash2)
+          hash1.merge(hash2) do |_key, old_val, new_val|
+            if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+              deep_merge(old_val, new_val)
+            else
+              new_val
+            end
+          end
+        end
+
+        ##
+        # Convert string to snake_case
+        #
+        # @param string [String] String to convert
+        # @return [String] Snake_case string
+        def snake_case(string)
+          string
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+        end
+
+        ##
+        # Convert string to camelCase
+        #
+        # @param string [String] String to convert
+        # @param first_letter_uppercase [Boolean] Whether first letter should be uppercase
+        # @return [String] CamelCase string
+        def camel_case(string, first_letter_uppercase: false)
+          parts = string.split(/[_\-\s]+/)
+          result = parts.first.downcase
+          result += parts[1..].map(&:capitalize).join if parts.length > 1
+
+          first_letter_uppercase ? result.capitalize : result
+        end
+
+        ##
+        # Truncate string to specified length
+        #
+        # @param string [String] String to truncate
+        # @param length [Integer] Maximum length
+        # @param suffix [String] Suffix to add if truncated
+        # @return [String] Truncated string
+        def truncate(string, length:, suffix: "...")
+          return string if string.length <= length
+
+          truncated_length = length - suffix.length
+          return suffix if truncated_length <= 0
+
+          string[0...truncated_length] + suffix
+        end
+
+        ##
+        # Sanitize string for safe usage
+        #
+        # @param string [String] String to sanitize
+        # @param allowed_chars [Regexp] Allowed characters pattern
+        # @return [String] Sanitized string
+        def sanitize_string(string, allowed_chars: /[a-zA-Z0-9_\-.]/)
+          string.gsub(/[^#{allowed_chars.source}]/, "_")
+        end
+
+        ##
+        # Check if string is blank (nil, empty, or whitespace only)
+        #
+        # @param string [String, nil] String to check
+        # @return [Boolean] True if blank
+        def blank?(string)
+          string.nil? || string.strip.empty?
+        end
+
+        ##
+        # Check if string is present (not blank)
+        #
+        # @param string [String, nil] String to check
+        # @return [Boolean] True if present
+        def present?(string)
+          !blank?(string)
+        end
+
+        ##
+        # Retry a block with exponential backoff
+        #
+        # @param max_attempts [Integer] Maximum number of attempts
+        # @param base_delay [Float] Base delay in seconds
+        # @param max_delay [Float] Maximum delay in seconds
+        # @param backoff_factor [Float] Backoff multiplier
+        # @yield Block to retry
+        # @return [Object] Block result
+        def retry_with_backoff(max_attempts: 3, base_delay: 1.0, max_delay: 60.0, backoff_factor: 2.0)
+          attempt = 1
+
+          begin
+            yield
+          rescue StandardError => e
+            raise e unless attempt < max_attempts
+
+            delay = [base_delay * (backoff_factor**(attempt - 1)), max_delay].min
+            sleep(delay)
+            attempt += 1
+            retry
+          end
+        end
+
+        ##
+        # Measure execution time of a block
+        #
+        # @yield Block to measure
+        # @return [Hash] Result with :result and :duration keys
+        def measure_execution_time
+          start_time = Time.now
+          result = yield
+          end_time = Time.now
+
+          {
+            result: result,
+            duration: end_time - start_time
+          }
+        end
+
+        ##
+        # Format bytes in human-readable format
+        #
+        # @param bytes [Integer] Number of bytes
+        # @return [String] Formatted string
+        def format_bytes(bytes)
+          return "0 B" if bytes.zero?
+
+          units = %w[B KB MB GB TB PB]
+          exp = (Math.log(bytes.abs) / Math.log(1024)).floor
+          exp = [exp, units.length - 1].min
+
+          "#{(bytes / (1024.0**exp)).round(2)} #{units[exp]}"
+        end
+
+        ##
+        # Validate email format
+        #
+        # @param email [String] Email to validate
+        # @return [Boolean] True if valid email format
+        def valid_email?(email)
+          return false if blank?(email)
+
+          # Simple email validation regex
+          email.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+        end
+
+        ##
+        # Validate URL format
+        #
+        # @param url [String] URL to validate
+        # @return [Boolean] True if valid URL format
+        def valid_url?(url)
+          return false if blank?(url)
+
+          begin
+            uri = URI.parse(url)
+            uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+          rescue URI::InvalidURIError
+            false
+          end
+        end
+      end
+    end
+  end
+end