Class: Parse::Retrieval::Reranker::Cohere

Inherits:
Base
  • Object
show all
Defined in:
lib/parse/retrieval/reranker/cohere.rb

Overview

Cohere cross-encoder reranker. Wraps POST /v2/rerank.

Cohere's rerank API takes a query plus a list of document strings and returns a relevance-ordered list of { index, relevance_score } objects. It is a distinct endpoint from /v1/embed / /v2/embed — do NOT confuse it with Embeddings::Cohere (the embeddings provider).

The HTTP stack mirrors the embeddings provider's hardening: explicit proxy: nil unless opted in, bounded timeouts, capped retries with backoff on 429/5xx, response-size cap, and a redacted #inspect.

Examples:

reranker = Parse::Retrieval::Reranker::Cohere.new(
  api_key: ENV.fetch("COHERE_API_KEY"),
  model:   "rerank-v3.5",
)
reranker.rerank(query: "rain songs", documents: lyrics, top_n: 5)

Defined Under Namespace

Classes: AuthenticationError, BadRequestError, RateLimitError, TransientError

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.cohere.com/v2"
DEFAULT_MODEL = 
"rerank-v3.5"
DEFAULT_TIMEOUT = 
30
DEFAULT_OPEN_TIMEOUT = 
5
DEFAULT_MAX_RETRIES = 
2
MAX_RESPONSE_BYTES =

Cohere documents a cap of 1000 documents per rerank call; the Base::MAX_DOCUMENTS cap (1000) already enforces this.

5 * 1024 * 1024

Constants inherited from Base

Base::MAX_DOCUMENTS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#rerank

Constructor Details

#initialize(api_key:, model: DEFAULT_MODEL, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, open_timeout: DEFAULT_OPEN_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, allow_faraday_proxy: false) ⇒ Cohere

Returns a new instance of Cohere.

Parameters:

  • api_key (String) —

    Cohere API key.

  • model (String) (defaults to: DEFAULT_MODEL) —

    rerank model (default DEFAULT_MODEL).

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    API base (default DEFAULT_BASE_URL).

  • timeout (Integer) (defaults to: DEFAULT_TIMEOUT) —

    read timeout (seconds).

  • open_timeout (Integer) (defaults to: DEFAULT_OPEN_TIMEOUT) —

    connect timeout (seconds).

  • max_retries (Integer) (defaults to: DEFAULT_MAX_RETRIES) —

    retry budget for 429 / 5xx / transient connection errors.

  • allow_faraday_proxy (Boolean) (defaults to: false) —

    permit Faraday to honor *_proxy env vars (default false — explicit proxy: nil).

Raises:

  • (ArgumentError) 


55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/parse/retrieval/reranker/cohere.rb', line 55

def initialize(api_key:, model: DEFAULT_MODEL, base_url: DEFAULT_BASE_URL,
               timeout: DEFAULT_TIMEOUT, open_timeout: DEFAULT_OPEN_TIMEOUT,
               max_retries: DEFAULT_MAX_RETRIES, allow_faraday_proxy: false)
  validate_api_key!(api_key)
  @api_key = api_key
  @model = model.to_s
  raise ArgumentError, "Reranker::Cohere: model must be non-empty." if @model.empty?
  @base_url = base_url.to_s
  validate_base_url!(@base_url)
  @timeout = Integer(timeout)
  @open_timeout = Integer(open_timeout)
  @max_retries = Integer(max_retries)
  raise ArgumentError, "Reranker::Cohere: max_retries must be >= 0." if @max_retries.negative?
  @allow_faraday_proxy = allow_faraday_proxy ? true : false
  @connection = build_connection
end

Instance Attribute Details

#model ⇒ String (readonly)

Returns the rerank model name.

Returns:

  • (String) —

    the rerank model name.



73
74
75
 
# File 'lib/parse/retrieval/reranker/cohere.rb', line 73

def model
  @model
end

Instance Method Details

#inspect ⇒ Object 



75
76
77
78
 
# File 'lib/parse/retrieval/reranker/cohere.rb', line 75

def inspect
  "#<#{self.class} model=#{@model.inspect} base=#{safe_base_host.inspect} " \
    "retries=#{@max_retries} api_key=[REDACTED]>"
end

#rerank_scores(query, documents, top_n) ⇒ Object (protected) 



82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/parse/retrieval/reranker/cohere.rb', line 82

def rerank_scores(query, documents, top_n)
  require_faraday!
  body = {
    "model"     => @model,
    "query"     => query,
    "documents" => documents,
    "top_n"     => top_n,
  }
  payload = post_rerank(body)
  extract_results!(payload, documents.length)
end