Module retrieval 

Ranked retrieval over the experiment pool.

The pool exists to answer “what have I already tried that bears on this?”, which is four questions at once: does the text match, does the architecture look like mine, is it recent enough to still be about the same code, and is it worth reading at all. The score adds them:

0.40 · lexical + 0.25 · structural + 0.15 · recency + 0.20 · importance

Additive, not multiplicative. A product lets any single term veto a record: an experiment from last year scores ~0 on recency and therefore ~0 overall, when a year-old dead end is exactly the kind of thing the pool exists to surface. Terms that do not apply (no query architecture, no timestamps to compare) have their weight redistributed over the rest, so scores stay comparable across queries instead of silently shrinking.

Lexical relevance is BM25 (k1 = 1.2, b = 0.75) over a document built by repeating each field: a term in the experiment’s name counts three times, in its conclusion headline twice, in its notes once. No stemming — experiment vocabulary is mostly identifiers and acronyms, which stemmers mangle.

Failures rank. importance puts a floor under any record that failed, crashed or regressed and carries a conclusion. Cutting experimental cost means not repeating dead ends, not only repeating wins.

Everything here is deterministic: now is a parameter, ordering ties break on id, and no clock or RNG is read.

Structs

RetrievalQuery

What to retrieve, and what to measure it against.

ScoreComponents

The four terms behind a score, so a result can explain itself.

ScoredRecord

A record and why it came back.

Constants

DEFAULT_HALF_LIFE_DAYS

Age at which recency has halved.

Traits

Embedder

Turns text into a vector. Not implemented by soma: the seam exists so an embedding model can be plugged in from outside (a sentence-transformer behind the Python worker, an HTTP endpoint) without soma taking a dependency on one.

Functions

embedding_text

The text an embedder should be given for a record: the same fields BM25 indexes, without the repetition weighting.

importance

How much this record is worth reading, in [0, 1].

is_dead_end

A run that failed, crashed, or moved every metric the wrong way.

rank

Rank records against query, best first.

recency

Exponential decay with a half-life, in (0, 1]. A record from the future (clock skew) scores 1.0 rather than exploding.

tokenize

Lowercase alphanumeric terms, splitting snake_case, kebab-case, dotted paths and camelCase. No stemming: experiment vocabulary is identifiers and acronyms, which stemmers only damage.