simple_acp 0.0.1

data/lib/simple_acp/models/await.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Base class for await requests.
+    #
+    # When an agent needs client input during execution, it creates
+    # an await request describing what input is needed.
+    #
+    # @abstract Subclass for specific await types
+    class AwaitRequest < Base
+      # @!attribute [r] type
+      #   @return [String] await request type
+      attribute :type, required: true
+
+      # Parse from hash, creating the appropriate subclass.
+      #
+      # @param hash [Hash, nil] await request data
+      # @return [AwaitRequest, nil] the request or nil
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        type = hash["type"] || hash[:type]
+
+        case type
+        when "message"
+          MessageAwaitRequest.from_hash(hash)
+        else
+          super
+        end
+      end
+    end
+
+    # Request for a message from the client.
+    #
+    # Used when an agent needs text or other message input to continue.
+    class MessageAwaitRequest < AwaitRequest
+      # @!attribute [r] message
+      #   @return [Message, nil] prompt message to display to client
+      attribute :message
+
+      def initialize(**kwargs)
+        kwargs[:type] = "message"
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = allocate
+        instance.instance_variable_set(:@type, "message")
+
+        if hash["message"] || hash[:message]
+          instance.instance_variable_set(
+            :@message,
+            Message.from_hash(hash["message"] || hash[:message])
+          )
+        end
+
+        instance
+      end
+    end
+
+    # Base class for await resume payloads.
+    #
+    # Clients send resume payloads to continue an awaited run
+    # with the requested input.
+    #
+    # @abstract Subclass for specific resume types
+    class AwaitResume < Base
+      # @!attribute [r] type
+      #   @return [String] resume type
+      attribute :type, required: true
+
+      # Parse from hash, creating the appropriate subclass.
+      #
+      # @param hash [Hash, nil] resume payload data
+      # @return [AwaitResume, nil] the resume or nil
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        type = hash["type"] || hash[:type]
+
+        case type
+        when "message"
+          MessageAwaitResume.from_hash(hash)
+        else
+          super
+        end
+      end
+    end
+
+    # Resume payload containing a message response.
+    #
+    # Used to provide text or other message input to an awaiting run.
+    class MessageAwaitResume < AwaitResume
+      # @!attribute [r] message
+      #   @return [Message, nil] the client's response message
+      attribute :message
+
+      def initialize(**kwargs)
+        kwargs[:type] = "message"
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = allocate
+        instance.instance_variable_set(:@type, "message")
+
+        if hash["message"] || hash[:message]
+          instance.instance_variable_set(
+            :@message,
+            Message.from_hash(hash["message"] || hash[:message])
+          )
+        end
+
+        instance
+      end
+    end
+  end
+end

data/lib/simple_acp/models/base.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Base class for all ACP models providing common serialization.
+    #
+    # Provides a simple DSL for declaring attributes with defaults,
+    # automatic JSON serialization/deserialization, and equality comparisons.
+    #
+    # @example Defining a model
+    #   class MyModel < Base
+    #     attribute :name, required: true
+    #     attribute :count, default: 0
+    #     attribute :tags, default: -> { [] }
+    #   end
+    #
+    # @abstract Subclass and use {.attribute} to define attributes
+    class Base
+      class << self
+        # Define an attribute on this model.
+        #
+        # @param name [Symbol] the attribute name
+        # @param type [Class, nil] optional type hint (for documentation)
+        # @param default [Object, Proc, nil] default value or proc
+        # @param required [Boolean] whether the attribute is required
+        # @return [void]
+        def attribute(name, type: nil, default: nil, required: false)
+          @attributes ||= {}
+          @attributes[name] = { type: type, default: default, required: required }
+
+          attr_reader name
+
+          define_method(:"#{name}=") do |value|
+            instance_variable_set(:"@#{name}", value)
+          end
+        end
+
+        # Get all attributes including inherited ones.
+        #
+        # @return [Hash<Symbol, Hash>] attribute definitions
+        def attributes
+          @attributes ||= {}
+
+          # Inherit attributes from parent class
+          if superclass.respond_to?(:attributes)
+            superclass.attributes.merge(@attributes)
+          else
+            @attributes
+          end
+        end
+
+        # Get only attributes defined on this class (not inherited).
+        #
+        # @return [Hash<Symbol, Hash>] attribute definitions
+        def own_attributes
+          @attributes ||= {}
+        end
+
+        # Create an instance from a hash.
+        #
+        # @param hash [Hash, nil] attribute values (string or symbol keys)
+        # @return [Base, nil] the new instance or nil if hash is nil
+        def from_hash(hash)
+          return nil if hash.nil?
+
+          instance = new
+          attributes.each do |name, _opts|
+            key = name.to_s
+            value = hash.key?(key) ? hash[key] : hash[name]
+            instance.send(:"#{name}=", value) unless value.nil?
+          end
+          instance
+        end
+
+        alias from_h from_hash
+      end
+
+      # Initialize with keyword arguments.
+      #
+      # @param kwargs [Hash] attribute values
+      def initialize(**kwargs)
+        self.class.attributes.each do |name, opts|
+          value = kwargs.fetch(name) { opts[:default].is_a?(Proc) ? opts[:default].call : opts[:default] }
+          instance_variable_set(:"@#{name}", value)
+        end
+      end
+
+      # Convert to a hash for JSON serialization.
+      #
+      # @return [Hash] attribute values (nil values excluded)
+      def to_h
+        self.class.attributes.each_with_object({}) do |(name, _opts), hash|
+          value = send(name)
+          next if value.nil?
+
+          hash[name] = serialize_value(value)
+        end
+      end
+
+      # Convert to JSON string.
+      #
+      # @param args [Array] arguments passed to Hash#to_json
+      # @return [String] JSON representation
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # Check equality based on all attributes.
+      #
+      # @param other [Object] object to compare
+      # @return [Boolean] true if same class and all attributes equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        self.class.attributes.keys.all? do |name|
+          send(name) == other.send(name)
+        end
+      end
+
+      alias eql? ==
+
+      # Compute hash based on all attributes.
+      #
+      # @return [Integer] hash code
+      def hash
+        self.class.attributes.keys.map { |name| send(name) }.hash
+      end
+
+      private
+
+      def serialize_value(value)
+        case value
+        when Base
+          value.to_h
+        when Array
+          value.map { |v| serialize_value(v) }
+        when Hash
+          value.transform_values { |v| serialize_value(v) }
+        when Time
+          value.utc.iso8601
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/simple_acp/models/errors.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Error codes as defined in the ACP specification.
+    module ErrorCode
+      # Internal server error
+      SERVER_ERROR = "server_error"
+      # Invalid input from client
+      INVALID_INPUT = "invalid_input"
+      # Requested resource not found
+      NOT_FOUND = "not_found"
+    end
+
+    # Structured error response following the ACP specification.
+    #
+    # @example Creating an error
+    #   error = Error.server_error("Something went wrong")
+    #   error.code    # => "server_error"
+    #   error.message # => "Something went wrong"
+    class Error
+      # @return [String] error code (server_error, invalid_input, not_found)
+      attr_reader :code
+
+      # @return [String] human-readable error message
+      attr_reader :message
+
+      # @return [Object, nil] additional error data
+      attr_reader :data
+
+      # Create a new error.
+      #
+      # @param code [String] error code
+      # @param message [String] error message
+      # @param data [Object, nil] additional data
+      def initialize(code:, message:, data: nil)
+        @code = code
+        @message = message
+        @data = data
+      end
+
+      # Convert to hash for JSON serialization.
+      #
+      # @return [Hash] error as hash
+      def to_h
+        hash = {
+          code: @code,
+          message: @message
+        }
+        hash[:data] = @data if @data
+        hash
+      end
+
+      # Convert to JSON string.
+      #
+      # @param args [Array] arguments passed to Hash#to_json
+      # @return [String] JSON representation
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # Create from a hash (JSON deserialization).
+      #
+      # @param hash [Hash] error data
+      # @return [Error] the error
+      def self.from_hash(hash)
+        new(
+          code: hash["code"] || hash[:code],
+          message: hash["message"] || hash[:message],
+          data: hash["data"] || hash[:data]
+        )
+      end
+
+      # Create a server error.
+      #
+      # @param message [String] error message
+      # @param data [Object, nil] additional data
+      # @return [Error] the error
+      def self.server_error(message, data: nil)
+        new(code: ErrorCode::SERVER_ERROR, message: message, data: data)
+      end
+
+      # Create an invalid input error.
+      #
+      # @param message [String] error message
+      # @param data [Object, nil] additional data
+      # @return [Error] the error
+      def self.invalid_input(message, data: nil)
+        new(code: ErrorCode::INVALID_INPUT, message: message, data: data)
+      end
+
+      # Create a not found error.
+      #
+      # @param message [String] error message
+      # @param data [Object, nil] additional data
+      # @return [Error] the error
+      def self.not_found(message, data: nil)
+        new(code: ErrorCode::NOT_FOUND, message: message, data: data)
+      end
+    end
+  end
+end

data/lib/simple_acp/models/events.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Base class for all Server-Sent Events (SSE).
+    #
+    # Events are streamed during run execution to provide
+    # real-time updates on progress and output.
+    #
+    # @abstract Subclass and set type in initializer
+    class Event < Base
+      # @!attribute [r] type
+      #   @return [String] event type (see Types::EventType)
+      attribute :type, required: true
+
+      # Format for Server-Sent Events protocol.
+      #
+      # @return [String] SSE-formatted event
+      def sse_format
+        "event: #{@type}\ndata: #{to_json}\n\n"
+      end
+    end
+
+    # Message created event
+    class MessageCreatedEvent < Event
+      attribute :message
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::MESSAGE_CREATED
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["message"] || hash[:message]
+          instance.message = Message.from_hash(hash["message"] || hash[:message])
+        end
+        instance
+      end
+    end
+
+    # Message part event (for streaming individual parts)
+    class MessagePartEvent < Event
+      attribute :part
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::MESSAGE_PART
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["part"] || hash[:part]
+          instance.part = MessagePart.from_hash(hash["part"] || hash[:part])
+        end
+        instance
+      end
+    end
+
+    # Message completed event
+    class MessageCompletedEvent < Event
+      attribute :message
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::MESSAGE_COMPLETED
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["message"] || hash[:message]
+          instance.message = Message.from_hash(hash["message"] || hash[:message])
+        end
+        instance
+      end
+    end
+
+    # Run created event
+    class RunCreatedEvent < Event
+      attribute :run
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::RUN_CREATED
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["run"] || hash[:run]
+          instance.run = Run.from_hash(hash["run"] || hash[:run])
+        end
+        instance
+      end
+    end
+
+    # Run in-progress event
+    class RunInProgressEvent < Event
+      attribute :run_id
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::RUN_IN_PROGRESS
+        super
+      end
+    end
+
+    # Run awaiting event
+    class RunAwaitingEvent < Event
+      attribute :run_id
+      attribute :await_request
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::RUN_AWAITING
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["await_request"] || hash[:await_request]
+          instance.await_request = AwaitRequest.from_hash(hash["await_request"] || hash[:await_request])
+        end
+        instance
+      end
+    end
+
+    # Run completed event
+    class RunCompletedEvent < Event
+      attribute :run
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::RUN_COMPLETED
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["run"] || hash[:run]
+          instance.run = Run.from_hash(hash["run"] || hash[:run])
+        end
+        instance
+      end
+    end
+
+    # Run cancelled event
+    class RunCancelledEvent < Event
+      attribute :run_id
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::RUN_CANCELLED
+        super
+      end
+    end
+
+    # Run failed event
+    class RunFailedEvent < Event
+      attribute :run_id
+      attribute :error
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::RUN_FAILED
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["error"] || hash[:error]
+          instance.error = Error.from_hash(hash["error"] || hash[:error])
+        end
+        instance
+      end
+    end
+
+    # Generic event
+    class GenericEvent < Event
+      attribute :data
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::GENERIC
+        super
+      end
+    end
+
+    # Error event
+    class ErrorEvent < Event
+      attribute :error
+
+      def initialize(**kwargs)
+        kwargs[:type] = Types::EventType::ERROR
+        super
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+        if hash["error"] || hash[:error]
+          instance.error = Error.from_hash(hash["error"] || hash[:error])
+        end
+        instance
+      end
+    end
+
+    # Factory module for parsing events from hashes.
+    module Events
+      # Mapping of event types to classes
+      EVENT_CLASSES = {
+        Types::EventType::MESSAGE_CREATED => MessageCreatedEvent,
+        Types::EventType::MESSAGE_PART => MessagePartEvent,
+        Types::EventType::MESSAGE_COMPLETED => MessageCompletedEvent,
+        Types::EventType::RUN_CREATED => RunCreatedEvent,
+        Types::EventType::RUN_IN_PROGRESS => RunInProgressEvent,
+        Types::EventType::RUN_AWAITING => RunAwaitingEvent,
+        Types::EventType::RUN_COMPLETED => RunCompletedEvent,
+        Types::EventType::RUN_CANCELLED => RunCancelledEvent,
+        Types::EventType::RUN_FAILED => RunFailedEvent,
+        Types::EventType::GENERIC => GenericEvent,
+        Types::EventType::ERROR => ErrorEvent
+      }.freeze
+
+      # Parse an event from a hash.
+      #
+      # @param hash [Hash, nil] event data with "type" key
+      # @return [Event, nil] the appropriate event subclass or nil
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        type = hash["type"] || hash[:type]
+        klass = EVENT_CLASSES[type] || GenericEvent
+        klass.from_hash(hash)
+      end
+
+      # Parse JSON SSE data.
+      #
+      # @param data [String] JSON string
+      # @return [Hash, nil] parsed hash or nil if invalid
+      def self.parse_sse(data)
+        JSON.parse(data)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end