starfuzz/rank

A module providing ranking and composite scoring capabilities. Multiple scoring signals can be combined with weights into a single score, with automatic weight normalization and stable tie-breaking descending sorting.

Types

ComponentScore

</>

A component score result for a single named signal.

pub type ComponentScore {
  ComponentScore(name: String, score: Float, weight: Float)
}

Constructors

ComponentScore(name: String, score: Float, weight: Float)

RankBuilder

</>

An immutable ranking builder configuration.

pub type RankBuilder(candidate) {
  RankBuilder(
    signals: List(Signal(candidate)),
    min_score: Float,
    limit: option.Option(Int),
  )
}

Constructors

RankBuilder(
  signals: List(Signal(candidate)),
  min_score: Float,
  limit: option.Option(Int),
)

RankError

</>

Represents ranking computation errors.

pub type RankError {
  ZeroWeightSum
  NegativeWeight(String)
}

Constructors

```
ZeroWeightSum
```
Returned when the sum of all weights equals zero (cannot normalize).
```
NegativeWeight(String)
```
Returned when a signal has a negative weight (weights must be positive).

Ranking

</>

A candidate ranked with its combined score and contributing component scores.

pub type Ranking(candidate) {
  Ranking(
    candidate: candidate,
    score: Float,
    components: List(ComponentScore),
  )
}

Constructors

Ranking(
  candidate: candidate,
  score: Float,
  components: List(ComponentScore),
)

Scorer

</>

A function to compute a similarity score for a candidate.

pub type Scorer(candidate) =
  fn(candidate) -> Float

Signal

</>

A named scoring signal with its relative weight and scoring function.

pub type Signal(candidate) {
  Signal(
    name: String,
    weight: Float,
    scorer: fn(candidate) -> Float,
  )
}

Constructors

Signal(
  name: String,
  weight: Float,
  scorer: fn(candidate) -> Float,
)

Values

add_signal

</>

pub fn add_signal(
  builder: RankBuilder(candidate),
  name: String,
  weight: Float,
  scorer: fn(candidate) -> Float,
) -> RankBuilder(candidate)

Adds a named scoring signal with its weight and scorer callback.

builder

</>

pub fn builder() -> RankBuilder(candidate)

Creates a new default RankBuilder with no signals, min score of 0.0, and no limit.

calculate

</>

pub fn calculate(
  builder: RankBuilder(candidate),
  candidates: List(candidate),
) -> Result(List(Ranking(candidate)), RankError)

Calculates combined rankings for a list of candidates. Returns ranked items sorted descending by combined score, with index-based stable sorting.

combine

</>

pub fn combine(
  components: List(ComponentScore),
) -> Result(Float, RankError)

Combines a list of component scores using a weighted average. Auto-normalizes weights: sum(score * weight) / sum(weight).

with_limit

</>

pub fn with_limit(
  builder: RankBuilder(candidate),
  limit: Int,
) -> RankBuilder(candidate)

Configures a limit on the number of returned rankings.

with_minimum_score

</>

pub fn with_minimum_score(
  builder: RankBuilder(candidate),
  min_score: Float,
) -> RankBuilder(candidate)

Configures the minimum combined score threshold. Rankings below this are discarded.