hermes-client 0.0.0 → 0.1.0

data/lib/hermes_agent/client/transport.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+# Require "http/cookie" explicitly before requiring "http", to avoid a
+# "circular dependency" warning due to the way the "http" gem uses autoload.
+require "http/cookie"
+require "http"
+require "json"
+
+require "hermes_agent/client/util"
+
+module HermesAgent
+  class Client
+    ##
+    # The single chokepoint for HTTP communication with the server.
+    #
+    # Transport owns the underlying `http` gem connection, attaches the
+    # `Authorization` header, serializes and parses JSON, and maps non-2xx
+    # responses to the {Error} hierarchy. Resource objects build paths and
+    # delegate here.
+    #
+    # The connection is **persistent and scoped to the transport instance**: a
+    # single keep-alive `HTTP::Session`, built lazily on first use, is reused
+    # across every request so the TCP/TLS handshake happens once rather than per
+    # call. The `http` gem transparently reopens the connection when it has been
+    # closed by the server, has exceeded its keep-alive lifetime, or a prior
+    # request failed (timeout or socket error), so callers never manage the
+    # connection lifecycle. Because the session is per-instance and holds live
+    # connection state, a transport — like the {Client} that owns it — is **not
+    # thread-safe**; multithreaded callers should use a separate client per
+    # thread.
+    #
+    # @private
+    class Transport
+      ##
+      # The outcome of a request whose response headers matter to the caller:
+      # the parsed body — or, for a streaming request, the live chunk
+      # enumerator — paired with the response headers as a Hash with downcased
+      # string keys. Returned by {#post} and {#stream_post}; the header-agnostic
+      # {#get} and {#delete} return the bare parsed body instead.
+      #
+      # @!attribute [r] body
+      #   @return [Hash, Enumerator] The parsed JSON body, or the chunk
+      #       enumerator for a streaming request.
+      # @!attribute [r] headers
+      #   @return [Hash{String=>String}] The response headers, keyed by
+      #       downcased name.
+      #
+      Result = ::Data.define(:body, :headers)
+
+      ##
+      # Create a transport.
+      #
+      # @param config [Configuration] The connection settings to use.
+      #
+      def initialize(config)
+        @config = config
+      end
+
+      ##
+      # Issue a GET request and return the parsed JSON body.
+      #
+      # @param path [String] The request path, including any prefix such as
+      #     `/v1` or `/health` (resources own their prefixes).
+      # @return [Hash] The parsed response body, with string keys.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def get(path)
+        response = map_request_errors { session.get(url_for(path)) }
+        handle(response)
+      end
+
+      ##
+      # Issue a POST request with a JSON body and return the parsed JSON body.
+      #
+      # @param path [String] The request path, including any prefix such as
+      #     `/v1` (resources own their prefixes).
+      # @param body [Hash] The request body, serialized to JSON. The
+      #     `Content-Type: application/json` header is set automatically.
+      # @param headers [Hash, nil] Extra request headers to send, merged over
+      #     the defaults (e.g. the session-continuity headers).
+      # @return [Result] The parsed response body and the response headers.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def post(path, body, headers: nil)
+        response = map_request_errors { session.post(url_for(path), json: body, headers: headers) }
+        Result.new(body: handle(response), headers: normalize_headers(response.headers))
+      end
+
+      ##
+      # Issue a PATCH request with a JSON body and return the parsed JSON body.
+      #
+      # Like {#get} and {#delete}, this returns the bare parsed body rather than
+      # a {Result}: no PATCH endpoint surfaces response headers the caller needs.
+      #
+      # @param path [String] The request path, including any prefix such as
+      #     `/v1` or `/api` (resources own their prefixes).
+      # @param body [Hash] The request body, serialized to JSON. The
+      #     `Content-Type: application/json` header is set automatically.
+      # @return [Hash] The parsed response body, with string keys.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def patch(path, body)
+        response = map_request_errors { session.patch(url_for(path), json: body) }
+        handle(response)
+      end
+
+      ##
+      # Issue a DELETE request and return the parsed JSON body.
+      #
+      # @param path [String] The request path, including any prefix such as
+      #     `/v1` (resources own their prefixes).
+      # @return [Hash] The parsed response body, with string keys.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def delete(path)
+        response = map_request_errors { session.delete(url_for(path)) }
+        handle(response)
+      end
+
+      ##
+      # Open a streaming POST and return its live response body for an SSE
+      # consumer ({Stream}). The response status is checked up front, so an
+      # error response raises before any streaming begins; on success the body
+      # is returned unread so it can be consumed incrementally.
+      #
+      # @param path [String] The request path, including its prefix.
+      # @param body [Hash] The request body, serialized to JSON.
+      # @param headers [Hash, nil] Extra request headers to send, merged over
+      #     the defaults (e.g. the session-continuity headers).
+      # @return [Result] The live chunk enumerator (as `body`) and the response
+      #     headers. Iterate `body` with `#each` to read byte chunks as they
+      #     arrive.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def stream_post(path, body, headers: nil)
+        response = map_request_errors { session.post(url_for(path), json: body, headers: headers) }
+        unless response.status.success?
+          raise APIError.from_response(status: response.code, body: response.body.to_s,
+                                       headers: normalize_headers(response.headers))
+        end
+        Result.new(body: map_stream_errors(response.body), headers: normalize_headers(response.headers))
+      end
+
+      ##
+      # Open a streaming GET and return its live response body for an SSE
+      # consumer ({Stream}). Like {#stream_post}, the status is checked up front
+      # so an error response raises before any streaming begins; on success the
+      # body is returned unread for incremental consumption. The response
+      # headers are not surfaced (this is the streaming counterpart of {#get},
+      # which also returns the bare body).
+      #
+      # @param path [String] The request path, including its prefix.
+      # @return [Enumerator] The live chunk enumerator. Iterate it with `#each`
+      #     to read byte chunks as they arrive.
+      # @raise [APIError] If the server returns a non-2xx response.
+      #
+      def stream_get(path)
+        response = map_request_errors { session.get(url_for(path)) }
+        unless response.status.success?
+          raise APIError.from_response(status: response.code, body: response.body.to_s,
+                                       headers: normalize_headers(response.headers))
+        end
+        map_stream_errors(response.body)
+      end
+
+      private
+
+      ##
+      # Wrap a streaming response body so transport-level failures hit while
+      # reading it are mapped to the {Error} hierarchy.
+      #
+      # The body is read lazily, chunk by chunk, *after* {#stream_post} has
+      # returned — so a socket or read-timeout failure mid-stream happens
+      # outside `map_request_errors`'s rescue and would otherwise surface as the raw
+      # `http`-gem exception. Iterating the returned enumerator re-reads the
+      # body inside `map_request_errors`, so the same {TimeoutError}/{ConnectionError}
+      # mapping applies. Chunks delivered before the failure are still yielded;
+      # the exception is raised when the failing read is reached. Keeps {Stream}
+      # HTTP-agnostic — it only ever sees mapped errors.
+      #
+      # @param body [#each] The live response body, yielding String chunks.
+      # @return [Enumerator] The same chunks, with mid-stream failures mapped.
+      #
+      def map_stream_errors(body)
+        ::Enumerator.new do |yielder|
+          map_request_errors { body.each { |chunk| yielder << chunk } }
+        end
+      end
+
+      ##
+      # Run an HTTP request, translating the `http` gem's transport-level
+      # failures into the client's {Error} hierarchy.
+      #
+      # @yield The block that issues the request and returns its response.
+      # @return [HTTP::Response]
+      # @raise [TimeoutError] On an open or read timeout.
+      # @raise [ConnectionError] On a socket, DNS, or TLS failure.
+      #
+      def map_request_errors
+        yield
+      rescue ::HTTP::TimeoutError => e
+        raise TimeoutError, e.message
+      rescue ::HTTP::ConnectionError => e
+        raise ConnectionError, e.message
+      end
+
+      ##
+      # The persistent `http` session for this transport, built once and reused
+      # across requests so its keep-alive connection is shared. The session
+      # carries the default headers (auth, `Accept`) and the configured
+      # timeouts, and reuses an idle connection for up to the configured
+      # keep-alive timeout before reopening it; per-request headers are merged
+      # over the defaults at the call site via the request's `headers:` option.
+      # Scoped to (and pinned to the origin of) this transport instance; not
+      # thread-safe.
+      #
+      # @return [HTTP::Session] The persistent, auth- and timeout-configured
+      #     session.
+      #
+      def session
+        @session ||=
+          begin
+            result = ::HTTP.persistent(@config.base_url, timeout: @config.keep_alive_timeout)
+                           .headers(default_headers)
+            # Pass only the timeouts that are set: the `http` gem rejects a nil
+            # value for any operation rather than treating it as "no limit".
+            timeouts = {read: @config.read_timeout, connect: @config.open_timeout,
+                        write: @config.write_timeout}.compact
+            result = result.timeout(timeouts) unless timeouts.empty?
+            result
+          end
+      end
+
+      ##
+      # Normalize response headers to a plain Hash keyed by downcased name,
+      # keeping the layers above {Transport} free of the `http` gem's header
+      # type. Repeated headers collapse to their first value.
+      #
+      # @param headers [#to_h] The response headers.
+      # @return [Hash{String=>String}]
+      #
+      def normalize_headers(headers)
+        headers.to_h.each_with_object({}) do |(name, value), result|
+          result[name.to_s.downcase] = value.is_a?(::Array) ? value.first : value
+        end
+      end
+
+      ##
+      # @return [Hash] The headers sent on every request.
+      #
+      def default_headers
+        headers = {"Accept" => "application/json"}
+        headers["Authorization"] = "Bearer #{@config.api_key}" if @config.api_key
+        headers
+      end
+
+      ##
+      # @param path [String] A request path.
+      # @return [String] The fully-qualified request URL.
+      #
+      def url_for(path)
+        "#{@config.base_url.chomp('/')}#{path}"
+      end
+
+      ##
+      # Parse a successful response or raise on a non-2xx status.
+      #
+      # @param response [HTTP::Response]
+      # @return [Hash] The parsed JSON body.
+      #
+      def handle(response)
+        body = response.body.to_s
+        unless response.status.success?
+          raise APIError.from_response(status: response.code, body: body,
+                                       headers: normalize_headers(response.headers))
+        end
+        body.empty? ? {} : Util.parse_json(body)
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/util.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+
+require "hermes_agent/client/errors"
+
+module HermesAgent
+  class Client
+    ##
+    # Internal helpers shared across the client's layers. Not part of the
+    # public API.
+    #
+    # @private
+    module Util
+      ##
+      # The downcased response-header name carrying the session id.
+      #
+      SESSION_ID_HEADER = "x-hermes-session-id"
+
+      ##
+      # The downcased response-header name carrying the session key.
+      #
+      SESSION_KEY_HEADER = "x-hermes-session-key"
+
+      ##
+      # Extract the session-continuity values from a normalized (downcased-key)
+      # response-header hash into the keyword form the session-bearing entities
+      # ({Entities::ChatCompletion}, {Entities::Response}) accept. Either value
+      # is `nil` when the corresponding header is absent.
+      #
+      # @param headers [Hash{String=>String}] Response headers, keyed by
+      #     downcased name (as produced by {Transport}).
+      # @return [Hash{Symbol=>(String, nil)}] `{session_id:, session_key:}`.
+      #
+      def self.session_headers(headers)
+        {session_id: headers[SESSION_ID_HEADER], session_key: headers[SESSION_KEY_HEADER]}
+      end
+
+      ##
+      # Parse JSON from a payload the client expected to be JSON, mapping a
+      # parse failure to {MalformedResponseError} so a raw `JSON::ParserError`
+      # never leaks out. Shared by the non-streaming ({Transport#handle}) and
+      # streaming ({Stream#dispatch}) paths so the two behave identically.
+      #
+      # @param text [String] The raw text to parse.
+      # @return [Object] The parsed JSON value.
+      # @raise [MalformedResponseError] If the text is not valid JSON.
+      #
+      def self.parse_json(text)
+        ::JSON.parse(text)
+      rescue ::JSON::ParserError
+        raise MalformedResponseError.new("Invalid JSON in response body", body: text)
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module HermesAgent
+  class Client
+    ##
+    # Version of the hermes-client gem
+    # @return [String]
+    #
+    VERSION = "0.1.0"
+  end
+end

data/lib/hermes_agent/client.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/version"
+require "hermes_agent/client/configuration"
+require "hermes_agent/client/errors"
+require "hermes_agent/client/util"
+require "hermes_agent/client/stream"
+require "hermes_agent/client/transport"
+require "hermes_agent/client/conversation"
+require "hermes_agent/client/resources/capabilities"
+require "hermes_agent/client/resources/chat"
+require "hermes_agent/client/resources/health"
+require "hermes_agent/client/resources/jobs"
+require "hermes_agent/client/resources/models"
+require "hermes_agent/client/resources/responses"
+require "hermes_agent/client/resources/runs"
+
+##
+# Classes related to the Hermes agent
+#
+module HermesAgent
+  ##
+  # A client for the Hermes API server.
+  #
+  # Construct a client with the server location and credentials, then reach
+  # endpoints through resource accessors such as {#health}.
+  #
+  #     client = HermesAgent::Client.new(base_url: "http://127.0.0.1:8642")
+  #     client.health.check.status  # => "ok"
+  #
+  # Note this class is not thread-safe. When using in a multithreaded
+  # application, you should create a separate client object per thread.
+  #
+  class Client
+    # Sentinel distinguishing an omitted `api_key:` (defer to {Configuration}'s
+    # `HERMES_API_KEY` default) from an explicit `nil` (send no auth header).
+    UNSET = ::Object.new
+    private_constant :UNSET
+
+    ##
+    # Create a client.
+    #
+    # Settings may be supplied as keyword arguments, by yielding the
+    # {Configuration} to a block, or both (the block runs after the keyword
+    # arguments are applied).
+    #
+    # @param base_url [String] The server root URL. See {Configuration}.
+    # @param api_key [String, nil] The bearer token. When omitted, defaults to
+    #     the `HERMES_API_KEY` environment variable (see {Configuration}); pass
+    #     `nil` explicitly to send no `Authorization` header regardless.
+    # @param read_timeout [Numeric, nil] The read timeout in seconds.
+    # @param open_timeout [Numeric, nil] The connection-open timeout in seconds.
+    # @param write_timeout [Numeric, nil] The request-write timeout in seconds.
+    # @param keep_alive_timeout [Numeric] How long an idle persistent
+    #     connection may be reused before being reopened. See {Configuration}.
+    # @yieldparam config [Configuration] The configuration, for customization.
+    #
+    def initialize(base_url: Configuration::DEFAULT_BASE_URL,
+                   api_key: UNSET,
+                   read_timeout: nil,
+                   open_timeout: nil,
+                   write_timeout: nil,
+                   keep_alive_timeout: Configuration::DEFAULT_KEEP_ALIVE_TIMEOUT)
+      @config = Configuration.new(base_url: base_url, read_timeout: read_timeout,
+                                  open_timeout: open_timeout, write_timeout: write_timeout,
+                                  keep_alive_timeout: keep_alive_timeout)
+      @config.api_key = api_key unless api_key.equal?(UNSET)
+      yield @config if block_given?
+      @transport = Transport.new(@config)
+    end
+
+    ##
+    # The configuration this client was built with.
+    # @return [Configuration]
+    #
+    attr_reader :config
+
+    ##
+    # The capabilities resource (the server's advertised endpoints and
+    # feature matrix).
+    # @return [Resources::Capabilities]
+    #
+    def capabilities
+      @capabilities ||= Resources::Capabilities.new(@transport)
+    end
+
+    ##
+    # The chat resource (OpenAI-compatible chat completions).
+    # @return [Resources::Chat]
+    #
+    def chat
+      @chat ||= Resources::Chat.new(@transport)
+    end
+
+    ##
+    # The health resource (server health checks).
+    # @return [Resources::Health]
+    #
+    def health
+      @health ||= Resources::Health.new(@transport)
+    end
+
+    ##
+    # The jobs resource (the Jobs API, for scheduled background work).
+    # @return [Resources::Jobs]
+    #
+    def jobs
+      @jobs ||= Resources::Jobs.new(@transport)
+    end
+
+    ##
+    # The models resource (discovery of advertised models).
+    # @return [Resources::Models]
+    #
+    def models
+      @models ||= Resources::Models.new(@transport)
+    end
+
+    ##
+    # The responses resource (the Responses API, with server-side
+    # conversation state).
+    # @return [Resources::Responses]
+    #
+    def responses
+      @responses ||= Resources::Responses.new(@transport)
+    end
+
+    ##
+    # The runs resource (the Runs API, for long-running server-side agent
+    # runs).
+    # @return [Resources::Runs]
+    #
+    def runs
+      @runs ||= Resources::Runs.new(@transport)
+    end
+  end
+end

metadata

@@ -1,26 +1,87 @@
 --- !ruby/object:Gem::Specification
 name: hermes-client
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
-- dazuma@gmail.com
+- Daniel Azuma
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: 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.
-  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.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: http-cookie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: This is a basic client library for the API Server that ships with the
+  Hermes AI Agent.
+email:
+- dazuma@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.md
 - README.md
 - lib/hermes-client.rb
-licenses: []
-metadata: {}
+- lib/hermes_agent/client.rb
+- lib/hermes_agent/client/configuration.rb
+- lib/hermes_agent/client/conversation.rb
+- lib/hermes_agent/client/entities/capabilities.rb
+- lib/hermes_agent/client/entities/chat_completion.rb
+- lib/hermes_agent/client/entities/health.rb
+- lib/hermes_agent/client/entities/job.rb
+- lib/hermes_agent/client/entities/model.rb
+- lib/hermes_agent/client/entities/response.rb
+- lib/hermes_agent/client/entities/run.rb
+- lib/hermes_agent/client/entities/session_headers.rb
+- lib/hermes_agent/client/entity.rb
+- lib/hermes_agent/client/errors.rb
+- lib/hermes_agent/client/resources/capabilities.rb
+- lib/hermes_agent/client/resources/chat.rb
+- lib/hermes_agent/client/resources/health.rb
+- lib/hermes_agent/client/resources/jobs.rb
+- lib/hermes_agent/client/resources/models.rb
+- lib/hermes_agent/client/resources/responses.rb
+- lib/hermes_agent/client/resources/runs.rb
+- lib/hermes_agent/client/stream.rb
+- lib/hermes_agent/client/transport.rb
+- lib/hermes_agent/client/util.rb
+- lib/hermes_agent/client/version.rb
+homepage: https://github.com/dazuma/hermes-client
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/dazuma/hermes-client/issues
+  changelog_uri: https://rubydoc.info/gems/hermes-client/0.1.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/hermes-client/0.1.0
+  homepage_uri: https://github.com/dazuma/hermes-client
 rdoc_options: []
 require_paths:
 - lib
@@ -28,7 +89,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -37,5 +98,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Placeholder gem
+summary: A client for the Hermes Agent API Server.
 test_files: []