Class: Phronomy::LLMAdapter::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/llm_adapter/base.rb

Overview

Abstract base class for LLM adapters.

Subclasses must implement #complete and #stream. The adapter or the underlying provider client owns transport timeout, retry, backoff, and rate-limit behavior. Phronomy only supplies cooperative cancellation and isolates blocking calls in BlockingAdapterPool.

The agent pipeline calls #complete_async / #stream_async which wrap those methods in a BlockingAdapterPool submission.

Direct Known Subclasses

RubyLLM

Instance Method Summary collapse

Instance Method Details

#complete(chat, message, config: {}) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Performs a blocking (non-streaming) LLM completion. Implementors must call chat.ask(message) (or equivalent) and return the response object.

Parameters:

  • chat (Object) —

    the configured chat session object

  • message (String) —

    the user message

  • config (Hash) (defaults to: {}) —

    invocation config (e.g. :cancellation_token)

Returns:

  • (Object) —

    LLM response object

Raises:

  • (NotImplementedError) 


25
26
27
 
# File 'lib/phronomy/llm_adapter/base.rb', line 25

def complete(chat, message, config: {})
  raise NotImplementedError, "#{self.class}#complete is not implemented"
end

#complete_async(chat, message, config: {}, pool: default_pool) ⇒ BlockingAdapterPool::PendingOperation

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Submits a non-streaming LLM call to BlockingAdapterPool and returns a BlockingAdapterPool::PendingOperation.

Transport timeout and retry remain the responsibility of the adapter or provider client; Phronomy does not attach an additional operation timeout.

Parameters:

  • chat (Object) —

    configured chat session

  • message (String) —

    user message

  • config (Hash) (defaults to: {}) —

    invocation config

  • pool (BlockingAdapterPool) (defaults to: default_pool) —

    pool to submit to

Returns:

  • (BlockingAdapterPool::PendingOperation) 


56
57
58
59
60
61
 
# File 'lib/phronomy/llm_adapter/base.rb', line 56

def complete_async(chat, message, config: {}, pool: default_pool)
  token = config[:cancellation_token]
  pool.submit(cancellation_token: token) do
    complete(chat, message, config: config)
  end
end

#stream(chat, message, config: {}) {|chunk| ... } ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Performs a blocking streaming LLM completion. Implementors must call chat.ask(message) { |chunk| block.call(chunk) } (or equivalent) and return the response object.

Parameters:

  • chat (Object) —

    the configured chat session object

  • message (String) —

    the user message

  • config (Hash) (defaults to: {}) —

    invocation config

Yields:

  • (chunk) —

    streaming chunk from the LLM

Returns:

  • (Object) —

    LLM response object

Raises:

  • (NotImplementedError) 


40
41
42
 
# File 'lib/phronomy/llm_adapter/base.rb', line 40

def stream(chat, message, config: {}, &block)
  raise NotImplementedError, "#{self.class}#stream is not implemented"
end

#stream_async(chat, message, config: {}, pool: default_pool) {|chunk| ... } ⇒ BlockingAdapterPool::PendingOperation

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Submits a streaming LLM call to BlockingAdapterPool and returns a BlockingAdapterPool::PendingOperation.

The block is invoked on the blocking-pool worker thread. Agent code must pass only a lightweight internal sink that posts a value to EventLoop; Application callbacks must never be passed directly to this method.

Transport timeout and retry remain the responsibility of the adapter or provider client; Phronomy does not attach an additional operation timeout.

Yields:

  • (chunk) —

    streaming chunk on the worker thread

Returns:

  • (BlockingAdapterPool::PendingOperation)

Raises:

  • (ArgumentError) 


76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/phronomy/llm_adapter/base.rb', line 76

def stream_async(chat, message, config: {}, pool: default_pool, &block)
  raise ArgumentError, "stream_async requires a block" unless block

  token = config[:cancellation_token]
  pool.submit(cancellation_token: token) do
    stream(chat, message, config: config) do |chunk|
      token&.raise_if_cancelled!("invocation cancelled during streaming")
      block.call(chunk)
    end
  end
end