Class: HermesAgent::Client::Resources::Chat

Inherits:
Object
  • Object
show all
Defined in:
lib/hermes_agent/client/resources/chat.rb

Overview

The chat resource: OpenAI-compatible chat completions (POST /v1/chat/completions). This endpoint is stateless — each call is independent — and, on a server configured with an API key, requires a bearer token (see HermesAgent::Client / Configuration).

Constant Summary collapse

TOOL_PROGRESS_EVENT =

The SSE event: name of the server's custom tool-progress frames, which are routed to Entities::ChatToolProgress rather than treated as completion chunks.

"hermes.tool.progress"

Instance Method Summary collapse

Instance Method Details

#create(messages:, session_id: nil, session_key: nil, idempotency_key: nil, **extra) ⇒ Entities::ChatCompletion

Create a chat completion.

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.)

Parameters:

  • messages (Array<Hash>) —

    The OpenAI-style message array. Each message is a hash such as {role: "user", content: "…"}; content may include image_url parts for inline images.

  • session_id (String, nil) (defaults to: nil) —

    A session id to continue, sent as the X-Hermes-Session-ID request header. When omitted, the server generates a fresh one (returned on Entities::SessionHeaders#session_id).

  • session_key (String, nil) (defaults to: nil) —

    A session key, sent as the X-Hermes-Session-Key request header.

  • idempotency_key (String, nil) (defaults to: 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).

  • extra (Hash) —

    Additional request-body fields (e.g. sampling parameters) merged into the body as-is.

Returns:

Raises:

  • (APIError) —

    If the server returns a non-2xx response.



66
67
68
69
70
71
72
 
# File 'lib/hermes_agent/client/resources/chat.rb', line 66

def create(messages:, session_id: nil, session_key: nil, idempotency_key: nil, **extra)
  body = {messages: messages, **extra}
  headers = session_request_headers(session_id, session_key)
  headers["Idempotency-Key"] = idempotency_key if idempotency_key
  result = @transport.post("/v1/chat/completions", body, headers: headers)
  Entities::ChatCompletion.new(result.body, **Util.session_headers(result.headers))
end

#stream_create(messages:, session_id: nil, session_key: nil, **extra) {|event| ... } ⇒ Entities::ChatCompletion, Stream

Create a chat completion, streaming the response.

While the server agent executes tools it interleaves custom hermes.tool.progress frames; these are surfaced as Entities::ChatToolProgress events (distinct from the text Entities::ChatCompletionChunks) and are not folded into the assembled completion.

With a block, each event is yielded as it arrives and the assembled Entities::ChatCompletion is returned once the stream closes. Without a block, a Stream is returned for the caller to iterate; its Stream#result is the assembled completion.

Parameters:

  • messages (Array<Hash>) —

    The OpenAI-style message array (see #create).

  • session_id (String, nil) (defaults to: nil) —

    A session id to continue, sent as the X-Hermes-Session-ID request header (see #create).

  • session_key (String, nil) (defaults to: nil) —

    A session key, sent as the X-Hermes-Session-Key request header (see #create).

  • extra (Hash) —

    Additional request-body fields merged into the body as-is.

Yield Parameters:

Returns:

Raises:

  • (APIError) —

    If the server returns a non-2xx response.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/hermes_agent/client/resources/chat.rb', line 103

def stream_create(messages:, session_id: nil, session_key: nil, **extra, &block)
  body = {messages: messages, stream: true, **extra}
  result = @transport.stream_post("/v1/chat/completions", body,
                                  headers: session_request_headers(session_id, session_key))
  session = Util.session_headers(result.headers)
  event_class = lambda do |name|
    name == TOOL_PROGRESS_EVENT ? Entities::ChatToolProgress : Entities::ChatCompletionChunk
  end
  stream = Stream.new(result.body, event_class: event_class, terminator: "[DONE]") do |events|
    Entities::ChatCompletion.from_chunks(events, **session)
  end
  return stream unless block

  stream.each(&block)
  stream.result
end