simple_acp 0.0.1

data/lib/simple_acp/storage/postgresql.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Storage
+    # PostgreSQL-backed storage for persistent deployments.
+    #
+    # Stores data in PostgreSQL using the Sequel gem.
+    # Automatically creates required tables on first use.
+    #
+    # @example
+    #   storage = SimpleAcp::Storage::PostgreSQL.new(
+    #     url: "postgres://localhost/simple_acp"
+    #   )
+    #   server = SimpleAcp::Server::Base.new(storage: storage)
+    class PostgreSQL < Base
+      # Initialize PostgreSQL storage.
+      #
+      # @param options [Hash] configuration options
+      # @option options [Sequel::Database] :db existing Sequel connection
+      # @option options [String] :url database URL (default: $DATABASE_URL or localhost)
+      # @option options [Boolean] :skip_setup skip automatic table creation
+      # @option options [String] :host database host
+      # @option options [Integer] :port database port
+      # @option options [String] :database database name
+      # @option options [String] :user database user
+      # @option options [String] :password database password
+      def initialize(options = {})
+        super
+        @db = options[:db] || connect_db(options)
+        setup_tables unless options[:skip_setup]
+      end
+
+      # @see Base#get_run
+      def get_run(run_id)
+        row = @db[:acp_runs].where(run_id: run_id).first
+        return nil unless row
+
+        deserialize_run(row)
+      end
+
+      # @see Base#save_run
+      def save_run(run)
+        data = {
+          run_id: run.run_id,
+          agent_name: run.agent_name,
+          session_id: run.session_id,
+          status: run.status,
+          output: run.output.to_json,
+          error: run.error&.to_json,
+          await_request: run.await_request&.to_json,
+          created_at: run.created_at,
+          finished_at: run.finished_at,
+          updated_at: Time.now
+        }
+
+        if @db[:acp_runs].where(run_id: run.run_id).count.positive?
+          @db[:acp_runs].where(run_id: run.run_id).update(data)
+        else
+          @db[:acp_runs].insert(data)
+        end
+
+        run
+      end
+
+      # @see Base#delete_run
+      def delete_run(run_id)
+        @db[:acp_events].where(run_id: run_id).delete
+        @db[:acp_runs].where(run_id: run_id).delete
+      end
+
+      # @see Base#list_runs
+      def list_runs(agent_name: nil, session_id: nil, limit: 10, offset: 0)
+        dataset = @db[:acp_runs]
+        dataset = dataset.where(agent_name: agent_name) if agent_name
+        dataset = dataset.where(session_id: session_id) if session_id
+
+        total = dataset.count
+        rows = dataset.order(Sequel.desc(:created_at)).limit(limit).offset(offset).all
+
+        {
+          runs: rows.map { |row| deserialize_run(row) },
+          total: total
+        }
+      end
+
+      # @see Base#get_session
+      def get_session(session_id)
+        row = @db[:acp_sessions].where(id: session_id).first
+        return nil unless row
+
+        deserialize_session(row)
+      end
+
+      # @see Base#save_session
+      def save_session(session)
+        data = {
+          id: session.id,
+          history: session.history.to_json,
+          state: session.state&.to_json,
+          updated_at: Time.now
+        }
+
+        if @db[:acp_sessions].where(id: session.id).count.positive?
+          @db[:acp_sessions].where(id: session.id).update(data)
+        else
+          data[:created_at] = Time.now
+          @db[:acp_sessions].insert(data)
+        end
+
+        session
+      end
+
+      # @see Base#delete_session
+      def delete_session(session_id)
+        @db[:acp_sessions].where(id: session_id).delete
+      end
+
+      # @see Base#add_event
+      def add_event(run_id, event)
+        @db[:acp_events].insert(
+          run_id: run_id,
+          event_type: event.type,
+          data: event.to_json,
+          created_at: Time.now
+        )
+        event
+      end
+
+      # @see Base#get_events
+      def get_events(run_id, limit: 100, offset: 0)
+        rows = @db[:acp_events]
+          .where(run_id: run_id)
+          .order(:created_at)
+          .limit(limit)
+          .offset(offset)
+          .all
+
+        rows.map { |row| Models::Events.from_hash(JSON.parse(row[:data])) }
+      end
+
+      # @see Base#close
+      def close
+        @db.disconnect if @db.respond_to?(:disconnect)
+      end
+
+      # @see Base#ping
+      def ping
+        @db.test_connection
+      rescue StandardError
+        false
+      end
+
+      # Clear all stored data.
+      #
+      # @return [void]
+      def clear!
+        @db[:acp_events].delete
+        @db[:acp_runs].delete
+        @db[:acp_sessions].delete
+      end
+
+      private
+
+      def connect_db(options)
+        require "sequel"
+        Sequel.connect(
+          options[:url] || ENV.fetch("DATABASE_URL", "postgres://localhost/acp"),
+          **options.slice(:host, :port, :database, :user, :password)
+        )
+      end
+
+      def setup_tables
+        @db.create_table?(:acp_runs) do
+          String :run_id, primary_key: true
+          String :agent_name, null: false, index: true
+          String :session_id, index: true
+          String :status, null: false
+          Text :output
+          Text :error
+          Text :await_request
+          DateTime :created_at
+          DateTime :finished_at
+          DateTime :updated_at
+        end
+
+        @db.create_table?(:acp_sessions) do
+          String :id, primary_key: true
+          Text :history
+          Text :state
+          DateTime :created_at
+          DateTime :updated_at
+        end
+
+        @db.create_table?(:acp_events) do
+          primary_key :id
+          String :run_id, null: false, index: true
+          String :event_type, null: false
+          Text :data
+          DateTime :created_at
+        end
+      end
+
+      def deserialize_run(row)
+        output = row[:output] ? JSON.parse(row[:output]).map { |m| Models::Message.from_hash(m) } : []
+        error = row[:error] ? Models::Error.from_hash(JSON.parse(row[:error])) : nil
+        await_request = row[:await_request] ? Models::AwaitRequest.from_hash(JSON.parse(row[:await_request])) : nil
+
+        run = Models::Run.new(
+          run_id: row[:run_id],
+          agent_name: row[:agent_name],
+          session_id: row[:session_id],
+          status: row[:status]
+        )
+        run.instance_variable_set(:@output, output)
+        run.instance_variable_set(:@error, error)
+        run.instance_variable_set(:@await_request, await_request)
+        run.instance_variable_set(:@created_at, row[:created_at])
+        run.instance_variable_set(:@finished_at, row[:finished_at])
+        run
+      end
+
+      def deserialize_session(row)
+        history = row[:history] ? JSON.parse(row[:history]).map { |m| Models::Message.from_hash(m) } : []
+        state = row[:state] ? JSON.parse(row[:state]) : nil
+
+        session = Models::Session.new(id: row[:id])
+        session.instance_variable_set(:@history, history)
+        session.instance_variable_set(:@state, state)
+        session
+      end
+    end
+  end
+end

data/lib/simple_acp/storage/redis.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  module Storage
+    # Redis-backed storage for distributed deployments.
+    #
+    # Stores data in Redis with configurable TTL for automatic expiration.
+    # Suitable for multi-process or multi-server deployments.
+    #
+    # @example
+    #   storage = SimpleAcp::Storage::Redis.new(
+    #     url: "redis://localhost:6379",
+    #     ttl: 3600  # 1 hour
+    #   )
+    #   server = SimpleAcp::Server::Base.new(storage: storage)
+    class Redis < Base
+      # Default TTL of 24 hours
+      DEFAULT_TTL = 86_400
+
+      # Default key prefix
+      KEY_PREFIX = "acp:"
+
+      # Initialize Redis storage.
+      #
+      # @param options [Hash] configuration options
+      # @option options [Redis] :redis existing Redis connection
+      # @option options [String] :url Redis URL (default: $REDIS_URL or localhost)
+      # @option options [Integer] :ttl TTL in seconds (default: 86400)
+      # @option options [String] :prefix key prefix (default: "acp:")
+      # @option options [String] :host Redis host
+      # @option options [Integer] :port Redis port
+      # @option options [Integer] :db Redis database number
+      # @option options [String] :password Redis password
+      # @option options [Boolean] :ssl use SSL
+      def initialize(options = {})
+        super
+        @redis = options[:redis] || connect_redis(options)
+        @ttl = options[:ttl] || DEFAULT_TTL
+        @prefix = options[:prefix] || KEY_PREFIX
+      end
+
+      # @see Base#get_run
+      def get_run(run_id)
+        data = @redis.get(run_key(run_id))
+        return nil unless data
+
+        Models::Run.from_hash(JSON.parse(data))
+      end
+
+      # @see Base#save_run
+      def save_run(run)
+        @redis.setex(run_key(run.run_id), @ttl, run.to_json)
+
+        # Index by agent name
+        @redis.sadd(agent_runs_key(run.agent_name), run.run_id)
+
+        # Index by session if present
+        if run.session_id
+          @redis.sadd(session_runs_key(run.session_id), run.run_id)
+        end
+
+        run
+      end
+
+      # @see Base#delete_run
+      def delete_run(run_id)
+        run = get_run(run_id)
+        return unless run
+
+        @redis.del(run_key(run_id))
+        @redis.del(events_key(run_id))
+        @redis.srem(agent_runs_key(run.agent_name), run_id)
+        @redis.srem(session_runs_key(run.session_id), run_id) if run.session_id
+      end
+
+      # @see Base#list_runs
+      def list_runs(agent_name: nil, session_id: nil, limit: 10, offset: 0)
+        run_ids = if agent_name
+                    @redis.smembers(agent_runs_key(agent_name))
+                  elsif session_id
+                    @redis.smembers(session_runs_key(session_id))
+                  else
+                    @redis.keys("#{@prefix}run:*").map { |k| k.sub("#{@prefix}run:", "") }
+                  end
+
+        runs = run_ids.filter_map { |id| get_run(id) }
+        runs = runs.sort_by { |r| r.created_at || Time.at(0) }.reverse
+
+        {
+          runs: runs.drop(offset).take(limit),
+          total: runs.length
+        }
+      end
+
+      # @see Base#get_session
+      def get_session(session_id)
+        data = @redis.get(session_key(session_id))
+        return nil unless data
+
+        Models::Session.from_hash(JSON.parse(data))
+      end
+
+      # @see Base#save_session
+      def save_session(session)
+        @redis.setex(session_key(session.id), @ttl, session.to_json)
+        session
+      end
+
+      # @see Base#delete_session
+      def delete_session(session_id)
+        @redis.del(session_key(session_id))
+      end
+
+      # @see Base#add_event
+      def add_event(run_id, event)
+        @redis.rpush(events_key(run_id), event.to_json)
+        @redis.expire(events_key(run_id), @ttl)
+        event
+      end
+
+      # @see Base#get_events
+      def get_events(run_id, limit: 100, offset: 0)
+        events_data = @redis.lrange(events_key(run_id), offset, offset + limit - 1)
+        events_data.map { |data| Models::Events.from_hash(JSON.parse(data)) }
+      end
+
+      # @see Base#close
+      def close
+        @redis.close if @redis.respond_to?(:close)
+      end
+
+      # @see Base#ping
+      def ping
+        @redis.ping == "PONG"
+      rescue StandardError
+        false
+      end
+
+      # Clear all stored data.
+      #
+      # @return [void]
+      def clear!
+        keys = @redis.keys("#{@prefix}*")
+        @redis.del(*keys) unless keys.empty?
+      end
+
+      private
+
+      def connect_redis(options)
+        require "redis"
+        ::Redis.new(
+          url: options[:url] || ENV.fetch("REDIS_URL", "redis://localhost:6379"),
+          **options.slice(:host, :port, :db, :password, :ssl)
+        )
+      end
+
+      def run_key(run_id)
+        "#{@prefix}run:#{run_id}"
+      end
+
+      def session_key(session_id)
+        "#{@prefix}session:#{session_id}"
+      end
+
+      def events_key(run_id)
+        "#{@prefix}events:#{run_id}"
+      end
+
+      def agent_runs_key(agent_name)
+        "#{@prefix}agent_runs:#{agent_name}"
+      end
+
+      def session_runs_key(session_id)
+        "#{@prefix}session_runs:#{session_id}"
+      end
+    end
+  end
+end

data/lib/simple_acp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SimpleAcp
+  VERSION = "0.0.1"
+end

data/lib/simple_acp.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "securerandom"
+require "concurrent"
+
+require_relative "simple_acp/version"
+
+# Models
+require_relative "simple_acp/models/errors"
+require_relative "simple_acp/models/types"
+require_relative "simple_acp/models/base"
+require_relative "simple_acp/models/metadata"
+require_relative "simple_acp/models/message_part"
+require_relative "simple_acp/models/message"
+require_relative "simple_acp/models/run"
+require_relative "simple_acp/models/agent_manifest"
+require_relative "simple_acp/models/session"
+require_relative "simple_acp/models/events"
+require_relative "simple_acp/models/await"
+
+# Storage
+require_relative "simple_acp/storage/base"
+require_relative "simple_acp/storage/memory"
+
+# Server
+require_relative "simple_acp/server/context"
+require_relative "simple_acp/server/agent"
+require_relative "simple_acp/server/app"
+require_relative "simple_acp/server/base"
+
+# Client
+require_relative "simple_acp/client/sse"
+require_relative "simple_acp/client/base"
+
+# Ruby implementation of the Agent Communication Protocol (ACP).
+# Provides server and client implementations for AI agent communication
+# with support for synchronous, asynchronous, and streaming execution modes.
+#
+# @example Creating a server
+#   server = SimpleAcp::Server::Base.new
+#   server.agent("echo", description: "Echoes input") do |context|
+#     SimpleAcp::Models::Message.agent(context.input.first.text_content)
+#   end
+#   server.run(port: 8000)
+#
+# @example Using the client
+#   client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+#   run = client.run_sync(agent: "echo", input: "Hello!")
+#   puts run.output.first.text_content
+#
+# @see https://github.com/i-am-bee/acp Agent Communication Protocol specification
+module SimpleAcp
+  # Base error class for all SimpleAcp exceptions
+  class Error < StandardError; end
+
+  # Raised when there is a configuration problem
+  class ConfigurationError < Error; end
+
+  # Raised when input validation fails
+  class ValidationError < Error; end
+
+  # Raised when a requested resource is not found
+  class NotFoundError < Error; end
+
+  # Raised when a run fails during execution
+  class RunError < Error; end
+
+  class << self
+    # @return [Logger, nil] optional logger for debugging
+    attr_accessor :logger
+
+    # Configure the SimpleAcp module
+    #
+    # @yield [self] yields self for configuration
+    # @return [void]
+    #
+    # @example
+    #   SimpleAcp.configure do |config|
+    #     config.logger = Logger.new(STDOUT)
+    #   end
+    def configure
+      yield self if block_given?
+    end
+  end
+end
+
+# Convenience top-level aliases (outside the SimpleAcp module to avoid constant conflicts)
+SimpleAcpServer = SimpleAcp::Server::Base
+SimpleAcpClient = SimpleAcp::Client::Base

data/mkdocs.yml

@@ -0,0 +1,152 @@
+site_name: SimpleAcp Documentation
+site_description: "Ruby implementation of the Agent Communication Protocol (ACP) for AI agent communication"
+site_author: "Dewayne VanHoozer"
+site_url: "https://madbomber.github.io/simple_acp/"
+
+repo_name: "MadBomber/simple_acp"
+repo_url: "https://github.com/MadBomber/simple_acp"
+edit_uri: "edit/main/docs/"
+
+theme:
+  name: material
+  language: en
+
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"\`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: MadBomber
+      repo: simple_acp
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  version: 0.1.0
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/simple_acp
+      name: GitHub Repository
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/simple_acp
+      name: RubyGems
+  generator: false
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - getting-started/index.md
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quick-start.md
+    - Configuration: getting-started/configuration.md
+  - Examples: examples.md
+  - Core Concepts:
+    - core-concepts/index.md
+    - Messages: core-concepts/messages.md
+    - Agents: core-concepts/agents.md
+    - Runs: core-concepts/runs.md
+    - Sessions: core-concepts/sessions.md
+    - Events: core-concepts/events.md
+  - Server Guide:
+    - server/index.md
+    - Creating Agents: server/creating-agents.md
+    - Streaming Responses: server/streaming.md
+    - Multi-Turn Conversations: server/multi-turn.md
+    - HTTP Endpoints: server/http-endpoints.md
+  - Client Guide:
+    - client/index.md
+    - Sync & Async: client/sync-async.md
+    - Streaming: client/streaming.md
+    - Session Management: client/sessions.md
+  - Storage Backends:
+    - storage/index.md
+    - Memory: storage/memory.md
+    - Redis: storage/redis.md
+    - PostgreSQL: storage/postgresql.md
+    - Custom Backends: storage/custom.md
+  - API Reference:
+    - api/index.md
+    - Server::Base: api/server-base.md
+    - Client::Base: api/client-base.md
+    - Models: api/models.md
+    - Storage: api/storage.md
+
+copyright: Copyright © 2025 Dewayne VanHoozer

data/sig/simple_acp.rbs

@@ -0,0 +1,4 @@
+module SimpleAcp
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end