ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! [`Fusion`] — WHICH fold runs over the member lists, and the one member v1 ships.

/// The fusion strategy a fused retrieve runs.
///
/// # One variant, and the shape is what makes the second one cheap
///
/// v1 ships reciprocal rank fusion and nothing else. It is an enum rather than a bare `k` because
/// the vocabulary is the FRAMEWORK's — a closed set of folds this crate implements, the way
/// [`Dedup`](crate::retrieve::Seen)'s two mechanisms are — and a second member is then an arm plus
/// a match, at every call site the compiler can find. Spelling it as a `k` today would make the
/// second fold a signature change instead.
///
/// # The families this type refuses BY NAME
///
/// CombSUM, CombMNZ, weighted score interpolation — every fold that ADDS or averages the members'
/// SCORES — are refused, and the refusal is the whole reason the parameter is a rank and not a
/// score. A BM25 relevance and a cosine similarity are two currencies; adding them produces a number
/// whose ordering depends on which engine happened to be scaled larger, which is not a ranking of
/// anything. Normalising first only moves the problem: a min-max normalisation over one query's
/// returned window is a function of the window, so the same document scores differently depending on
/// what else came back.
///
/// A CUSTOM fold — a trait seam a third party implements — is deferred to demand rather than
/// refused. Nothing here forecloses it: an open seam arrives as one more variant carrying the
/// implementor, and this type is where it would land.
///
/// Per-modality WEIGHTS are a named future knob, and the shape they take is additive: RRF's own term
/// gains a coefficient, `wᵢ / (k + rank)`. That is a widening of [`Rrf`](Self::Rrf) rather than a new
/// member, and it is not built because no ruling has set what a weight means.
///
/// # `#[non_exhaustive]`, and what it costs whom
///
/// The two paragraphs above both end in *one more variant*, so the attribute is the accurate
/// statement rather than a precaution. It costs a DOWNSTREAM `match` a wildcard arm and costs this
/// crate's own fold nothing, the attribute being invisible inside the crate that defines it — and no
/// downstream `match` is expected anyway: a client BUILDS one of these and the emitted face passes
/// it through, which is the direction the attribute leaves untouched.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Fusion {
  /// Reciprocal rank fusion: each member contributes `1 / (k + rank)` to every root it ranked, and a
  /// root's fused score is the sum over the members that ranked it.
  ///
  /// `k` damps the top of each list. At `k = 0` a first place is worth `1.0` and a second `0.5`, so
  /// one member's opinion about its top hit outweighs every agreement below it; raising `k`
  /// flattens the curve until being ranked AT ALL by two members beats being ranked first by one.
  /// That trade is the only thing the number does, which is why it is a query parameter rather than
  /// a constant: the crossover a corpus wants is a property of the corpus.
  Rrf {
    /// The damping constant — [`Fusion::RRF_K`] unless the query says otherwise.
    k: u32,
  },
}

impl Fusion {
  /// The shipped `k`, and the value the wire's `rrfK` argument defaults to.
  ///
  /// 60 is the constant from the fusion literature the ruling names, and it is a RULED constant
  /// rather than a tuning knob with a default: the number is the law, and a query that wants
  /// another one says so in the query.
  pub const RRF_K: u32 = 60;

  /// Reciprocal rank fusion at the shipped [`RRF_K`](Self::RRF_K).
  #[inline]
  #[must_use]
  pub const fn rrf() -> Self {
    Self::Rrf { k: Self::RRF_K }
  }
}

/// The fold a fused retrieve runs when its caller names none.
impl Default for Fusion {
  #[inline]
  fn default() -> Self {
    Self::rrf()
  }
}

#[cfg(test)]
mod tests;