simple_acp 0.0.1

data/lib/simple_acp/models/message.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Fundamental communication structure in ACP.
+    #
+    # Messages represent units of communication between users and agents,
+    # containing one or more parts (text, JSON, images, etc.).
+    #
+    # @example Creating a simple text message
+    #   msg = Message.user("Hello, world!")
+    #
+    # @example Creating a message with multiple parts
+    #   msg = Message.agent(
+    #     MessagePart.text("Here's the data:"),
+    #     MessagePart.json({ count: 42 })
+    #   )
+    class Message < Base
+      # @!attribute [r] role
+      #   @return [String] "user" or "agent" (or "agent/name")
+      attribute :role, required: true
+
+      # @!attribute [r] parts
+      #   @return [Array<MessagePart>] content parts
+      attribute :parts, default: -> { [] }
+
+      # @!attribute [r] created_at
+      #   @return [Time, nil] when the message was created
+      attribute :created_at
+
+      # @!attribute [r] completed_at
+      #   @return [Time, nil] when the message was completed
+      attribute :completed_at
+
+      def initialize(**kwargs)
+        super
+        @parts ||= []
+        @created_at ||= Time.now
+      end
+
+      # Create from a hash (JSON deserialization).
+      #
+      # @param hash [Hash, nil] message data
+      # @return [Message, nil] the message or nil
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = allocate
+        instance.send(:initialize_from_hash, hash)
+        instance
+      end
+
+      # Create a user message from content.
+      #
+      # @param contents [Array<String, MessagePart, Hash>] message content
+      # @return [Message] the user message
+      #
+      # @example
+      #   Message.user("Hello!")
+      #   Message.user(MessagePart.text("Hello"), MessagePart.json({key: "value"}))
+      def self.user(*contents)
+        parts = contents.map do |content|
+          case content
+          when MessagePart
+            content
+          when String
+            MessagePart.text(content)
+          when Hash
+            MessagePart.from_hash(content)
+          else
+            MessagePart.json(content)
+          end
+        end
+
+        new(role: Types::Role::USER, parts: parts)
+      end
+
+      # Create an agent message from content.
+      #
+      # @param contents [Array<String, MessagePart, Hash>] message content
+      # @return [Message] the agent message
+      #
+      # @example
+      #   Message.agent("Hello, I'm your assistant!")
+      def self.agent(*contents)
+        parts = contents.map do |content|
+          case content
+          when MessagePart
+            content
+          when String
+            MessagePart.text(content)
+          when Hash
+            MessagePart.from_hash(content)
+          else
+            MessagePart.json(content)
+          end
+        end
+
+        new(role: Types::Role::AGENT, parts: parts)
+      end
+
+      # Check if this is a user message.
+      #
+      # @return [Boolean] true if role is "user"
+      def user?
+        @role == Types::Role::USER
+      end
+
+      # Check if this is an agent message.
+      #
+      # @return [Boolean] true if role is "agent" or starts with "agent/"
+      def agent?
+        @role == Types::Role::AGENT || @role.to_s.start_with?("agent/")
+      end
+
+      # Get the agent name if this is a named agent message.
+      #
+      # @return [String, nil] agent name extracted from "agent/name" role
+      def agent_name
+        return nil unless agent?
+
+        if @role.to_s.start_with?("agent/")
+          @role.to_s.sub("agent/", "")
+        end
+      end
+
+      # Add a part to this message.
+      #
+      # @param part [MessagePart, Hash] the part to add
+      # @return [self] for chaining
+      def add_part(part)
+        @parts << (part.is_a?(MessagePart) ? part : MessagePart.from_hash(part))
+        self
+      end
+
+      # Mark the message as completed.
+      #
+      # @return [self] for chaining
+      def complete!
+        @completed_at = Time.now
+        self
+      end
+
+      # Check if the message is completed.
+      #
+      # @return [Boolean] true if completed_at is set
+      def completed?
+        !@completed_at.nil?
+      end
+
+      # Combine two messages by appending parts.
+      #
+      # @param other [Message] message to append
+      # @return [Message] new combined message
+      def +(other)
+        combined = self.class.new(role: @role, parts: @parts.dup)
+        other.parts.each { |p| combined.add_part(p) }
+        combined
+      end
+
+      # Get combined text content from all text parts.
+      #
+      # @return [String] concatenated text content
+      def text_content
+        @parts.select(&:text?).map(&:content).join("\n")
+      end
+
+      # Create a new message with adjacent text parts combined.
+      #
+      # @return [Message] compressed message
+      def compress
+        return self if @parts.length <= 1
+
+        compressed_parts = []
+        current_text = nil
+
+        @parts.each do |part|
+          if part.text? && !part.base64_encoded?
+            if current_text
+              current_text = MessagePart.text("#{current_text.content}\n#{part.content}")
+            else
+              current_text = part.dup
+            end
+          else
+            compressed_parts << current_text if current_text
+            current_text = nil
+            compressed_parts << part
+          end
+        end
+
+        compressed_parts << current_text if current_text
+
+        self.class.new(role: @role, parts: compressed_parts, created_at: @created_at)
+      end
+
+      # Validate the message.
+      #
+      # @return [Boolean] true if role is valid, has parts, and all parts are valid
+      def valid?
+        return false unless Types::Role.valid?(@role)
+        return false if @parts.empty?
+        return false unless @parts.all?(&:valid?)
+
+        true
+      end
+
+      # Convert to string representation.
+      #
+      # @return [String] concatenated string representation of all parts
+      def to_s
+        @parts.map(&:to_s).join("\n")
+      end
+
+      private
+
+      def initialize_from_hash(hash)
+        @role = hash["role"] || hash[:role]
+        @created_at = parse_time(hash["created_at"] || hash[:created_at])
+        @completed_at = parse_time(hash["completed_at"] || hash[:completed_at])
+
+        parts_data = hash["parts"] || hash[:parts] || []
+        @parts = parts_data.map { |p| MessagePart.from_hash(p) }
+      end
+
+      def parse_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/simple_acp/models/message_part.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module SimpleAcp
+  module Models
+    # Individual content unit within a Message.
+    #
+    # Message parts can contain text, JSON, images, or URL references.
+    # Each part has a content type (MIME type) and either inline content
+    # or a URL reference.
+    #
+    # @example Text part
+    #   part = MessagePart.text("Hello, world!")
+    #
+    # @example JSON part
+    #   part = MessagePart.json({ key: "value" })
+    #
+    # @example Image from base64
+    #   part = MessagePart.image(base64_data, mime_type: "image/png")
+    #
+    # @example URL reference
+    #   part = MessagePart.from_url("https://example.com/image.png", content_type: "image/png")
+    class MessagePart < Base
+      # @!attribute [r] name
+      #   @return [String, nil] optional name for the part
+      attribute :name
+
+      # @!attribute [r] content_type
+      #   @return [String] MIME type (e.g., "text/plain", "application/json")
+      attribute :content_type, required: true
+
+      # @!attribute [r] content
+      #   @return [String, nil] inline content (mutually exclusive with content_url)
+      attribute :content
+
+      # @!attribute [r] content_encoding
+      #   @return [String] "plain" or "base64"
+      attribute :content_encoding, default: Types::ContentEncoding::PLAIN
+
+      # @!attribute [r] content_url
+      #   @return [String, nil] URL reference (mutually exclusive with content)
+      attribute :content_url
+
+      # @!attribute [r] metadata
+      #   @return [CitationMetadata, TrajectoryMetadata, nil] optional metadata
+      attribute :metadata
+
+      def initialize(**kwargs)
+        super
+        validate!
+      end
+
+      # Create from a hash (JSON deserialization).
+      #
+      # @param hash [Hash, nil] part data
+      # @return [MessagePart, nil] the part or nil
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = allocate
+        instance.send(:initialize_from_hash, hash)
+        instance
+      end
+
+      # Create a plain text message part.
+      #
+      # @param content [String] the text content
+      # @param name [String, nil] optional name
+      # @return [MessagePart] the text part
+      def self.text(content, name: nil)
+        new(
+          content_type: "text/plain",
+          content: content,
+          name: name
+        )
+      end
+
+      # Create a JSON message part.
+      #
+      # @param data [Hash, Array, String] JSON data (will be serialized if not string)
+      # @param name [String, nil] optional name
+      # @return [MessagePart] the JSON part
+      def self.json(data, name: nil)
+        new(
+          content_type: "application/json",
+          content: data.is_a?(String) ? data : data.to_json,
+          name: name
+        )
+      end
+
+      # Create an image message part from base64 data.
+      #
+      # @param data [String] base64-encoded image data
+      # @param mime_type [String] image MIME type (default: "image/png")
+      # @param name [String, nil] optional name
+      # @return [MessagePart] the image part
+      def self.image(data, mime_type: "image/png", name: nil)
+        new(
+          content_type: mime_type,
+          content: data,
+          content_encoding: Types::ContentEncoding::BASE64,
+          name: name
+        )
+      end
+
+      # Create a message part referencing a URL.
+      #
+      # @param url [String] the URL to reference
+      # @param content_type [String] the content type at the URL
+      # @param name [String, nil] optional name
+      # @return [MessagePart] the URL reference part
+      def self.from_url(url, content_type:, name: nil)
+        new(
+          content_type: content_type,
+          content_url: url,
+          name: name
+        )
+      end
+
+      # Check if this is a text content part.
+      #
+      # @return [Boolean] true if content_type starts with "text/"
+      def text?
+        @content_type&.start_with?("text/")
+      end
+
+      # Check if this is a JSON content part.
+      #
+      # @return [Boolean] true if content_type is "application/json"
+      def json?
+        @content_type == "application/json"
+      end
+
+      # Check if this is an image content part.
+      #
+      # @return [Boolean] true if content_type starts with "image/"
+      def image?
+        @content_type&.start_with?("image/")
+      end
+
+      # Check if content is base64 encoded.
+      #
+      # @return [Boolean] true if content_encoding is "base64"
+      def base64_encoded?
+        @content_encoding == Types::ContentEncoding::BASE64
+      end
+
+      # Check if this part references a URL.
+      #
+      # @return [Boolean] true if content_url is set
+      def url_reference?
+        !@content_url.nil?
+      end
+
+      # Get decoded content (decodes base64 if needed).
+      #
+      # @return [String] decoded content
+      def decoded_content
+        return @content unless base64_encoded?
+
+        Base64.decode64(@content)
+      end
+
+      # Parse JSON content into Ruby objects.
+      #
+      # @return [Hash, Array, nil] parsed JSON or nil if not JSON
+      def parsed_json
+        return nil unless json?
+
+        JSON.parse(@content)
+      end
+
+      # Validate the message part.
+      #
+      # @return [Boolean] true if content_type is set and has content or URL (not both)
+      def valid?
+        return false if @content_type.nil?
+        return false if @content.nil? && @content_url.nil?
+        return false if @content && @content_url
+
+        true
+      end
+
+      # Convert to string representation.
+      #
+      # @return [String] content for text, URL for references, or "<type>" placeholder
+      def to_s
+        return @content if text?
+        return @content_url if url_reference?
+
+        "<#{@content_type}>"
+      end
+
+      private
+
+      def initialize_from_hash(hash)
+        @name = hash["name"] || hash[:name]
+        @content_type = hash["content_type"] || hash[:content_type]
+        @content = hash["content"] || hash[:content]
+        @content_encoding = hash["content_encoding"] || hash[:content_encoding] || Types::ContentEncoding::PLAIN
+        @content_url = hash["content_url"] || hash[:content_url]
+
+        metadata_hash = hash["metadata"] || hash[:metadata]
+        if metadata_hash
+          kind = metadata_hash["kind"] || metadata_hash[:kind]
+          @metadata = case kind
+                      when "citation"
+                        CitationMetadata.from_hash(metadata_hash)
+                      when "trajectory"
+                        TrajectoryMetadata.from_hash(metadata_hash)
+                      end
+        end
+
+        validate!
+      end
+
+      def validate!
+        if @content && @content_url
+          raise SimpleAcp::ValidationError, "MessagePart cannot have both content and content_url"
+        end
+      end
+    end
+  end
+end

data/lib/simple_acp/models/metadata.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Models
+    # Citation metadata for source attribution
+    class CitationMetadata < Base
+      attribute :kind, default: "citation"
+      attribute :start_index
+      attribute :end_index
+      attribute :url
+      attribute :title
+      attribute :description
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+        return nil unless hash["kind"] == "citation" || hash[:kind] == "citation"
+
+        super
+      end
+    end
+
+    # Trajectory metadata for tracking multi-step reasoning
+    class TrajectoryMetadata < Base
+      attribute :kind, default: "trajectory"
+      attribute :message
+      attribute :tool_name
+      attribute :tool_input
+      attribute :tool_output
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+        return nil unless hash["kind"] == "trajectory" || hash[:kind] == "trajectory"
+
+        super
+      end
+    end
+
+    # Author information
+    class Author < Base
+      attribute :name, required: true
+      attribute :email
+      attribute :url
+    end
+
+    # Contributor information (same structure as Author)
+    class Contributor < Base
+      attribute :name, required: true
+      attribute :email
+      attribute :url
+    end
+
+    # Link to external resources
+    class Link < Base
+      attribute :type, required: true
+      attribute :url, required: true
+
+      def valid?
+        Types::LinkType::ALL.include?(@type) && Types.valid_url?(@url)
+      end
+    end
+
+    # Dependency declaration
+    class Dependency < Base
+      attribute :type, required: true
+      attribute :name, required: true
+
+      def valid?
+        Types::DependencyType::ALL.include?(@type)
+      end
+    end
+
+    # Agent capability
+    class Capability < Base
+      attribute :name, required: true
+      attribute :description, required: true
+    end
+
+    # Annotations for platform-specific metadata
+    class Annotations < Base
+      attribute :beeai_ui
+      attribute :extra, default: -> { {} }
+
+      def [](key)
+        @extra[key]
+      end
+
+      def []=(key, value)
+        @extra[key] = value
+      end
+
+      def to_h
+        hash = super
+        @extra&.each { |k, v| hash[k] = v }
+        hash
+      end
+    end
+
+    # Agent status metrics
+    class AgentStatus < Base
+      attribute :average_tokens
+      attribute :average_run_time
+      attribute :success_rate
+    end
+
+    # Full agent metadata
+    class Metadata < Base
+      attribute :annotations
+      attribute :documentation
+      attribute :license
+      attribute :programming_language
+      attribute :natural_languages, default: -> { [] }
+      attribute :framework
+      attribute :capabilities, default: -> { [] }
+      attribute :domains, default: -> { [] }
+      attribute :tags, default: -> { [] }
+      attribute :created_at
+      attribute :updated_at
+      attribute :author
+      attribute :contributors, default: -> { [] }
+      attribute :links, default: -> { [] }
+      attribute :dependencies, default: -> { [] }
+      attribute :recommended_models, default: -> { [] }
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        instance = super
+
+        if hash["annotations"] || hash[:annotations]
+          instance.annotations = Annotations.from_hash(hash["annotations"] || hash[:annotations])
+        end
+
+        if hash["author"] || hash[:author]
+          instance.author = Author.from_hash(hash["author"] || hash[:author])
+        end
+
+        if hash["contributors"] || hash[:contributors]
+          contributors = hash["contributors"] || hash[:contributors]
+          instance.contributors = contributors.map { |c| Contributor.from_hash(c) }
+        end
+
+        if hash["capabilities"] || hash[:capabilities]
+          capabilities = hash["capabilities"] || hash[:capabilities]
+          instance.capabilities = capabilities.map { |c| Capability.from_hash(c) }
+        end
+
+        if hash["links"] || hash[:links]
+          links = hash["links"] || hash[:links]
+          instance.links = links.map { |l| Link.from_hash(l) }
+        end
+
+        if hash["dependencies"] || hash[:dependencies]
+          dependencies = hash["dependencies"] || hash[:dependencies]
+          instance.dependencies = dependencies.map { |d| Dependency.from_hash(d) }
+        end
+
+        instance
+      end
+    end
+  end
+end