Tuning Discovery

Discovery is designed to improve as you curate. It is normal for a new library to feel noisy at first. The fastest path to better results is to give the recommender clearer evidence.

Quick wins

1. Save more papers. Discovery is data-starved with a tiny library.
2. Use Like and Love deliberately. Those ratings carry more positive weight than a neutral save.
3. Dismiss obviously wrong recommendations so the lens stops recycling them.
4. Use Dislike when the paper should stay visible in normal flows but should teach the ranker "less like this".
5. Refresh after making changes. Weights and actions affect the next refresh, not already-materialized rows.

What gets shown vs hidden

Two filters apply on top of all the ranking math, and only two:

• Saved papers never reappear. Once a paper is in your Library (status='library'), Discovery permanently excludes it. That's the canonical "you already have this" signal.
• Dismissed suggestions cool down per lens. Dismiss changes visibility in that lens; Dislike records global negative preference.

Everything else in your corpus is fair game on a refresh — including papers your other workflows already pulled in but that you haven't saved yet (status tracked). They might have been overshadowed by a dominant author or topic the first time around; with new feedback they can re-rank into the top-K and get a second look.

If the same paper keeps re-appearing and you don't want it to, Dismiss it — that's the correct lever, not Save.

Single-author dominance

If your library is heavily skewed toward one author (e.g. your PI), you'll feel two things without intervention:

1. The author affinity signal would saturate around that one author and bury everyone else.
2. The "taste-author" external retrieval lane would fire explicit author-name searches at OpenAlex and Semantic Scholar, which just amplifies that same author back into the candidate pool.

Discovery counters both:

• Log-prevalence affinity weighting. A co-author appearing on 5 of 100 saved papers used to score 0.05 against the dominant author's 1.0; with log-prevalence they score around 0.4 — meaningful enough to compete on merit when other signals agree.
• Dominant authors don't drive external queries. Any author who appears on more than 40% of your saved papers is excluded from the taste-author lane's explicit search list. They still get full ranking credit through author_affinity on candidates pulled in by other lanes — they just stop being the explicit search query.
• Per-author cap in the staged top-K. No single first/last author is allowed more than two slots in a refresh. If the ranker produces three, the third moves to an overflow queue and is only shown if there are slots left after the rest of the top-K is filled.
• Per-source-key cap. No single external query (one taste-author, one taste-topic, etc.) can supply more than ~25% of the staged set. Forces lateral diversity across queries.

Weights

Every signal that feeds the ranker is weighted, normalized to sum to 1.0, and configurable. Settings → Discovery weights exposes the ten signals documented in Scoring formulas. The defaults give roughly:

Signal	Default share
topic	~18%
retrieval	~14%
author	~14%
semantic (SPECTER2 embeddings)	~13%
recency	~9%
feedback	~9%
preference	~9%
lexical (terminology overlap)	~5%
citation	~5%
venue	~5%

So a perfect SPECTER2 cosine of 1.00 contributes at most ~13% of the final score — it influences the ranking but does not dominate it. One slider, Semantic + Lexical (weights.text_similarity), drives both text families: semantic takes 70% of it and lexical 30%. Lower it to make text matter less, raise it to make it dominate. The ranker re-normalizes against the budget every refresh.

Shares are shown for a paper where everything is measured. A family with nothing to measure — no journal, no citation count, no embedding yet — is dropped and the rest are rescaled, so a thin-metadata paper is scored on what is actually known about it rather than being charged for the blank columns.

Common adjustments:

Goal	Adjustment
More recent papers	Raise Recency. Or switch mode to Explore, which multiplies recency by 1.5× and halves author, venue and citation.
Less old-hit citation bias	Lower Citation.
Stronger influence from your ratings	Raise Feedback and Preference.
Fewer same-author recommendations	Lower Author (the diversity cap already prevents >2/author in the top-K, so usually no further tuning needed).
Less semantic dominance	Lower Semantic + Lexical.

The weights are stored in ALMa's discovery_settings store and apply on the next lens refresh. Each lens can also carry its own override that merges on top of the global defaults.

What Feedback Teaches

Paper feedback is projected onto the surrounding scholarly graph:

Signal you give	Ranking effect
Like / Love / high rating	Raises the paper, its main authors and co-authors, dominant topics, venue, keywords, tags, close semantic neighbours, and local citation neighbours.
Dislike / low rating / remove paper	Lowers the same connected signals without deleting papers or unfollowing authors.
Follow author	Adds a positive author signal to Discovery and weakly boosts that author's profile.
Dismiss / remove author	Adds a negative author signal to Discovery and weakly lowers that author's profile.
Repeated feedback in one area	Accumulates into stronger topic / venue / author priors, decayed over time.

Author suggestions listen to the same paper-feedback projection. If you love papers by an author, that author and nearby candidates get a reasonable bump. If you dislike papers from a topic or venue, authors connected to that pattern lose rank unless other evidence outweighs it.

Multi-source consensus

A candidate found by more than one retrieval lane gets a small, diminishing-returns score bonus on top of its weighted-signal score. The "Why this surfaced" panel surfaces this as a Found by N sources chip (in brand-blue) when at least 2 lanes independently agreed — the chip is the first in the chip row because it's the strongest "why" signal we have. The chip is informational — the bonus is already in the score. It exists so you know why a card outranked another that looked similar in the ten signals.

The provenance chips are now plain-language bands rather than raw signal numbers — e.g. "close topic", "related wording", "Matches what you save", or "Near a disliked paper". The exact underlying figure is shown on hover, and the full numeric breakdown still lives in the Score Breakdown panel.

Refreshing and visible cards

A lens refresh stages 50 cards on the page after all filters and diversity caps. To keep the initial scroll focused, only the first 20 cards render by default — click Show all 50 recommendations below the list to expand the rest. Switching lenses resets to the curated 20.

The refresh now runs in the background job pool: the POST returns instantly and a live in-page banner shows while the job runs, self-clearing when it finishes. You can keep reading the current cards while the new set is built.

The four retrieval lanes (lexical, vector, graph, external) each emit their own row in the Activity panel under the parent Lens refresh row, so you can see exactly which lane was slow or which one failed without digging through one combined log stream.

Outcome calibration

ALMa quietly tracks whether each retrieval source's recommendations produce positive versus explicit negative preference and reweights the source on subsequent refreshes. A source where negative outcomes dominate gets pulled toward 0.5×; a source where saves dominate gets pushed toward 1.5×. Three axes calibrate independently — the API the candidate came from, the lane mode (core/explore/safe), and the specific branch — composed multiplicatively so a single hot axis can't push past the per-axis ceiling. On a fresh DB the multiplier is 1.0 (no behavior change); the system warms up over a few weeks of normal use. The score breakdown carries source_calibration_multiplier and per-axis components so you can audit what moved.

Retrieval strategies

The Settings card also lets you toggle retrieval lanes on and off. Current strategies include:

• related_works
• topic_search
• followed_authors
• coauthor_network
• citation_chain
• semantic_scholar
• branch_explorer
• taste_topics
• taste_authors
• taste_venues
• recent_wins

Disabling a strategy removes it from the candidate pool entirely.

Branch controls

Inside a lens, Branch view gives you the sharpest local controls:

• Pin — keep this branch important
• Boost — increase its weight
• Mute — suppress it
• Cool / reset — clear earlier tuning

These controls feed into the next refresh of that lens.

Dismiss vs Dislike

Action	Effect
Dismiss	Hides the recommendation in this lens without changing preference. Repeat dismissals extend the lens-local visibility cooldown.
Dislike	Sets a 1-star rating and records a negative signal. The recommendation stays visible.

Use Dismiss when the paper is wrong for this lens. Use Dislike when you want to teach the ranker. Combine both for “bad and gone”. Like and Love follow the same rule on the positive side: they rate the paper but do not save or hide it.

The tuning loop on main

There is no separate training page in the current public build. The learning loop comes from the normal product surfaces:

• Save / Like / Love from Feed
• Save / Reading list / Like / Love from Discovery
• Dismiss / Dislike in Discovery
• Reading history
• Passive interaction signals such as abstract views and outbound clicks

That keeps the public product simpler while still letting Discovery adapt over time.