Reranker support

[miyako]

#22

example usage: https://github.com/miyako/4d-example-renranker

[e-marchand]

RerankerParameters

[miyako]

3b25d99

[e-marchand]

no _Reranker

if private, no need to doc

Just principe of returned collection result and solution

[e-marchand]

_sigmoid private?

[miyako]

ff96c91

[e-marchand]

maybe simple if

An edge case: If a provider returns all scores between 0 and 1 but they are actually logits (unlikely but possible with low-confidence results), normalization would be skipped but maybe acceptable

[miyako]

5544460

[e-marchand]

Must Fix

• RerankerAPI.4dm:9 — Change OpenAIEmbeddingsParameters to RerankerParameters
• RerankerResult.md:18 — Fix cs._Reranker reference to correct class name

Should Fix

• Add documentation for Reranker, RerankerAPI, RerankerQuery, RerankerParameters
• Complete RerankerResult.md — document the results computed property and normalization behavior
• sigmoid private

Important

The following text has been generated by AI after I suggest to study architecture, and look at alternative like delegation

Architecture — Consider delegation over inheritance

The current approach (Reranker extends OpenAI + strip properties) is fragile and conceptually misleading — /rerank is not an OpenAI endpoint, yet the class inherits OPENAI_API_KEY defaults and https://api.openai.com/v1 fallback.

Suggested alternative: Flatten to a single Reranker class using delegation. The Reranker owns its own configuration but can optionally receive an OpenAI client for shared HTTP infrastructure:

// Simple — standalone reranker with its own config
var $reranker:=cs.AIKit.Reranker.new({baseURL: "http://127.0.0.1:8080/v1"})

// With shared client — reuses auth, httpAgent, retry, timeout from an existing OpenAI instance
var $openai:=cs.AIKit.OpenAI.new({apiKey: "key"; baseURL: "https://api.cohere.com/v2"})
var $reranker:=cs.AIKit.Reranker.new($openai)

// Or both — client for infra, object for overrides
var $reranker:=cs.AIKit.Reranker.new($openai; {baseURL: "http://other-server/v1"})

The Reranker class would:

• Store an optional _client: cs.OpenAI reference for delegation (HTTP calls, auth headers, retry logic)
• Accept a plain Object as constructor param, auto-create an internal cs.OpenAI client from it if no client passed
• Expose only .create($query; $parameters) directly — no .rerank.create() nesting needed since there's only one operation
• Keep RerankerQuery, RerankerParameters, RerankerResult as-is (they're well-designed)

This removes:

• The 5 OB REMOVE calls
• The "OpenAI subclass for non-OpenAI endpoint" confusion
• The stale-removal-list maintenance burden
• The leaked .models property

[miyako]

4fd09e4

[miyako]

About delegation. Perhaps if OpenAI itself inherited an abstract base class, the non-OpenAI classes could inherit that also, but since OpenAI is currently the base class I was hesitant to make that architectural shift.

[e-marchand]

Interesting point! I still lean toward delegation since Reranker could use other methods beyond API (OpenAI like ones), like in the Python library

I have shared with Product Team a "document" about what a reranker is and why we need it

[miyako]

I've changed the constructor to accept delegation. I did not however apply the AI suggestion to remove the "API" class, since it seems to be the uniform style used throughout AI Kit, even if the API had only a single function.

Here is the code snippet to try the new design

//%attributes = {}
/*

delegation over inheritance

*/

var $apiKey; $baseURL : Text
$apiKey:=Folder:C1567(fk desktop folder:K87:19).file("Cohere.token").getText()
$baseURL:="http://127.0.0.1:8080/v1"
var $Cohere : cs:C1710.OpenAI
$Cohere:=cs:C1710.OpenAI.new({baseURL: "https://api.cohere.ai/v2"; apiKey: $apiKey})

var $Reranker : cs:C1710.Reranker
//syntax 0 (no params)
$Reranker:=cs:C1710.Reranker.new()  //provider=openai (no rerank endpoint)

//syntax 1.a (text)
$Reranker:=cs:C1710.Reranker.new($apiKey)  //provider=openai (no rerank endpoint)
//syntax 1.b (config)
$Reranker:=cs:C1710.Reranker.new({baseURL: $baseURL})
//syntax 1.c (client)
$Reranker:=cs:C1710.Reranker.new($Cohere)

//syntax 2.a (text;text)
$Reranker:=cs:C1710.Reranker.new(""/*$apiKey*/; $baseURL)
//syntax 2.b (text;config)
$Reranker:=cs:C1710.Reranker.new($apiKey; {baseURL: "https://api.cohere.ai/v2"})
//syntax 2.c (client;config)
$Reranker:=cs.Reranker.new($Cohere; {baseURL: $baseURL; apiKey: ""})

var $query:=cs:C1710.RerankerQuery.new({query: "What is deep learning?"; documents: [\
"Deep learning is a subset of machine learning based on artificial neural networks."; \
"Apples are red and sweet fruits that grow on trees."; \
"The theory of relativity was developed by Albert Einstein."; \
"Neural networks simulate the human brain to solve complex problems."\
]})

/*
Not implemented; Cohere specific request properties:

v1
rank_fields
return_documents
max_chunks_per_doc

v2
max_tokens_per_doc
priority

*/

var $parameters:=cs:C1710.RerankerParameters.new({model: "rerank-v4.0-fast"; top_n: 3})

var $result:=$Reranker.rerank.create($query; $parameters)

SET TEXT TO PASTEBOARD:C523(JSON Stringify:C1217($result.results; *))