a2a 0.1.0.pre → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5f7029c9c5b7b7925240beddbfc4dc0a948cad67eab64cb73bc847be68f113c
-  data.tar.gz: 4a78ebd646ce8069bc0abf1c67399cc27a8ee0e998ebec8d42fd24f9c392222f
+  metadata.gz: a735724d190d582f29a71d683d2e9c0eff95ff3ec90dd77e29ef3f091e7c8338
+  data.tar.gz: 7af91cf7fe7e0a112654a016955139672a47f3e55fe2bbfe4a66019a7b82dda1
 SHA512:
-  metadata.gz: a7cf7fcd88e1032144ed16f369387ac085c58acb866ccab9519896b5cc7b2081aa154fe91fdf7f315e9c12d1ca7cd38e7e74e4f0471c5669345db7f0dcdfdefe
-  data.tar.gz: fe0cb28b59d9d82a19629843bb4d4616049f85abb74e7d522778815260d2d8d73acb290ce7e9bbb35df7679428956515816ffc2043528da497820b03b686fe5b
+  metadata.gz: 7569e210cb5c08ec6c18dc612a8690472ce117b7aaac15ded258a314dc33cc82b0cf845d0a4d1be3a0cc3cdc36872f478db6f0955ed3c34e3b45e85886a0c31d
+  data.tar.gz: ccb3d85eccdc0934d52b76f2b4b7bcbc598e16a3fbc8d4e1c24c67600708923e5b25bfdf75776bab7217703aa772424ace4a0f2865952fe2a2f112df71425e6a

data/.rubocop.yml

@@ -1,4 +1,5 @@
 plugins:
+  - rubocop-factory_bot
   - rubocop-performance
   - rubocop-rake
   - rubocop-rspec
@@ -15,6 +16,10 @@ Gemspec/DevelopmentDependencies:
 
 # ----------------------- Style -----------------------
 
+Style/MixinUsage:
+  Exclude:
+    - bin/console
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: single_quotes
@@ -28,23 +33,39 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
   Exclude:
-    - hsr.gemspec
+    - a2a.gemspec
 
 # ---------------------- Metrics ----------------------
 
+Metrics/AbcSize:
+  Enabled: false
+
 Metrics/BlockLength:
-  Exclude:
-    - '**/*_spec.rb'
-    - hsr.gemspec
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
 
 Metrics/ParameterLists:
   CountKeywordArgs: false
 
+Metrics/PerceivedComplexity:
+  Enabled: false
+
 # ----------------------- RSpec -----------------------
 
 RSpec/ExampleLength:
   Enabled: false
 
+RSpec/MultipleExpectations:
+  Enabled: false
+
 # RuboCop does not like the gem's name.
 RSpec/SpecFilePathFormat:
   Enabled: false

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.2
+ruby 3.4.3

data/CHANGELOG.md

@@ -1,5 +1,22 @@
-## [Unreleased]
+# Changelog
+All notable changes to this project will be documented in this file.
 
-## [0.1.0.pre] - 2025-03-08
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.1.1/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-05-03
+
+### Added
+
+- Protocol data structures defined according to the Agent2Agent specification
+- Serialization and deserialization of protocol messages
+- Typed data structures with validation
+- Case transformation support (snake_case ↔ camelCase) during instantiation and serialization
+- Flexible schema with support for additional properties beyond defined attributes
+
+## [0.1.0.pre] - 2025-04-08
 
 - Pre-release
+
+[0.1.0]: https://github.com/wilsonsilva/a2a/compare/v0.1.0.pre...0.1.0
+[0.1.0.pre]: https://github.com/wilsonsilva/a2a/compare/a20b9b6...v0.1.0.pre

data/Guardfile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 guard 'bundler' do
-  watch('hsr.gemspec')
+  watch('a2a.gemspec')
 end
 
 guard 'bundler_audit', run_on_start: true do

data/README.md

@@ -2,8 +2,8 @@
 
 [![Gem Version](https://badge.fury.io/rb/a2a.svg)](https://badge.fury.io/rb/a2a)
 ![Build](https://github.com/wilsonsilva/a2a/actions/workflows/main.yml/badge.svg)
-[![Maintainability](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/maintainability)](https://codeclimate.com/github/wilsonsilva/a2a/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/test_coverage)](https://codeclimate.com/github/wilsonsilva/a2a/test_coverage)
+[![Maintainability](https://qlty.sh/badges/73ebc4bb-d1db-4b5b-9a7c-a4acd59dfe69/maintainability.svg)](https://qlty.sh/gh/wilsonsilva/projects/a2a)
+[![Code Coverage](https://qlty.sh/badges/73ebc4bb-d1db-4b5b-9a7c-a4acd59dfe69/test_coverage.svg)](https://qlty.sh/gh/wilsonsilva/projects/a2a)
 
 An open protocol enabling communication and interoperability between opaque agentic applications.
 
@@ -21,7 +21,11 @@ An open protocol enabling communication and interoperability between opaque agen
 
 ## 🔑 Key features
 
-TODO
+- Protocol data structures defined according to the Agent2Agent specification
+- Serialization and deserialization of protocol messages
+- Typed data structures with validation
+- Case transformation support (snake_case ↔ camelCase) during instantiation and serialization
+- Flexible schema with support for additional properties beyond defined attributes
 
 ## 📦 Installation
 
@@ -31,7 +35,48 @@ Install the gem by executing:
 
 ## ⚡️ Quickstart
 
-TODO
+```ruby
+require 'a2a'
+
+# Create a task send parameters object
+task_params = A2A::TaskSendParams.new(
+  id: 'task-123',
+  session_id: 'session-456',
+  message: {
+    content: 'Plan a trip to Paris',
+    role: 'user'
+  }
+)
+
+# Build a JSON-RPC request object (no actual network request is made)
+request = A2A::SendTaskRequest.new(
+  id: 1,
+  params: task_params
+)
+
+# Convert to JSON with camelCase formatting (as per protocol spec)
+json_request = request.to_json
+puts json_request
+# => {"jsonrpc":"2.0","id":1,"method":"tasks/send","params":{"id":"task-123","sessionId":"session-456","message":{"content":"Plan a trip to Paris","role":"user"}}}
+
+# Parse a JSON response string
+agent_response = '{"jsonrpc":"2.0","id":1,"result":{"id":"task-123","status":"success","history":[{"role":"user","content":"Plan a trip to Paris"}]}}'
+
+# Method 1: Parse the JSON first, then create the object
+response_data = JSON.parse(agent_response)
+response = A2A::SendTaskResponse.new(response_data)
+
+# Method 2: Directly create the object from JSON (using the new from_json method)
+response = A2A::SendTaskResponse.from_json(agent_response)
+
+# Access the task information
+if response.result
+  puts "Task status: #{response.result.status}"
+  puts "Messages: #{response.result.history&.length || 0}"
+else
+  puts "Error: #{response.error&.message}"
+end
+```
 
 ## 📚 Documentation
 

data/lib/a2a/extensions/additional_properties.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module A2A
+  module Extensions
+    # Allows a dry-struct to have additional properties beyond the defined schema.
+    # Limitations: the +attributes+ method does not return additional properties.
+    module AdditionalProperties
+      # @!visibility private
+      # @return [Hash] Storage for additional properties not defined in the schema
+      attr_reader :additional_properties
+
+      # @!visibility private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Initialize with empty additional properties
+      def initialize(*)
+        super
+        @additional_properties ||= {}
+      end
+
+      # Access additional properties via method_missing
+      #
+      # @param method_name [Symbol] Method name corresponding to property
+      # @param args [Array] Method arguments (unused)
+      #
+      # @return [Object, nil] Property value if found
+      #
+      def method_missing(method_name, *args)
+        if additional_properties.key?(method_name)
+          additional_properties[method_name]
+        else
+          super
+        end
+      end
+
+      # Indicate whether the object responds to the given method
+      #
+      # @param method_name [Symbol] Method name
+      # @param include_private [Boolean] Whether to include private methods
+      #
+      # @return [Boolean] Whether the object responds to the method
+      #
+      def respond_to_missing?(method_name, include_private = false)
+        additional_properties.key?(method_name) || super
+      end
+
+      # Convert the struct to a hash, including additional properties
+      #
+      # @return [Hash] All properties as a hash
+      #
+      def to_h
+        super.merge(additional_properties)
+      end
+
+      # Override the camelize method to handle additional properties correctly
+      #
+      # @param value [Object] The value to convert
+      #
+      # @return [Object] The value with camelized keys if applicable
+      #
+      def camelize(value)
+        case value
+        when Hash
+          value.to_h do |key, v|
+            [INFLECTOR.camelize_lower(key.to_s).to_sym, camelize(v)]
+          end
+        when Array
+          value.map { |item| camelize(item) }
+        else
+          value
+        end
+      end
+
+      # Class methods added to the class that includes AdditionalProperties
+      module ClassMethods
+        # Override the new method to handle additional properties
+        #
+        # @param hash [Hash, nil] Input hash including both schema and additional properties
+        #
+        # @return [Object] New instance with additional properties preserved
+        #
+        def new(hash = nil)
+          hash = {} if hash.nil?
+
+          # Convert all keys to symbols
+          input = hash.transform_keys(&:to_sym)
+
+          # Get schema keys
+          schema_keys = schema.keys.map(&:name)
+
+          # Split input into schema data and additional properties
+          schema_data = {}
+          additional_props = {}
+
+          input.each do |key, value|
+            snake_key = INFLECTOR.underscore(key.to_s).to_sym
+
+            if schema_keys.include?(snake_key)
+              schema_data[snake_key] = value
+            elsif schema_keys.include?(key)
+              schema_data[key] = value
+            else
+              # Store additional properties with snake_case keys
+              additional_props[snake_key] = value
+            end
+          end
+
+          # Create instance using schema data
+          instance = super(schema_data)
+
+          # Attach additional properties
+          instance.instance_variable_set(:@additional_properties, additional_props)
+
+          instance
+        end
+      end
+    end
+  end
+end

data/lib/a2a/extensions/case_transformation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module A2A
+  module Extensions
+    # Allows a dry-struct to be instantiated and serialized with camelCase keys.
+    module CaseTransformation
+      def self.included(base)
+        base.class_eval do
+          # Transform keys to snake_case symbols when initializing the struct
+          transform_keys { |key| INFLECTOR.underscore(key.to_s).to_sym }
+        end
+      end
+
+      # Converts hash keys from snake_case to camelCase recursively
+      #
+      # @param value [Object] The value to convert
+      #
+      # @return [Object] The value with camelized keys if applicable
+      #
+      def camelize(value)
+        case value
+        when Array
+          value.map { |item| camelize(item) }
+        when Hash
+          value.to_h do |key, v|
+            [INFLECTOR.camelize_lower(key.to_s).to_sym, camelize(v)]
+          end
+        else
+          value
+        end
+      end
+
+      # Serializes the object to JSON with an option for camelCase formatting
+      #
+      # @param camel_case [Boolean] Whether to convert keys to camelCase
+      #
+      # @return [String] JSON representation of the object
+      #
+      def to_json(camel_case: true, **)
+        data = to_h
+        data = camelize(data) if camel_case
+        data.to_json(**)
+      end
+    end
+  end
+end

data/lib/a2a/extensions/json_deserialization.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module A2A
+  module Extensions
+    # Provides JSON deserialization capabilities to a class
+    module JSONDeserialization
+      # @!visibility private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods added to the class that includes JsonDeserialization
+      module ClassMethods
+        # Creates a new instance from a JSON string
+        #
+        # @param json [String] JSON string to parse
+        # @return [ProtocolStruct] A new instance of the appropriate class
+        #
+        # @example Create a Google Maps Agent Card from JSON
+        #   json_string = <<~JSON
+        #     {
+        #       "name": "Google Maps Agent",
+        #       "description": "Plan routes, remember places, and generate directions",
+        #       "url": "https://maps-agent.google.com",
+        #       "provider": {
+        #         "organization": "Google",
+        #         "url": "https://google.com"
+        #       },
+        #       "version": "1.0.0",
+        #       "capabilities": {
+        #         "streaming": true,
+        #         "pushNotifications": false
+        #       },
+        #       "skills": [
+        #         {
+        #           "id": "route-planner",
+        #           "name": "Route planning",
+        #           "description": "Helps plan routing between two locations"
+        #         }
+        #       ]
+        #     }
+        #   JSON
+        #   agent_card = A2A::AgentCard.from_json(json_string)
+        #
+        def from_json(json)
+          new(JSON.parse(json))
+        end
+      end
+    end
+  end
+end

data/lib/a2a/types/agent_authentication.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines the authentication schemes and credentials for an agent.
+  class AgentAuthentication < ProtocolStruct
+    # @return [Array<String>] List of supported authentication schemes.
+    attribute :schemes, Types::Array.of(Types::String)
+
+    # @return [String, nil] Credentials for authentication. Can be a string (e.g., token) or null if not
+    # required initially.
+    attribute? :credentials, Types::String.optional
+  end
+end

data/lib/a2a/types/agent_capabilities.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # Describes the capabilities of an agent.
+  class AgentCapabilities < ProtocolStruct
+    # @return [Boolean] Indicates if the agent supports streaming responses.
+    attribute? :streaming, Types::Bool.default(false)
+
+    # @return [Boolean] Indicates if the agent supports push notification mechanisms.
+    attribute? :push_notifications, Types::Bool.default(false)
+
+    # @return [Boolean] Indicates if the agent supports providing state transition history.
+    attribute? :state_transition_history, Types::Bool.default(false)
+  end
+end

data/lib/a2a/types/agent_card.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents the metadata card for an agent, describing its properties and capabilities.
+  class AgentCard < ProtocolStruct
+    # @return [String] The name of the agent.
+    attribute :name, Types::String
+
+    # @return [String, nil] An optional description of the agent.
+    attribute? :description, Types::String.optional
+
+    # @return [String] The base URL endpoint for interacting with the agent.
+    attribute :url, Types::String
+
+    # @return [AgentProvider, nil] Information about the provider of the agent.
+    attribute? :provider, Types::Constructor(AgentProvider).optional
+
+    # @return [String] The version identifier for the agent or its API.
+    attribute :version, Types::String
+
+    # @return [String, nil] An optional URL pointing to the agent's documentation.
+    attribute? :documentation_url, Types::String.optional
+
+    # @return [AgentCapabilities] The capabilities supported by the agent.
+    attribute :capabilities, Types::Constructor(AgentCapabilities)
+
+    # @return [AgentAuthentication, nil] Authentication details required to interact with the agent.
+    attribute? :authentication, Types::Constructor(AgentAuthentication).optional
+
+    # @return [Array<String>] Default input modes supported by the agent (e.g., 'text', 'file', 'json').
+    attribute? :default_input_modes, Types::Array.of(Types::String).default(['text'].freeze)
+
+    # @return [Array<String>] Default output modes supported by the agent (e.g., 'text', 'file', 'json').
+    attribute? :default_output_modes, Types::Array.of(Types::String).default(['text'].freeze)
+
+    # @return [Array<AgentSkill>] List of specific skills offered by the agent.
+    attribute :skills, Types::Array.of(Types::Constructor(AgentSkill))
+  end
+end

data/lib/a2a/types/agent_provider.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents the provider or organization behind an agent.
+  class AgentProvider < ProtocolStruct
+    # @return [String] The name of the organization providing the agent.
+    attribute :organization, Types::String
+
+    # @return [String, nil] URL associated with the agent provider.
+    attribute? :url, Types::String.optional
+  end
+end

data/lib/a2a/types/agent_skill.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines a specific skill or capability offered by an agent.
+  class AgentSkill < ProtocolStruct
+    # @return [String] Unique identifier for the skill.
+    attribute :id, Types::String
+
+    # @return [String] Human-readable name of the skill.
+    attribute :name, Types::String
+
+    # @return [String, nil] Optional description of the skill.
+    attribute? :description, Types::String.optional
+
+    # @return [Array<String>, nil] Optional list of tags associated with the skill for categorization.
+    attribute? :tags, Types::Array.of(Types::String).optional
+
+    # @return [Array<String>, nil] Optional list of example inputs or use cases for the skill.
+    attribute? :examples, Types::Array.of(Types::String).optional
+
+    # @return [Array<String>, nil] Optional list of input modes supported by this skill, overriding agent defaults.
+    attribute? :input_modes, Types::Array.of(Types::String).optional
+
+    # @return [Array<String>, nil] Optional list of output modes supported by this skill, overriding agent defaults.
+    attribute? :output_modes, Types::Array.of(Types::String).optional
+  end
+end

data/lib/a2a/types/artifact.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents an artifact generated or used by a task, potentially composed of multiple parts.
+  class Artifact < ProtocolStruct
+    # @return [String, nil] Optional name for the artifact.
+    attribute? :name, Types::String.optional
+
+    # @return [String, nil] Optional description of the artifact.
+    attribute? :description, Types::String.optional
+
+    # @return [Array<Part>] The constituent parts of the artifact.
+    attribute :parts, Types::Array.of(Types::Constructor(Part))
+
+    # @return [Integer, nil] Optional index for ordering artifacts, especially relevant in streaming or updates.
+    attribute? :index, Types::Integer.default(0)
+
+    # @return [Boolean, nil] Optional flag indicating if this artifact content should append to previous
+    # content (for streaming).
+    attribute? :append, Types::Bool.optional
+
+    # @return [Hash, nil] Optional metadata associated with the artifact.
+    attribute? :metadata, Types::Hash.optional
+
+    # @return [Boolean, nil] Optional flag indicating if this is the last chunk of data for this
+    # artifact (for streaming).
+    attribute? :last_chunk, Types::Bool.optional
+  end
+end

data/lib/a2a/types/authentication_info.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module A2A
+  # Authentication information, potentially including additional properties beyond the standard ones.
+  # (Note: Schema allows additional properties).
+  class AuthenticationInfo < AgentAuthentication
+    include Extensions::AdditionalProperties
+  end
+end

data/lib/a2a/types/cancel_task_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # Request to cancel a currently running task.
+  class CancelTaskRequest < JSONRPCRequest
+    # @return [String] Method name for canceling a task.
+    attribute :method, Types::String.constant('tasks/cancel')
+
+    # @return [TaskIdParams] Parameters for the cancel task method.
+    attribute :params, Types::Constructor(TaskIdParams)
+
+    # @return [String] Method name for canceling a task.
+    def method = attributes[:method]
+  end
+end

data/lib/a2a/types/cancel_task_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Response to a `tasks/cancel` request. Contains the updated Task object or an error.
+  class CancelTaskResponse < JSONRPCResponse
+    # @return [Task, nil] The canceled task information if successful.
+    attribute? :result, Types::Constructor(Task).optional
+
+    # @return [JSONRPCError, nil] Error information if the request failed.
+    attribute? :error, Types::Constructor(JSONRPCError).optional
+  end
+end

data/lib/a2a/types/data_part.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a part of a message containing structured data (JSON).
+  class DataPart < ProtocolStruct
+    # @return [String] Type identifier for this part.
+    attribute :type, Types::String.constant('data')
+
+    # @return [Hash] The structured data content as a JSON object.
+    attribute :data, Types::Hash
+
+    # @return [Hash, nil] Optional metadata associated with this data part.
+    attribute? :metadata, Types::Hash.optional
+  end
+end

data/lib/a2a/types/error_codes.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module A2A
+  # Standard JSON-RPC error codes
+  module ErrorCodes
+    # Invalid JSON was received by the server
+    PARSE_ERROR = -32_700
+    # The JSON sent is not a valid Request object
+    INVALID_REQUEST = -32_600
+    # The method does not exist / is not available
+    METHOD_NOT_FOUND = -32_601
+    # Invalid method parameter(s)
+    INVALID_PARAMS = -32_602
+    # Internal JSON-RPC error
+    INTERNAL_ERROR = -32_603
+
+    # The specified task was not found
+    TASK_NOT_FOUND = -32_001
+    # The specified task cannot be canceled
+    TASK_NOT_CANCELABLE = -32_002
+    # Push Notifications are not supported for this operation or agent
+    PUSH_NOTIFICATION_NOT_SUPPORTED = -32_003
+    # The requested operation is not supported by the agent
+    UNSUPPORTED_OPERATION = -32_004
+  end
+end

data/lib/a2a/types/file_content.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents the content of a file, either as base64 encoded bytes or a URI.
+  class FileContent < ProtocolStruct
+    # @return [String, nil] Optional name of the file.
+    attribute? :name, Types::String.optional
+
+    # @return [String, nil] Optional MIME type of the file content.
+    attribute? :mime_type, Types::String.optional
+
+    # @return [String, nil] File content encoded as a Base64 string. Use this OR `uri`.
+    attribute? :bytes, Types::String.optional
+
+    # @return [String, nil] URI pointing to the file content. Use this OR `bytes`.
+    attribute? :uri, Types::String.optional
+  end
+end

data/lib/a2a/types/file_part.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a part of a message containing file content.
+  class FilePart < ProtocolStruct
+    # @return [String] Type identifier for this part.
+    attribute :type, Types::String.constant('file')
+
+    # @return [FileContent] The file content, provided either inline or via URI.
+    attribute :file, Types::Constructor(FileContent)
+
+    # @return [Hash, nil] Optional metadata associated with this file part.
+    attribute? :metadata, Types::Hash.optional
+  end
+end