a2a-ruby 1.0.0

data/lib/a2a/types/base_model.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "time"
+
+module A2A
+  module Types
+  end
+end
+
+##
+# Base class for all A2A protocol types
+#
+# Provides common functionality for validation, serialization, and
+# camelCase/snake_case conversion for A2A protocol compatibility.
+#
+module A2A
+  module Types
+    class BaseModel
+      ##
+      # Initialize a new model instance
+      #
+      # @param attributes [Hash] The attributes to set
+      def initialize(**attributes)
+        # Set instance variables for all provided attributes
+        attributes.each do |key, value|
+          instance_variable_set("@#{key}", value)
+        end
+
+        # Validate the instance after initialization
+        validate! if respond_to?(:validate!, true)
+      end
+
+      ##
+      # Convert the model to a hash representation
+      #
+      # @param camel_case [Boolean] Whether to convert keys to camelCase
+      # @return [Hash] The model as a hash
+      def to_h(camel_case: true)
+        hash = {}
+
+        instance_variables.each do |var|
+          key = var.to_s.delete("@")
+          value = instance_variable_get(var)
+
+          # Convert nested models
+          case value
+          when BaseModel
+            value = value.to_h(camel_case: camel_case)
+          when Array
+            value = value.map do |item|
+              item.is_a?(BaseModel) ? item.to_h(camel_case: camel_case) : item
+            end
+          when Hash
+            value = value.transform_values do |v|
+              v.is_a?(BaseModel) ? v.to_h(camel_case: camel_case) : v
+            end
+          end
+
+          # Convert key to camelCase if requested
+          key = camelize(key) if camel_case
+          hash[key] = value unless value.nil?
+        end
+
+        hash
+      end
+
+      ##
+      # Create an instance from a hash
+      #
+      # @param hash [Hash] The hash to create from
+      # @return [BaseModel] The new instance
+      def self.from_h(hash)
+        return hash if hash.is_a?(self) # Already an instance of this class
+        return nil if hash.nil?
+
+        # Convert string keys to symbols and snake_case camelCase keys
+        normalized_hash = {}
+        hash.each do |key, value|
+          snake_key = underscore(key.to_s).to_sym
+          normalized_hash[snake_key] = value
+        end
+
+        new(**normalized_hash)
+      end
+
+      ##
+      # Convert to JSON string
+      #
+      # @param options [Hash] JSON generation options
+      # @return [String] The JSON representation
+      def to_json(**options)
+        require "json"
+        to_h.to_json(**options)
+      end
+
+      ##
+      # Create an instance from JSON string
+      #
+      # @param json_string [String] The JSON string
+      # @return [BaseModel] The new instance
+      def self.from_json(json_string)
+        require "json"
+        hash = JSON.parse(json_string)
+        from_h(hash)
+      end
+
+      ##
+      # Check equality with another model
+      #
+      # @param other [Object] The other object to compare
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        to_h == other.to_h
+      end
+
+      ##
+      # Generate hash code for the model
+      #
+      # @return [Integer] The hash code
+      def hash
+        to_h.hash
+      end
+
+      ##
+      # Check if the model is valid
+      #
+      # @return [Boolean] True if valid
+      def valid?
+        validate!
+        true
+      rescue StandardError
+        false
+      end
+
+      private
+
+      ##
+      # Convert snake_case to camelCase
+      #
+      # @param string [String] The string to convert
+      # @return [String] The camelCase string
+      def camelize(string)
+        string.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+      end
+
+      ##
+      # Convert camelCase to snake_case
+      #
+      # @param string [String] The string to convert
+      # @return [String] The snake_case string
+      def self.underscore(string)
+        string.to_s
+              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+      end
+
+      ##
+      # Validate required fields
+      #
+      # @param fields [Array<Symbol>] The required field names
+      # @raise [ArgumentError] If any required field is missing
+      def validate_required(*fields)
+        fields.each do |field|
+          value = instance_variable_get("@#{field}")
+          raise ArgumentError, "#{field} is required" if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        end
+      end
+
+      ##
+      # Validate that a field is one of the allowed values
+      #
+      # @param field [Symbol] The field name
+      # @param allowed_values [Array] The allowed values
+      # @raise [ArgumentError] If the field value is not allowed
+      def validate_inclusion(field, allowed_values)
+        value = instance_variable_get("@#{field}")
+        return if value.nil?
+
+        return if allowed_values.include?(value)
+
+        raise ArgumentError, "#{field} must be one of: #{allowed_values.join(', ')}"
+      end
+
+      ##
+      # Validate that a field is of the expected type
+      #
+      # @param field [Symbol] The field name
+      # @param expected_type [Class, Array<Class>] The expected type(s)
+      # @raise [ArgumentError] If the field is not of the expected type
+      def validate_type(field, expected_type)
+        value = instance_variable_get("@#{field}")
+        return if value.nil?
+
+        types = expected_type.is_a?(Array) ? expected_type : [expected_type]
+
+        return if types.any? { |type| value.is_a?(type) }
+
+        type_names = types.map(&:to_s).join(" or ")
+        raise ArgumentError, "#{field} must be a #{type_names}"
+      end
+
+      ##
+      # Validate that an array field contains only items of the expected type
+      #
+      # @param field [Symbol] The field name
+      # @param expected_type [Class] The expected item type
+      # @raise [ArgumentError] If any item is not of the expected type
+      def validate_array_type(field, expected_type)
+        value = instance_variable_get("@#{field}")
+        return if value.nil?
+
+        validate_type(field, Array)
+
+        value.each_with_index do |item, index|
+          raise ArgumentError, "#{field}[#{index}] must be a #{expected_type}" unless item.is_a?(expected_type)
+        end
+      end
+    end
+  end
+end

data/lib/a2a/types/events.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module A2A
+  module Types
+    ##
+    # Represents a task status update event
+    #
+    # These events are sent when a task's status changes, allowing clients
+    # to track task progress in real-time.
+    #
+    class TaskStatusUpdateEvent < A2A::Types::BaseModel
+      attr_reader :task_id, :context_id, :status, :metadata
+
+      ##
+      # Initialize a new task status update event
+      #
+      # @param task_id [String] The task identifier
+      # @param context_id [String] The context identifier
+      # @param status [TaskStatus, Hash] The new task status
+      # @param metadata [Hash, nil] Additional event metadata
+      def initialize(task_id:, context_id:, status:, metadata: nil)
+        @task_id = task_id
+        @context_id = context_id
+        @status = status.is_a?(TaskStatus) ? status : TaskStatus.from_h(status)
+        @metadata = metadata
+
+        validate!
+      end
+
+      ##
+      # Get the event type
+      #
+      # @return [String] The event type
+      def event_type
+        "task_status_update"
+      end
+
+      ##
+      # Check if this is a terminal status update
+      #
+      # @return [Boolean] True if the status is terminal
+      def terminal?
+        @status.state.in?(%w[completed canceled failed rejected])
+      end
+
+      private
+
+      def validate!
+        validate_required(:task_id, :context_id, :status)
+        validate_type(:task_id, String)
+        validate_type(:context_id, String)
+        validate_type(:status, TaskStatus)
+      end
+    end
+
+    ##
+    # Represents a task artifact update event
+    #
+    # These events are sent when artifacts are added or updated for a task,
+    # supporting streaming artifact delivery.
+    #
+    class TaskArtifactUpdateEvent < A2A::Types::BaseModel
+      attr_reader :task_id, :context_id, :artifact, :append, :metadata
+
+      ##
+      # Initialize a new task artifact update event
+      #
+      # @param task_id [String] The task identifier
+      # @param context_id [String] The context identifier
+      # @param artifact [Artifact, Hash] The artifact being updated
+      # @param append [Boolean] Whether to append to existing artifact
+      # @param metadata [Hash, nil] Additional event metadata
+      def initialize(task_id:, context_id:, artifact:, append: false, metadata: nil)
+        @task_id = task_id
+        @context_id = context_id
+        @artifact = artifact.is_a?(Artifact) ? artifact : Artifact.from_h(artifact)
+        @append = append
+        @metadata = metadata
+
+        validate!
+      end
+
+      ##
+      # Get the event type
+      #
+      # @return [String] The event type
+      def event_type
+        "task_artifact_update"
+      end
+
+      ##
+      # Check if this is an append operation
+      #
+      # @return [Boolean] True if appending to existing artifact
+      def append?
+        @append
+      end
+
+      ##
+      # Check if this is a replace operation
+      #
+      # @return [Boolean] True if replacing existing artifact
+      def replace?
+        !@append
+      end
+
+      private
+
+      def validate!
+        validate_required(:task_id, :context_id, :artifact)
+        validate_type(:task_id, String)
+        validate_type(:context_id, String)
+        validate_type(:artifact, Artifact)
+      end
+    end
+  end
+end

data/lib/a2a/types/message.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+##
+# Represents a message in the A2A protocol
+#
+# Messages are the primary means of communication between agents and users.
+# They contain one or more parts (text, files, or data) and metadata.
+#
+module A2A
+  module Types
+    class Message < A2A::Types::BaseModel
+      attr_reader :message_id, :role, :parts, :context_id, :task_id, :kind,
+                  :metadata, :extensions, :reference_task_ids
+
+      ##
+      # Initialize a new message
+      #
+      # @param message_id [String] Unique message identifier
+      # @param role [String] Message role ("user" or "agent")
+      # @param parts [Array<Part>] Message parts
+      # @param kind [String] Message kind (always "message")
+      # @param context_id [String, nil] Context identifier
+      # @param task_id [String, nil] Associated task identifier
+      # @param metadata [Hash, nil] Additional metadata
+      # @param extensions [Array<Hash>, nil] Protocol extensions
+      # @param reference_task_ids [Array<String>, nil] Referenced task IDs
+      def initialize(message_id:, role:, parts:, kind: KIND_MESSAGE, context_id: nil,
+                     task_id: nil, metadata: nil, extensions: nil, reference_task_ids: nil)
+        @message_id = message_id
+        @role = role
+        @parts = parts.map { |p| p.is_a?(Part) ? p : Part.from_h(p) }
+        @kind = kind
+        @context_id = context_id
+        @task_id = task_id
+        @metadata = metadata
+        @extensions = extensions
+        @reference_task_ids = reference_task_ids
+
+        validate!
+      end
+
+      ##
+      # Get all text content from the message
+      #
+      # @return [String] Combined text from all text parts
+      def text_content
+        @parts.select { |p| p.is_a?(TextPart) }
+              .map(&:text)
+              .join("\n")
+      end
+
+      ##
+      # Get all file parts from the message
+      #
+      # @return [Array<FilePart>] All file parts
+      def file_parts
+        @parts.select { |p| p.is_a?(FilePart) }
+      end
+
+      ##
+      # Get all data parts from the message
+      #
+      # @return [Array<DataPart>] All data parts
+      def data_parts
+        @parts.select { |p| p.is_a?(DataPart) }
+      end
+
+      ##
+      # Add a part to the message
+      #
+      # @param part [Part] The part to add
+      def add_part(part)
+        @parts << part
+      end
+
+      ##
+      # Check if the message is from a user
+      #
+      # @return [Boolean] True if the message is from a user
+      def from_user?
+        @role == ROLE_USER
+      end
+
+      ##
+      # Check if the message is from an agent
+      #
+      # @return [Boolean] True if the message is from an agent
+      def from_agent?
+        @role == ROLE_AGENT
+      end
+
+      private
+
+      def validate!
+        validate_required(:message_id, :role, :parts, :kind)
+        validate_inclusion(:role, VALID_ROLES)
+        validate_inclusion(:kind, [KIND_MESSAGE])
+        validate_array_type(:parts, Part)
+
+        return unless @parts.empty?
+
+        raise ArgumentError, "Message must have at least one part"
+      end
+    end
+  end
+end