hermes-client 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43e89034ffc51c50bf49f73ad2bb1b26d74c924c543ce26a95f25523310375b8
-  data.tar.gz: 618f19001d44ccfac6b0f97a1f7b0757b4743a09c6eab9feb4cc082f5654c4a6
+  metadata.gz: 0c8205d1a6aed4260e80ca3d351772791025195265b92a883b379a1f697c098a
+  data.tar.gz: 66bc29e492989c686d9866633e119b5cd2bdc2a4c8b1cc8fc34a0d9dc8b9d615
 SHA512:
-  metadata.gz: d3368a4b8a47c703e8e1ae31b7306b7d9da99b92d3663bc58a04692709e28af7b83020f0b2554a52d1b4ed6cc44907f079342a34db8115897e7665a744ba35a8
-  data.tar.gz: 431bbd67359fc7ce185b276e6030dd2ee30d923ed18a34ef9513ea0aca93b026786f72a7c40320b8521f51470d802bfd54d4281eefe12cd4a68a4e2ab61c9b4b
+  metadata.gz: 741e6c38b1937b260ddd206449ba5bf6095eb3f3ad037ba569a6eed6cc924c5b734805fc9ede3a043bc21359dc95a32f4abb1f2a55d89118ec1267d16c029da1
+  data.tar.gz: b006e53068f75e41434c913105956dac7335b1a49427daa82e7b29dd537152ec9decc50ef506d739378c3f5df20f9429cd9ce09b120f03c6f853c8a9fea3f829

data/.yardopts

@@ -0,0 +1,11 @@
+--no-private
+--title=HermesAgent::Client
+--markup=markdown
+--markup-provider redcarpet
+--main=README.md
+./lib/hermes_agent/**/*.rb
+./lib/hermes-client.rb
+-
+README.md
+LICENSE.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History
+
+### v0.1.0 / 2026-05-26
+
+Initial release (alpha quality)

data/LICENSE.md

@@ -0,0 +1,21 @@
+# License
+
+Copyright 2026 Daniel Azuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/README.md

@@ -1,9 +1,107 @@
-# Placeholder for hermes-client
+# Hermes-Client
 
-This is a placeholder gem, which was generated on 2026-05-22 to
-reserve the gem "hermes-client".
-The actual gem is planned for release in the near future.
+`hermes-client` is a Ruby client library for the Hermes Agent API Server.
 
-If this is a problem, or if the actual gem has not been released
-in a timely manner, you can contact the owner at
-`dazuma@gmail.com`.
+## Getting started
+
+Install the gem using
+
+```sh
+gem install hermes-client
+```
+
+Or add it to your bundle:
+
+```ruby
+# In your Gemfile
+gem "hermes-client"
+```
+
+Create and use a client object:
+
+```ruby
+require "hermes-client"
+
+# Create a new client and point it at a Hermes Gateway server
+hermes_client = HermesAgent::Client.new(
+  base_url: "http://localhost:8642",
+  api_key: "my-key-12345678"
+)
+
+# Send chat messages to the gateway
+response = hermes_client.responses.create(input: "Tell me a joke.")
+puts response.output_text
+
+# Manage jobs
+briefing_job = hermes_client.jobs.create(
+  name: "daily-briefing",
+  schedule: "every morning at 8am",
+  prompt: "Collect the day's news and email me a summary."
+)
+puts "Daily-briefing will next run at #{briefing_job.next_run_at}"
+```
+
+A client is not thread-safe (it holds a persistent connection); create one
+client per thread.
+
+For more information, see the
+[Hermes Gateway API documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server).
+
+Full API documentation is available at https://dazuma.github.io/hermes-client
+for released gems.
+
+## Requirements and status
+
+`hermes-client` requires Ruby 3.4 or later.
+
+The gem can be considered alpha quality. Initial development is complete, but
+the library has seen minimal real-world testing, and it may experience
+significant changes, including breaking interface changes. It is available now
+on an experimental basis, but not currently recommended for production use.
+
+## Contributing
+
+Development is done in GitHub at https://github.com/dazuma/hermes-client.
+
+ *  To file issues: https://github.com/dazuma/hermes-client/issues.
+ *  For questions and discussion, please do not file an issue. Instead, use the
+    discussions feature: https://github.com/dazuma/hermes-client/discussions.
+ *  Before opening any non-trivial pull request, please report a bug or feature
+    request using an issue.
+
+The library uses [toys](https://dazuma.github.io/toys) for testing and CI. To
+run the test suite, `gem install toys` and then run `toys ci`. You can also run
+unit tests, rubocop, and build tests independently.
+
+As of late May, 2026, the documentation provided by Hermes is fairly thin, and
+the developer had to cobble together an understanding of the API interfaces and
+protocols from various sources, including the Hermes source and empirical
+probing of a live gateway. Documents related to our findings are available in
+the `devdocs` directory, and some Toys-based probing tools are also included in
+this repository. (These are not included in the gem distribution.)
+
+Much of the heavy lifting in the original implementation and documentation, as
+well as the research behind it into the actual behavior of the gateway API, was
+done in close collaboration with Claude Code (Opus 4.7).
+
+## License
+
+Copyright 2026 Daniel Azuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/lib/hermes-client.rb

@@ -1,8 +1,3 @@
-#
-# This is a placeholder Ruby file for gem "hermes-client".
-# It was generated on 2026-05-22 to reserve the gem name.
-# The actual gem is planned for release in the near future.
-# If this is a problem, or if the actual gem has not been
-# released in a timely manner, you can contact the owner at
-# dazuma@gmail.com
-#
+# frozen_string_literal: true
+
+require "hermes_agent/client"

data/lib/hermes_agent/client/configuration.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module HermesAgent
+  class Client
+    ##
+    # Connection settings for a {HermesAgent::Client}.
+    #
+    # Holds the server location and credentials shared by all requests. An
+    # instance is created when a client is constructed and may be customized
+    # either via keyword arguments or by yielding the configuration to a block.
+    #
+    class Configuration
+      ##
+      # The default server root URL.
+      # @return [String]
+      #
+      DEFAULT_BASE_URL = "http://127.0.0.1:8642"
+
+      ##
+      # The default keep-alive timeout, in seconds.
+      # @return [Numeric]
+      #
+      DEFAULT_KEEP_ALIVE_TIMEOUT = 5
+
+      ##
+      # Create a configuration.
+      #
+      # @param base_url [String] The server root URL, _without_ a path prefix
+      #     such as `/v1`. Defaults to {DEFAULT_BASE_URL}.
+      # @param api_key [String, nil] The bearer token sent on every request, or
+      #     `nil` to send no `Authorization` header. Defaults to the
+      #     `HERMES_API_KEY` environment variable.
+      # @param read_timeout [Numeric, nil] The read timeout in seconds, or `nil`
+      #     for no client-side limit.
+      # @param open_timeout [Numeric, nil] The connection-open timeout in
+      #     seconds, or `nil` for no client-side limit.
+      # @param write_timeout [Numeric, nil] The timeout in seconds for writing
+      #     a request, or `nil` for no client-side limit.
+      # @param keep_alive_timeout [Numeric] How long, in seconds, an idle
+      #     persistent connection may be reused before it is considered stale
+      #     and reopened on the next request. Defaults to
+      #     {DEFAULT_KEEP_ALIVE_TIMEOUT}.
+      #
+      def initialize(base_url: DEFAULT_BASE_URL,
+                     api_key: ::ENV.fetch("HERMES_API_KEY", nil),
+                     read_timeout: nil,
+                     open_timeout: nil,
+                     write_timeout: nil,
+                     keep_alive_timeout: DEFAULT_KEEP_ALIVE_TIMEOUT)
+        @base_url = base_url
+        @api_key = api_key
+        @read_timeout = read_timeout
+        @open_timeout = open_timeout
+        @write_timeout = write_timeout
+        @keep_alive_timeout = keep_alive_timeout
+      end
+
+      ##
+      # The server root URL, without a path prefix.
+      # @return [String]
+      #
+      attr_accessor :base_url
+
+      ##
+      # The bearer token sent on every request, or `nil` for none.
+      # @return [String, nil]
+      #
+      attr_accessor :api_key
+
+      ##
+      # The read timeout in seconds, or `nil` for no client-side limit.
+      # @return [Numeric, nil]
+      #
+      attr_accessor :read_timeout
+
+      ##
+      # The connection-open timeout in seconds, or `nil` for no client-side
+      # limit.
+      # @return [Numeric, nil]
+      #
+      attr_accessor :open_timeout
+
+      ##
+      # The request-write timeout in seconds, or `nil` for no client-side
+      # limit.
+      # @return [Numeric, nil]
+      #
+      attr_accessor :write_timeout
+
+      ##
+      # How long, in seconds, an idle persistent connection may be reused before
+      # it is considered stale and reopened on the next request.
+      # @return [Numeric]
+      #
+      attr_accessor :keep_alive_timeout
+    end
+  end
+end

data/lib/hermes_agent/client/conversation.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module HermesAgent
+  class Client
+    ##
+    # A stateful, multi-turn conversation over the Responses API that chains its
+    # turns automatically, so each call takes only the turn's `input:`.
+    #
+    # Construct one via {Resources::Responses#conversation} rather than directly:
+    #
+    #     convo = client.responses.conversation
+    #     convo.create(input: "Hello").output_text
+    #     convo.create(input: "And what about X?").output_text  # auto-chains
+    #
+    # There are two chaining mechanisms, selected at construction:
+    #
+    # - **id-tracking mode** (the default): the conversation remembers each
+    #   turn's response id client-side and threads it into the next turn as
+    #   `previous_response_id`. Pass `previous_response_id:` to resume such a
+    #   thread from a known id (e.g. across process restarts).
+    # - **named mode** (`name:`): every turn sends a stable `conversation` name
+    #   and the server keeps the thread; no client-side id is threaded.
+    #
+    # The verb methods mirror {Resources::Responses} ({#create} /
+    # {#stream_create}) and return the same entities and stream, so the helper
+    # is a drop-in. {#last_response_id} is recorded in both modes for
+    # inspection or persistence.
+    #
+    # A conversation models a single sequential thread and is not thread-safe:
+    # issue and (for streaming) consume one turn before starting the next.
+    #
+    class Conversation
+      ##
+      # Create a conversation. Prefer {Resources::Responses#conversation}.
+      #
+      # @param responses [Resources::Responses] The responses resource to issue
+      #     turns through.
+      # @param name [String, nil] A conversation name for server-side chaining.
+      #     Mutually exclusive with `previous_response_id`.
+      # @param previous_response_id [String, nil] A prior response id to seed
+      #     client-side chaining from. Mutually exclusive with `name`.
+      # @raise [ArgumentError] If both `name` and `previous_response_id` are
+      #     given (they select different chaining mechanisms).
+      #
+      # @private
+      def initialize(responses, name: nil, previous_response_id: nil)
+        raise ::ArgumentError, "name and previous_response_id are mutually exclusive" if name && previous_response_id
+
+        @responses = responses
+        @name = name
+        @last_response_id = previous_response_id
+      end
+
+      ##
+      # The conversation name, in named mode; `nil` in id-tracking mode.
+      # @return [String, nil]
+      #
+      attr_reader :name
+
+      ##
+      # The id of the most recent turn's response (also the seed id before any
+      # turn, in id-tracking mode). In named mode it is recorded for inspection
+      # but not used for chaining.
+      # @return [String, nil]
+      #
+      attr_reader :last_response_id
+
+      ##
+      # Create the next turn in the conversation.
+      #
+      # @param input [String, Array<Hash>] The turn's input (see
+      #     {Resources::Responses#create}).
+      # @param extra [Hash] Additional request-body fields merged into the body.
+      # @return [Entities::Response] The response. Its id becomes
+      #     {#last_response_id}.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def create(input:, **extra)
+        response = @responses.create(input: input, **chaining, **extra)
+        capture(response)
+        response
+      end
+
+      ##
+      # Create the next turn, streaming its events. Follows the same
+      # block-or-enumerator contract as {Resources::Responses#stream_create}:
+      # with a block, each event is yielded and the assembled
+      # {Entities::Response} is returned; without one, a {Stream} is returned.
+      # In either case the turn's response id is captured into
+      # {#last_response_id} when the stream's result is built (during
+      # consumption), so a subsequent turn chains onto it.
+      #
+      # @param input [String, Array<Hash>] The turn's input.
+      # @param extra [Hash] Additional request-body fields merged into the body.
+      # @yieldparam event [Entities::ResponseStreamEvent] Each streamed event.
+      # @return [Entities::Response, Stream] The assembled response when a block
+      #     is given, otherwise the {Stream}.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def stream_create(input:, **extra, &)
+        @responses.stream_response(
+          on_result: method(:capture), input: input, **chaining, **extra, &
+        )
+      end
+
+      private
+
+      ##
+      # The chaining fields for the next turn: the conversation name in named
+      # mode, the tracked previous response id in id-tracking mode, or none.
+      #
+      # @return [Hash]
+      #
+      def chaining
+        return {conversation: @name} if @name
+        return {previous_response_id: @last_response_id} if @last_response_id
+
+        {}
+      end
+
+      ##
+      # Record a turn's response id as {#last_response_id}, ignoring a missing
+      # id (which would otherwise drop a previously tracked one).
+      #
+      # @param response [Entities::Response, nil] The turn's response.
+      # @return [void]
+      #
+      def capture(response)
+        id = response&.id
+        @last_response_id = id if id
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/entities/capabilities.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entity"
+
+module HermesAgent
+  class Client
+    module Entities
+      ##
+      # The authentication scheme advertised by the server
+      # ({Capabilities#auth}).
+      #
+      class Auth < Entity
+        ##
+        # The authentication type, e.g. `"bearer"`.
+        # @return [String, nil]
+        #
+        def type
+          self["type"]
+        end
+
+        ##
+        # Whether authentication is required.
+        # @return [boolean, nil]
+        #
+        def required?
+          self["required"]
+        end
+      end
+
+      ##
+      # The server's execution model ({Capabilities#runtime}).
+      #
+      class Runtime < Entity
+        ##
+        # The runtime mode, e.g. `"server_agent"`.
+        # @return [String, nil]
+        #
+        def mode
+          self["mode"]
+        end
+
+        ##
+        # Where tools execute, e.g. `"server"`.
+        # @return [String, nil]
+        #
+        def tool_execution
+          self["tool_execution"]
+        end
+
+        ##
+        # Whether the runtime is split between client and server. A runtime
+        # that does not advertise this is treated as not split (`false`).
+        # @return [boolean]
+        #
+        def split_runtime?
+          !!self["split_runtime"]
+        end
+
+        ##
+        # A human-readable description of the runtime.
+        # @return [String, nil]
+        #
+        def description
+          self["description"]
+        end
+      end
+
+      ##
+      # The server's feature matrix ({Capabilities#features}).
+      #
+      # Each reader returns whether the server advertises that feature: `true`
+      # when the flag is set, `false` when it is unset or absent (an
+      # unadvertised feature is treated as unsupported). Readers are
+      # best-effort; use {#[]} / {#to_h} for any feature not yet modeled here.
+      #
+      class Features < Entity
+        ##
+        # Whether the chat-completions endpoint is supported.
+        # @return [boolean]
+        #
+        def chat_completions?
+          !!self["chat_completions"]
+        end
+
+        ##
+        # Whether chat-completions streaming is supported.
+        # @return [boolean]
+        #
+        def chat_completions_streaming?
+          !!self["chat_completions_streaming"]
+        end
+
+        ##
+        # Whether the Responses API is supported.
+        # @return [boolean]
+        #
+        def responses_api?
+          !!self["responses_api"]
+        end
+
+        ##
+        # Whether Responses API streaming is supported.
+        # @return [boolean]
+        #
+        def responses_streaming?
+          !!self["responses_streaming"]
+        end
+
+        ##
+        # Whether run submission is supported.
+        # @return [boolean]
+        #
+        def run_submission?
+          !!self["run_submission"]
+        end
+
+        ##
+        # Whether run status polling is supported.
+        # @return [boolean]
+        #
+        def run_status?
+          !!self["run_status"]
+        end
+
+        ##
+        # Whether the run events SSE stream is supported.
+        # @return [boolean]
+        #
+        def run_events_sse?
+          !!self["run_events_sse"]
+        end
+
+        ##
+        # Whether stopping a run is supported.
+        # @return [boolean]
+        #
+        def run_stop?
+          !!self["run_stop"]
+        end
+
+        ##
+        # Whether responding to a run approval request is supported.
+        # @return [boolean]
+        #
+        def run_approval_response?
+          !!self["run_approval_response"]
+        end
+
+        ##
+        # Whether the server emits custom tool-progress events.
+        # @return [boolean]
+        #
+        def tool_progress_events?
+          !!self["tool_progress_events"]
+        end
+
+        ##
+        # Whether the server emits approval events.
+        # @return [boolean]
+        #
+        def approval_events?
+          !!self["approval_events"]
+        end
+
+        ##
+        # Whether CORS is enabled.
+        # @return [boolean]
+        #
+        def cors?
+          !!self["cors"]
+        end
+
+        ##
+        # The request header carrying the session-continuity id, e.g.
+        # `"X-Hermes-Session-Id"`.
+        # @return [String, nil]
+        #
+        def session_continuity_header
+          self["session_continuity_header"]
+        end
+
+        ##
+        # The request header carrying the session key, e.g.
+        # `"X-Hermes-Session-Key"`.
+        # @return [String, nil]
+        #
+        def session_key_header
+          self["session_key_header"]
+        end
+      end
+
+      ##
+      # A single advertised route (one entry of {Capabilities#endpoints}).
+      #
+      class Endpoint < Entity
+        ##
+        # The HTTP method, e.g. `"GET"`. (Named `http_method` rather than
+        # `method` to avoid shadowing `Object#method`.)
+        # @return [String, nil]
+        #
+        def http_method
+          self["method"]
+        end
+
+        ##
+        # The request path, e.g. `"/v1/models"`. May contain `{...}`
+        # placeholders such as `/v1/runs/{run_id}`.
+        # @return [String, nil]
+        #
+        def path
+          self["path"]
+        end
+      end
+
+      ##
+      # The server's advertised capabilities (`GET /v1/capabilities`).
+      # Field readers are best-effort; {#to_h} remains the source of truth.
+      #
+      class Capabilities < Entity
+        ##
+        # The object type, `"hermes.api_server.capabilities"`.
+        # @return [String, nil]
+        #
+        def object
+          self["object"]
+        end
+
+        ##
+        # The platform identifier, e.g. `"hermes-agent"`.
+        # @return [String, nil]
+        #
+        def platform
+          self["platform"]
+        end
+
+        ##
+        # The configured server-side model id, e.g. `"hermes-test"`.
+        # @return [String, nil]
+        #
+        def model
+          self["model"]
+        end
+
+        ##
+        # The authentication scheme, wrapped in an {Auth} entity. Returns
+        # `nil` when the field is absent.
+        # @return [Auth, nil]
+        #
+        def auth
+          raw = self["auth"]
+          raw.is_a?(::Hash) ? Auth.new(raw) : nil
+        end
+
+        ##
+        # The execution model, wrapped in a {Runtime} entity. Returns `nil`
+        # when the field is absent.
+        # @return [Runtime, nil]
+        #
+        def runtime
+          raw = self["runtime"]
+          raw.is_a?(::Hash) ? Runtime.new(raw) : nil
+        end
+
+        ##
+        # The feature matrix, wrapped in a {Features} entity. Returns `nil`
+        # when the field is absent.
+        # @return [Features, nil]
+        #
+        def features
+          raw = self["features"]
+          raw.is_a?(::Hash) ? Features.new(raw) : nil
+        end
+
+        ##
+        # The advertised routes, keyed by logical name (e.g. `"models"`), each
+        # value wrapped in an {Endpoint}. Returns `nil` when the field is
+        # absent.
+        # @return [Hash{String => Endpoint}, nil]
+        #
+        def endpoints
+          raw = self["endpoints"]
+          return nil unless raw.is_a?(::Hash)
+
+          raw.transform_values { |value| Endpoint.new(value) }
+        end
+      end
+    end
+  end
+end