Safe default for Context.score

[jamesbraza]

Context.score is used for sorting the contextual summaries, so it's really a relative metric (not an absolute one). However, when constructing a standalone Context (outside of Docs.aget_evidence), it puts one in a regime of thinking in absolute terms.

Secondly, if one forgets to specify the score it's defaulted to 5, which may or may not be appropriate.

This PR updates the default score to -1 so at least the default behavior is somewhat safe and requires less thought.

---

Note

Set Context.score default to -1 (via UNSET_RELEVANCE) and document the 0–10 relevance scale.

• Types (src/paperqa/types.py):
  • Context:
    • Introduce UNSET_RELEVANCE = -1 constant.
    • Change score to a Field with default UNSET_RELEVANCE (previously 5) and add description clarifying 0–10 relevance scale and purpose of -1 as sorting-safe default.

^{Written by Cursor Bugbot for commit 3f68f52. Configure here.}

[dosubot]

Related Documentation

Checked 1 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[Copilot]

Pull Request Overview

This pull request updates the Context class to change the default relevance score and improve its documentation. The changes make the "unset" state of the score field more explicit and provide clearer guidance on the scoring scale.

• Changed the default score value from 5 to -1 to explicitly indicate an unset state
• Added a UNSET_RELEVANCE class variable to define the sentinel value
• Enhanced the score field documentation to describe the 0-10 scoring scale

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Changing the default score from 5 to -1 is a breaking change. The comment in core.py line 353-355 states "If we don't assign scores, just default to 5. why 5? Because we filter out 0s in another place and 5/10 is the only default I could come up with". This indicates the previous default was chosen to pass the filtering thresholds. With the new default of -1, any Context objects created without an explicit score will be filtered out by get_unique_docs_from_contexts(score_threshold=0) and context_serializer (which uses evidence_relevance_score_cutoff=1). While production code appears to always set scores explicitly, this could break downstream code or require updates to test fixtures that create Context objects without scores.

Suggested change

	default=UNSET_RELEVANCE,
	description=(
	"Relevance score for this context to the question."
	" The range used here is 0-10, where 0 is 'irrelevant',"
	" 1 is barely relevant, and 10 is most relevant."
	" The default is -1 to have a 'sorting safe' default as sub-relevant."
	default=5,
	description=(
	"Relevance score for this context to the question."
	" The range used here is 0-10, where 0 is 'irrelevant',"
	" 1 is barely relevant, and 10 is most relevant."
	" The default is 5 to pass filtering thresholds."

[jamesbraza]

This comment is basically reverting this PR, see the description. Yes it's a breaking change but it's not a user-facing change, more of a change in PQA internals

[jamesbraza]

The comment in core.py line 353-355 states "If we don't assign scores, just default to 5. why 5? Because we filter out 0s in another place and 5/10 is the only default I could come up with".

Per this, it's fine that aget_evidence has its own internal defaults. This PR is about Context as a generally-useful primitive data structure