hermes-client 0.0.0 → 0.1.0

data/lib/hermes_agent/client/resources/models.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entities/model"
+
+module HermesAgent
+  class Client
+    module Resources
+      ##
+      # The models resource: discovery of the models the server advertises
+      # (`/v1/models`).
+      #
+      class Models
+        ##
+        # Create the resource.
+        #
+        # @param transport [Transport] The transport used to issue requests.
+        #
+        # @private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        ##
+        # List the models the server advertises.
+        #
+        # @return [Array<Entities::Model>] The advertised models. Empty when
+        #     the server returns no `data` array.
+        #
+        def list
+          data = @transport.get("/v1/models")["data"]
+          return [] unless data.is_a?(::Array)
+
+          data.map { |item| Entities::Model.new(item) }
+        end
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/resources/responses.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entities/response"
+require "hermes_agent/client/conversation"
+require "hermes_agent/client/util"
+
+module HermesAgent
+  class Client
+    module Resources
+      ##
+      # The responses resource: the Responses API (`/v1/responses`). Unlike
+      # chat completions, the server persists conversation state, so turns can
+      # be chained (via `previous_response_id` or a named `conversation`) and a
+      # response can be retrieved or deleted by id afterward. On a server
+      # configured with an API key, these calls require a bearer token (see
+      # {Client} / {Configuration}).
+      #
+      # Server-side storage is capped (LRU eviction), so callers should not
+      # assume an older response remains retrievable.
+      #
+      class Responses
+        ##
+        # Create the resource.
+        #
+        # @param transport [Transport] The transport used to issue requests.
+        #
+        # @private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        ##
+        # Create a response.
+        #
+        # No `model` is sent: the model is configured server-side and the
+        # server ignores a client-supplied one. (A caller who really wants to
+        # send fields we have not modeled — including `model` — can pass them
+        # through `extra`.)
+        #
+        # @param input [String, Array<Hash>] The input: a plain string, or an
+        #     array of input items (which may include `input_image` parts for
+        #     inline images).
+        # @param previous_response_id [String, nil] The id of a prior response
+        #     to chain this turn onto. Omitted from the request when `nil`.
+        # @param conversation [String, nil] A stable conversation name to chain
+        #     this turn onto. Omitted from the request when `nil`.
+        # @param idempotency_key [String, nil] An idempotency key, sent as the
+        #     `Idempotency-Key` request header. The server caches the result for
+        #     ~5 minutes and replays it for a repeat call carrying the same key
+        #     and an equivalent request, so a retry does not re-run the model.
+        #     The replay is **transparent**: the response is indistinguishable
+        #     from a fresh one (same status, no replay header, and a freshly
+        #     regenerated `id`), so there is no way — here or in the returned
+        #     entity — to tell whether a given call was served from the cache.
+        #     Reusing a key with a *different* request silently recomputes (no
+        #     error) and overwrites the cached entry. Honored only on this
+        #     non-streaming endpoint (not on {#stream_create}).
+        # @param extra [Hash] Additional request-body fields merged into the
+        #     body as-is.
+        # @return [Entities::Response] The response. Its
+        #     {Entities::SessionHeaders#session_id} carries the server-generated
+        #     session id from the response headers (this endpoint does not
+        #     accept a session on the request).
+        # @raise [APIError] If the server returns a non-2xx response.
+        #
+        def create(input:, previous_response_id: nil, conversation: nil, idempotency_key: nil, **extra)
+          body = build_body(input, previous_response_id, conversation, extra)
+          headers = idempotency_key ? {"Idempotency-Key" => idempotency_key} : nil
+          result = @transport.post("/v1/responses", body, headers: headers)
+          Entities::Response.new(result.body, **Util.session_headers(result.headers))
+        end
+
+        ##
+        # Create a response, streaming the turn's events.
+        #
+        # With a block, each {Entities::ResponseStreamEvent} is yielded as it
+        # arrives and the assembled {Entities::Response} is returned once the
+        # stream closes. Without a block, a {Stream} is returned for the caller
+        # to iterate; its {Stream#result} is the assembled response. The final
+        # response is taken from the terminal `response.completed` event (see
+        # {Entities::Response.from_events}).
+        #
+        # @param input [String, Array<Hash>] The input (see {#create}).
+        # @param previous_response_id [String, nil] The id of a prior response
+        #     to chain onto. Omitted from the request when `nil`.
+        # @param conversation [String, nil] A stable conversation name to chain
+        #     onto. Omitted from the request when `nil`.
+        # @param extra [Hash] Additional request-body fields merged into the
+        #     body as-is.
+        # @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:, previous_response_id: nil, conversation: nil, **extra, &)
+          stream_response(on_result: nil, input: input, previous_response_id: previous_response_id,
+                          conversation: conversation, **extra, &)
+        end
+
+        ##
+        # Create a streamed response, with an optional hook invoked with the
+        # assembled {Entities::Response} once the stream is consumed. This is
+        # the shared implementation behind {#stream_create}; the `on_result`
+        # hook is folded into the stream's aggregator (so it fires exactly when
+        # the final response is built, for both the block and enumerator forms)
+        # rather than exposed as a settable hook on the returned {Stream}, where
+        # a caller could clobber it. It exists for {Conversation} to capture the
+        # new response id for chaining; it is not part of the public API.
+        #
+        # @private
+        # @param on_result [#call, nil] Called with the assembled
+        #     {Entities::Response} when the stream's result is built. May be nil.
+        # @param input [String, Array<Hash>] The input (see {#create}).
+        # @param previous_response_id [String, nil] The prior response id to
+        #     chain onto. Omitted from the request when nil.
+        # @param conversation [String, nil] A conversation name to chain onto.
+        #     Omitted from the request when nil.
+        # @param extra [Hash] Additional request-body fields.
+        # @yieldparam event [Entities::ResponseStreamEvent] Each streamed event.
+        # @return [Entities::Response, Stream] The assembled response when a
+        #     block is given, otherwise the {Stream}.
+        #
+        def stream_response(on_result:, input:, previous_response_id: nil, conversation: nil, **extra, &block)
+          body = build_body(input, previous_response_id, conversation, extra)
+          body[:stream] = true
+          result = @transport.stream_post("/v1/responses", body)
+          session = Util.session_headers(result.headers)
+          stream = Stream.new(result.body, event_class: Entities::ResponseStreamEvent) do |events|
+            response = Entities::Response.from_events(events, **session)
+            on_result&.call(response)
+            response
+          end
+          return stream unless block
+
+          stream.each(&block)
+          stream.result
+        end
+
+        ##
+        # Begin a multi-turn conversation that automatically chains its turns.
+        #
+        # Returns a {Conversation} — a stateful helper wrapping this resource —
+        # whose `create` / `stream_create` take only the per-turn `input:` (plus
+        # `extra`) and handle chaining for you. With no arguments it tracks the
+        # `previous_response_id` of each turn client-side and threads it into the
+        # next; pass `name:` instead to chain via a server-side named
+        # conversation; pass `previous_response_id:` to resume a client-side
+        # thread from a known id. `name:` and `previous_response_id:` are
+        # mutually exclusive (they select different chaining mechanisms).
+        #
+        # @param name [String, nil] A stable 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`.
+        # @return [Conversation]
+        #
+        def conversation(name: nil, previous_response_id: nil)
+          Conversation.new(self, name: name, previous_response_id: previous_response_id)
+        end
+
+        ##
+        # Retrieve a previously created response by id.
+        #
+        # @param id [String] The response id (`"resp_…"`).
+        # @return [Entities::Response] The response.
+        # @raise [NotFoundError] If no such response exists (or it was evicted).
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def get(id)
+          Entities::Response.new(@transport.get("/v1/responses/#{id}"))
+        end
+
+        ##
+        # Delete a response by id.
+        #
+        # @param id [String] The response id (`"resp_…"`).
+        # @return [Entities::ResponseDeletion] The deletion result.
+        # @raise [APIError] If the server returns a non-2xx response.
+        #
+        def delete(id)
+          Entities::ResponseDeletion.new(@transport.delete("/v1/responses/#{id}"))
+        end
+
+        private
+
+        ##
+        # Build the request body, including chaining fields only when present.
+        #
+        # @param input [String, Array<Hash>] The input.
+        # @param previous_response_id [String, nil] The prior response id.
+        # @param conversation [String, nil] The conversation name.
+        # @param extra [Hash] Additional body fields.
+        # @return [Hash] The request body.
+        #
+        def build_body(input, previous_response_id, conversation, extra)
+          body = {input: input, **extra}
+          body[:previous_response_id] = previous_response_id if previous_response_id
+          body[:conversation] = conversation if conversation
+          body
+        end
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/resources/runs.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entities/run"
+
+module HermesAgent
+  class Client
+    module Resources
+      ##
+      # The runs resource: the Runs API (`/v1/runs`) for long-running agent
+      # runs. Unlike chat completions and the Responses API, a run is
+      # **server-side asynchronous**: {#create} returns immediately (HTTP `202`)
+      # with a minimal {Entities::Run} carrying only its `run_id` and `status`,
+      # and progress is tracked by polling {#get} or by subscribing to its
+      # event stream with {#stream_events}. On a server configured with an API
+      # key, these calls require a bearer token (see {Client} / {Configuration}).
+      #
+      # Run records are retained only briefly after they reach a terminal
+      # status, then evicted, so callers should not assume an older run remains
+      # retrievable.
+      #
+      class Runs
+        ##
+        # Create the resource.
+        #
+        # @param transport [Transport] The transport used to issue requests.
+        #
+        # @private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        ##
+        # Start a run.
+        #
+        # Returns as soon as the run is accepted; the returned {Entities::Run}
+        # carries only its `run_id` and an initial `status` of `"started"`. Poll
+        # {#get} with that id to follow the run to a terminal status.
+        #
+        # No `model` is sent: the model is configured server-side. (A caller who
+        # really wants to send fields we have not modeled — including `model` —
+        # can pass them through `extra`.)
+        #
+        # @param input [String] The user prompt (required).
+        # @param instructions [String, nil] A system directive layered over the
+        #     agent prompt. Omitted from the request when `nil`.
+        # @param conversation_history [Array<Hash>, nil] Prior turns as an
+        #     OpenAI-style message array (`[{role:, content:}, …]`), loaded into
+        #     the run's context. Omitted from the request when `nil`.
+        # @param previous_response_id [String, nil] The id of a stored
+        #     `/v1/responses` response whose context should be loaded into the
+        #     run. Omitted from the request when `nil`.
+        # @param session_id [String, nil] A correlation label, stored and echoed
+        #     back on the poll. Omitted from the request when `nil`.
+        # @param extra [Hash] Additional request-body fields merged in as-is.
+        # @return [Entities::Run] The accepted run (minimal: `run_id` + status).
+        # @raise [APIError] If the server returns a non-2xx response.
+        #
+        def create(input:, instructions: nil, conversation_history: nil,
+                   previous_response_id: nil, session_id: nil, **extra)
+          body = {input: input, **extra}
+          body[:instructions] = instructions if instructions
+          body[:conversation_history] = conversation_history if conversation_history
+          body[:previous_response_id] = previous_response_id if previous_response_id
+          body[:session_id] = session_id if session_id
+          Entities::Run.new(@transport.post("/v1/runs", body).body)
+        end
+
+        ##
+        # Retrieve a run by id, to poll its progress and status.
+        #
+        # @param run_id [String] The run id (`"run_…"`).
+        # @return [Entities::Run] The current run state.
+        # @raise [NotFoundError] If no such run exists (or it was evicted).
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def get(run_id)
+          Entities::Run.new(@transport.get("/v1/runs/#{run_id}"))
+        end
+
+        ##
+        # Request that a run stop.
+        #
+        # The stop is cooperative: this returns as soon as the request is
+        # accepted, with an ack carrying `status: "stopping"`. The run then
+        # resolves to a terminal `"cancelled"` status — poll {#get} to observe
+        # that transition.
+        #
+        # @param run_id [String] The run id (`"run_…"`).
+        # @return [Entities::RunStop] The stop acknowledgement.
+        # @raise [NotFoundError] If no such run exists (or it was evicted).
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def stop(run_id)
+          Entities::RunStop.new(@transport.post("/v1/runs/#{run_id}/stop", {}).body)
+        end
+
+        ##
+        # Stream a run's events as they occur (its tool-call progress, token
+        # deltas, reasoning, approval prompts, and lifecycle), following the
+        # block-or-enumerator pattern.
+        #
+        # With a block, each {Entities::RunEvent} is yielded as it arrives and
+        # the terminal `run.*` event is returned once the stream closes. Without
+        # a block, a {Stream} is returned for the caller to iterate; its
+        # {Stream#result} is that terminal event (see
+        # {Entities::RunEvent.terminal}). Subscribing replays a run from its
+        # first event, so an already-terminal run can still be streamed during
+        # its (brief) retention window.
+        #
+        # @param run_id [String] The run id (`"run_…"`).
+        # @yieldparam event [Entities::RunEvent] Each streamed event.
+        # @return [Entities::RunEvent, Stream, nil] The terminal event when a
+        #     block is given (or `nil` if the stream closed without one),
+        #     otherwise the {Stream}.
+        # @raise [NotFoundError] If no such run exists (or it was evicted).
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def stream_events(run_id, &block)
+          chunks = @transport.stream_get("/v1/runs/#{run_id}/events")
+          stream = Stream.new(chunks, event_class: Entities::RunEvent) do |events|
+            Entities::RunEvent.terminal(events)
+          end
+          return stream unless block
+
+          stream.each(&block)
+          stream.result
+        end
+
+        ##
+        # Answer a run's pending approval, when a gated dangerous command has
+        # parked it at `waiting_for_approval`.
+        #
+        # A run has at most one outstanding approval, keyed by its id, so only
+        # the `run_id` and a `choice` are needed. `"once"` approves this one
+        # invocation; `"deny"` rejects it (the run still ends `completed`). Note
+        # `"always"` writes a permanent server-side allowlist entry and
+        # `"session"` auto-approves the pattern for the rest of the gateway
+        # session — prefer `"once"`/`"deny"` unless those side effects are
+        # intended. An invalid choice is rejected by the server.
+        #
+        # @param run_id [String] The run id (`"run_…"`).
+        # @param choice [String] One of `"once"`, `"session"`, `"always"`, or
+        #     `"deny"`.
+        # @return [Entities::RunApprovalResponse] The approval acknowledgement.
+        # @raise [NotFoundError] If no such run exists (or it was evicted).
+        # @raise [APIError] On an invalid choice (`400`) or another non-2xx
+        #     response.
+        #
+        def respond_approval(run_id, choice:)
+          body = {choice: choice}
+          Entities::RunApprovalResponse.new(@transport.post("/v1/runs/#{run_id}/approval", body).body)
+        end
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/stream.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "json"
+
+require "hermes_agent/client/errors"
+require "hermes_agent/client/util"
+
+module HermesAgent
+  class Client
+    ##
+    # A consumable Server-Sent Events stream.
+    #
+    # `Stream` parses the SSE frames emitted by a streaming endpoint, wrapping
+    # each frame's `data` payload (parsed as JSON) in an event wrapper object,
+    # and implements the block-or-enumerator contract:
+    #
+    # - Iterated with a block (via {#each}), it yields each event as it
+    #   arrives, giving natural backpressure over the network read.
+    # - Without a block it is an `Enumerable` the caller drives itself.
+    #
+    # After the stream is fully consumed, {#result} returns the aggregated
+    # final object (built by the aggregator block given at construction). It is
+    # a **single-pass** stream over a live network read: it can be iterated
+    # once.
+    #
+    # The class is HTTP-agnostic — it consumes anything that yields String
+    # byte chunks via `#each` (the `http` gem's response body, or an array of
+    # chunks in tests) — so it never owns or manages the network connection
+    # itself.
+    #
+    class Stream
+      include ::Enumerable
+
+      ##
+      # Create a stream.
+      #
+      # @param chunks [#each] A source of String byte chunks (e.g. an `http`
+      #     response body).
+      # @param event_class [Class, #call] How each frame's parsed data is
+      #     wrapped. A {Entity} subclass wraps every frame regardless of its
+      #     SSE `event:` name. A callable instead receives the frame's event
+      #     name (`nil` for an unnamed frame) and returns the {Entity} subclass
+      #     to use, so a single stream can surface heterogeneous event types
+      #     (e.g. chat's `hermes.tool.progress` frames vs. completion chunks).
+      # @param terminator [String, nil] A sentinel `data` payload that marks
+      #     the end of the stream (e.g. `"[DONE]"` for chat completions). The
+      #     terminator frame is not yielded. `nil` means the stream simply
+      #     ends when the connection closes.
+      # @yieldparam events [Array<Entity>] All events seen, in order; the
+      #     block returns the aggregated {#result}. Optional — without it
+      #     {#result} is `nil`.
+      #
+      # @private
+      def initialize(chunks, event_class:, terminator: nil, &aggregator)
+        @chunks = chunks
+        @event_class = event_class
+        @terminator = terminator
+        @aggregator = aggregator
+        @buffer = +""
+        @data_lines = []
+        @event_name = nil
+        @events = []
+        @consumed = false
+        @result = nil
+      end
+
+      ##
+      # Iterate the events. With a block, yields each event as it is parsed and
+      # returns `self`. Without a block, returns an `Enumerator`.
+      #
+      # @yieldparam event [Entity] Each parsed event, in order.
+      # @return [self, Enumerator]
+      # @raise [Error] If the stream has already been consumed.
+      #
+      def each(&block)
+        return enum_for(:each) unless block
+
+        raise Error, "Stream has already been consumed" if @consumed
+
+        consume(&block)
+        self
+      end
+
+      ##
+      # The aggregated final object, available after the stream is consumed.
+      # Consuming the stream first if it has not been iterated.
+      #
+      # @return [Object, nil] Whatever the aggregator block returned, or `nil`
+      #     when no aggregator was given.
+      #
+      def result
+        consume unless @consumed
+        @result
+      end
+
+      private
+
+      ##
+      # Read every chunk, parse frames, accumulate events, and build the
+      # aggregated result. Yields each event if a block is given.
+      #
+      def consume
+        @consumed = true
+        @chunks.each do |chunk|
+          @buffer << chunk
+          while (newline = @buffer.index("\n"))
+            event = process_line(@buffer.slice!(0, newline + 1).chomp)
+            next unless event
+
+            @events << event
+            yield event if block_given?
+          end
+        end
+        @result = @aggregator&.call(@events)
+      end
+
+      ##
+      # Process one SSE line. Accumulates `data` fields, records the frame's
+      # `event:` name, and on a blank line dispatches the buffered frame.
+      #
+      # @param line [String] One line, without its trailing newline.
+      # @return [Entity, nil] The event when a frame completes, else `nil`.
+      #
+      def process_line(line)
+        return dispatch if line.empty?
+        return nil if line.start_with?(":")
+
+        field, separator, value = line.partition(":")
+        value = value.sub(/\A /, "") unless separator.empty?
+        case field
+        when "data" then @data_lines << value
+        when "event" then @event_name = value
+        end
+        nil
+      end
+
+      ##
+      # Emit the buffered frame, unless it is empty or the terminator. Resets
+      # the per-frame state (data lines and event name) either way so it does
+      # not leak into the next frame.
+      #
+      # @return [Entity, nil]
+      #
+      def dispatch
+        data = @data_lines.empty? ? nil : @data_lines.join("\n")
+        name = @event_name
+        @data_lines = []
+        @event_name = nil
+        return nil if data.nil? || (@terminator && data == @terminator)
+
+        event_class_for(name).new(Util.parse_json(data))
+      end
+
+      ##
+      # Resolve the {Entity} subclass for a frame: a callable `event_class`
+      # chooses by event name, otherwise the class itself is used for all.
+      #
+      # @param name [String, nil] The frame's SSE `event:` name.
+      # @return [Class]
+      #
+      def event_class_for(name)
+        @event_class.respond_to?(:call) ? @event_class.call(name) : @event_class
+      end
+    end
+  end
+end