Module: Phronomy::Agent::Context::Knowledge::VectorStore::AsyncBackend

Included in:
Base
Defined in:
lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb

Overview

Mixin that defines the async interface for VectorStore backends.

Mixing this module into a VectorStore class provides three choices:

  1. Do nothing — inherits default implementations from Base that route through BlockingAdapterPool (the previous behaviour).

  2. Override selectively — override only the async methods where the backend has a native async driver, while the remaining methods fall back to the pool.

  3. Implement all natively — override all async methods to avoid pool allocation entirely.

Examples:

Native async search (no pool worker thread allocated)

class MyFastStore < Phronomy::Agent::Context::Knowledge::VectorStore::Base
  include Phronomy::Agent::Context::Knowledge::VectorStore::AsyncBackend

  def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
    # Returns a PendingOperation backed by a native async driver.
    native_async_search(query_embedding, k)
  end
end

Instance Method Summary collapse

Instance Method Details

#add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil) ⇒ BlockingAdapterPool::PendingOperation

Async variant of Base#add.

Submits the add call to BlockingAdapterPool by default. Override to use a native async driver.

Parameters:

  • id (String)
  • embedding (Array<Float>)
  • metadata (Hash) (defaults to: {})
  • cancellation_token (Phronomy::Concurrency::CancellationToken, nil) (defaults to: nil)
  • timeout (Numeric, nil) (defaults to: nil)

Returns:

  • (BlockingAdapterPool::PendingOperation) 


46
47
48
49
50
51
52
53
 
# File 'lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb', line 46

def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
  Phronomy::Runtime.instance.blocking_io.submit(
    timeout: timeout,
    cancellation_token: cancellation_token
  ) do
    add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
  end
end

#clear_async(cancellation_token: nil, timeout: nil) ⇒ BlockingAdapterPool::PendingOperation

Async variant of Base#clear.

Submits the clear call to BlockingAdapterPool by default. Override to use a native async driver.

Parameters:

Returns:

  • (BlockingAdapterPool::PendingOperation) 


103
104
105
106
107
108
109
110
 
# File 'lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb', line 103

def clear_async(cancellation_token: nil, timeout: nil)
  Phronomy::Runtime.instance.blocking_io.submit(
    timeout: timeout,
    cancellation_token: cancellation_token
  ) do
    clear
  end
end

#remove_async(id:, cancellation_token: nil, timeout: nil) ⇒ BlockingAdapterPool::PendingOperation

Async variant of Base#remove.

Submits the remove call to BlockingAdapterPool by default. Override to use a native async driver.

Parameters:

Returns:

  • (BlockingAdapterPool::PendingOperation) 


85
86
87
88
89
90
91
92
 
# File 'lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb', line 85

def remove_async(id:, cancellation_token: nil, timeout: nil)
  Phronomy::Runtime.instance.blocking_io.submit(
    timeout: timeout,
    cancellation_token: cancellation_token
  ) do
    remove(id: id)
  end
end

#search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil) ⇒ BlockingAdapterPool::PendingOperation

Async variant of Base#search.

Submits the search call to BlockingAdapterPool by default. Override to use a native async driver.

Parameters:

Returns:

  • (BlockingAdapterPool::PendingOperation) 


66
67
68
69
70
71
72
73
 
# File 'lib/phronomy/agent/context/knowledge/vector_store/async_backend.rb', line 66

def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
  Phronomy::Runtime.instance.blocking_io.submit(
    timeout: timeout,
    cancellation_token: cancellation_token
  ) do
    search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
  end
end