infinity-context 0.1.0__py3-none-any.whl

infinity_context_core/application/context_canonical_fact_retrieval.py

@@ -0,0 +1,409 @@
+"""Plan-aware retrieval and ranking for canonical facts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from infinity_context_core.application import (
+    context_building_legacy_candidate_adapter as _candidate_policy,
+)
+from infinity_context_core.application.context_query_expansion import (
+    QueryExpansion,
+    QueryExpansionPlan,
+)
+from infinity_context_core.application.context_query_relevance_ranking import (
+    query_reason_priority_for_relevance,
+    query_relevance_rank_key,
+)
+from infinity_context_core.application.context_relevance import (
+    QueryRelevance,
+    has_project_identity_mismatch,
+    is_fact_candidate_relevance_sufficient,
+    score_query_relevance,
+)
+from infinity_context_core.application.dto import BuildContextQuery
+from infinity_context_core.domain.entities import MemoryFact
+from infinity_context_core.ports.repositories import ActiveFactSearch, FactRepositoryPort
+
+_MAX_FAIR_DERIVED_HEADS_PER_QUERY = 8
+_MAX_FAIR_DERIVED_RESERVED = 20
+_MAX_CANONICAL_FACT_CANDIDATES = 200
+_DEFAULT_CANONICAL_FACT_SEARCH_CAP = 100
+_DEFAULT_CANONICAL_FACT_RERANK_CAP = 40
+_CURRENT_TRUTH_DERIVED_CANONICAL_REASONS = frozenset(
+    {
+        "current_state_temporal_bridge",
+        "decomposition_knowledge_update_current",
+    }
+)
+
+
+@dataclass(frozen=True)
+class CanonicalFactMatch:
+    """A canonical fact paired with the query that best retrieved it."""
+
+    fact: MemoryFact
+    query: str
+    reason: str
+    relevance: QueryRelevance
+
+
+@dataclass(frozen=True)
+class CanonicalFactQueryResult:
+    """Raw repository result for one bounded retrieval query."""
+
+    retrieval_query: QueryExpansion
+    facts: tuple[MemoryFact, ...]
+
+
+@dataclass(frozen=True)
+class CanonicalFactRetrievalResult:
+    """Fused fact candidates plus enough metadata for later reranking."""
+
+    matches: tuple[CanonicalFactMatch, ...]
+    query_results: tuple[CanonicalFactQueryResult, ...]
+    request_count: int
+    raw_fact_count: int
+    batch_api_used: bool
+
+
+@dataclass(frozen=True)
+class CanonicalFactSelectionResult:
+    """Collector-ready canonical facts and retrieval diagnostics."""
+
+    facts: tuple[MemoryFact, ...]
+    matches: tuple[CanonicalFactMatch, ...]
+    diagnostics: dict[str, object]
+
+
+async def collect_plan_aware_active_facts(
+    repository: FactRepositoryPort,
+    *,
+    query: BuildContextQuery,
+    memory_scope_ids: tuple[str, ...],
+    query_plan: QueryExpansionPlan | None,
+) -> CanonicalFactSelectionResult:
+    """Apply bounded planning plus canonical and protected-head selection."""
+
+    retrieval_queries = _candidate_policy._bounded_derived_retrieval_queries(
+        query_plan,
+        fallback=query.query,
+    )
+    retrieval = await retrieve_plan_aware_active_facts(
+        repository,
+        space_id=str(query.space_id),
+        memory_scope_ids=memory_scope_ids,
+        thread_id=str(query.thread_id) if query.thread_id else None,
+        retrieval_queries=retrieval_queries,
+        total_limit=query.max_facts,
+        category=query.category,
+        tags_any=query.tags_any,
+        tags_all=query.tags_all,
+        tags_none=query.tags_none,
+    )
+    matches = retrieval.matches[: canonical_fact_rerank_pool_limit(query.max_facts)]
+    return CanonicalFactSelectionResult(
+        facts=tuple(match.fact for match in matches),
+        matches=matches,
+        diagnostics={
+            "canonical_fact_query_count": retrieval.request_count,
+            "canonical_fact_query_reasons": [item.reason for item in retrieval_queries],
+            "canonical_fact_search_batch_api_used": int(retrieval.batch_api_used),
+            "canonical_fact_search_raw_fact_count": retrieval.raw_fact_count,
+        },
+    )
+
+
+async def retrieve_plan_aware_active_facts(
+    repository: FactRepositoryPort,
+    *,
+    space_id: str,
+    memory_scope_ids: tuple[str, ...],
+    thread_id: str | None,
+    retrieval_queries: tuple[QueryExpansion, ...],
+    total_limit: int,
+    category: str | None = None,
+    tags_any: tuple[str, ...] = (),
+    tags_all: tuple[str, ...] = (),
+    tags_none: tuple[str, ...] = (),
+) -> CanonicalFactRetrievalResult:
+    """Fetch, relevance-rank, and fuse canonical facts across a bounded query plan."""
+
+    candidate_limit = canonical_fact_rerank_pool_limit(total_limit)
+    if candidate_limit <= 0:
+        return CanonicalFactRetrievalResult((), (), 0, 0, False)
+    indexed_queries = _dedupe_retrieval_queries(retrieval_queries)
+    base_search_limit = canonical_fact_candidate_limit(total_limit)
+    searches = tuple(
+        ActiveFactSearch(
+            space_id=space_id,
+            memory_scope_ids=memory_scope_ids,
+            thread_id=thread_id,
+            query=retrieval_query.query,
+            limit=base_search_limit,
+            category=category,
+            tags_any=tags_any,
+            tags_all=tags_all,
+            tags_none=tags_none,
+        )
+        for _, retrieval_query in indexed_queries
+    )
+    find_active_many = getattr(repository, "find_active_many", None)
+    if searches and callable(find_active_many):
+        fact_groups = await find_active_many(searches)
+        batch_api_used = True
+    else:
+        fact_groups = [
+            await repository.find_active(
+                space_id=search.space_id,
+                memory_scope_ids=search.memory_scope_ids,
+                thread_id=search.thread_id,
+                query=search.query,
+                limit=search.limit,
+                category=search.category,
+                tags_any=search.tags_any,
+                tags_all=search.tags_all,
+                tags_none=search.tags_none,
+            )
+            for search in searches
+        ]
+        batch_api_used = False
+
+    query_results: list[CanonicalFactQueryResult] = []
+    rankings: dict[str, tuple[str, ...]] = {}
+    ranked_matches_by_query: list[tuple[QueryExpansion, tuple[CanonicalFactMatch, ...]]] = []
+    match_by_id: dict[str, CanonicalFactMatch] = {}
+    for (index, retrieval_query), facts in zip(indexed_queries, fact_groups, strict=True):
+        fact_tuple = tuple(facts)
+        query_results.append(
+            CanonicalFactQueryResult(
+                retrieval_query=retrieval_query,
+                facts=fact_tuple,
+            )
+        )
+        ranked_matches = rank_fact_matches_for_query(
+            fact_tuple,
+            retrieval_query=retrieval_query,
+            limit=len(fact_tuple),
+        )
+        ranked_matches_by_query.append((retrieval_query, ranked_matches))
+        rankings[_candidate_policy._retrieval_query_rank_key(index, retrieval_query)] = tuple(
+            str(match.fact.id) for match in ranked_matches
+        )
+        for match in ranked_matches:
+            fact_id = str(match.fact.id)
+            current = match_by_id.get(fact_id)
+            if current is None or _fact_match_is_preferred(match, current=current):
+                match_by_id[fact_id] = match
+
+    original_head_ids = tuple(
+        ranking[0]
+        for ranking_key, ranking in rankings.items()
+        if ranking and ranking_key.endswith(":original_query")
+    )
+    protected_ids = _candidate_policy._protected_query_head_keys(rankings)
+    fair_derived_ids = _fair_strong_derived_head_keys(
+        tuple(ranked_matches_by_query),
+        excluded_ids=frozenset((*original_head_ids, *protected_ids)),
+        limit=min(_MAX_FAIR_DERIVED_RESERVED, candidate_limit // 2),
+    )
+    selected_ids = tuple(
+        dict.fromkeys(
+            (
+                *original_head_ids,
+                *protected_ids,
+                *fair_derived_ids,
+                *_candidate_policy._fused_ranked_keys(
+                    rankings,
+                    limit=candidate_limit,
+                    max_rank_floor=candidate_limit,
+                ),
+            )
+        )
+    )[:candidate_limit]
+    return CanonicalFactRetrievalResult(
+        matches=tuple(match_by_id[fact_id] for fact_id in selected_ids if fact_id in match_by_id),
+        query_results=tuple(query_results),
+        request_count=len(searches),
+        raw_fact_count=sum(len(group) for group in fact_groups),
+        batch_api_used=batch_api_used,
+    )
+
+
+def rank_fact_matches_for_query(
+    facts: tuple[MemoryFact, ...],
+    *,
+    retrieval_query: QueryExpansion,
+    limit: int,
+) -> tuple[CanonicalFactMatch, ...]:
+    if limit <= 0 or not facts:
+        return ()
+    ranked: list[tuple[tuple[float | int, ...], CanonicalFactMatch]] = []
+    for index, fact in enumerate(facts):
+        match = canonical_fact_match(fact, retrieval_query=retrieval_query)
+        if has_project_identity_mismatch(query=match.query, text=fact.text):
+            continue
+        if not _canonical_fact_match_is_admissible(match):
+            continue
+        if not is_fact_candidate_relevance_sufficient(match.relevance):
+            continue
+        ranked.append(((*_relevance_rank_key(match.relevance), -index), match))
+    ranked.sort(key=lambda item: item[0], reverse=True)
+    return tuple(match for _, match in ranked[:limit])
+
+
+def canonical_fact_match(
+    fact: MemoryFact,
+    *,
+    retrieval_query: QueryExpansion,
+) -> CanonicalFactMatch:
+    return CanonicalFactMatch(
+        fact=fact,
+        query=retrieval_query.query,
+        reason=retrieval_query.reason,
+        relevance=score_query_relevance(
+            query=retrieval_query.query,
+            text=fact.text,
+            max_boost=0.03,
+        ),
+    )
+
+
+def canonical_fact_candidate_limit(max_facts: int) -> int:
+    if max_facts <= 0:
+        return 0
+    return min(
+        _MAX_CANONICAL_FACT_CANDIDATES,
+        max(_DEFAULT_CANONICAL_FACT_SEARCH_CAP, max_facts),
+        max(max_facts * 4, max_facts + 8),
+    )
+
+
+def canonical_fact_rerank_pool_limit(max_facts: int) -> int:
+    if max_facts <= 0:
+        return 0
+    return min(
+        _MAX_CANONICAL_FACT_CANDIDATES,
+        max(_DEFAULT_CANONICAL_FACT_RERANK_CAP, max_facts),
+        max(max_facts * 4, max_facts + 3),
+    )
+
+
+def _fair_strong_derived_head_keys(
+    ranked_matches_by_query: tuple[tuple[QueryExpansion, tuple[CanonicalFactMatch, ...]], ...],
+    *,
+    excluded_ids: frozenset[str],
+    limit: int,
+) -> tuple[str, ...]:
+    if limit <= 0:
+        return ()
+    lanes = tuple(
+        _strong_unique_lane_ids(ranked_matches)
+        for retrieval_query, ranked_matches in ranked_matches_by_query
+        if retrieval_query.reason != "original_query"
+    )
+    selected: list[str] = []
+    seen = set(excluded_ids)
+    for depth in range(_MAX_FAIR_DERIVED_HEADS_PER_QUERY):
+        for lane in lanes:
+            if depth >= len(lane):
+                continue
+            fact_id = lane[depth]
+            if fact_id in seen:
+                continue
+            seen.add(fact_id)
+            selected.append(fact_id)
+            if len(selected) >= limit:
+                return tuple(selected)
+    return tuple(selected)
+
+
+def _strong_unique_lane_ids(
+    ranked_matches: tuple[CanonicalFactMatch, ...],
+) -> tuple[str, ...]:
+    selected: list[str] = []
+    seen: set[str] = set()
+    for match in ranked_matches:
+        fact_id = str(match.fact.id)
+        if fact_id in seen or not _is_strong_derived_match(match.relevance):
+            continue
+        seen.add(fact_id)
+        selected.append(fact_id)
+        if len(selected) >= _MAX_FAIR_DERIVED_HEADS_PER_QUERY:
+            break
+    return tuple(selected)
+
+
+def _is_strong_derived_match(relevance: QueryRelevance) -> bool:
+    return (
+        relevance.hit_ratio >= 0.6
+        and relevance.unique_term_hits >= 3
+        and relevance.distinctive_term_hits >= 3
+        and (relevance.phrase_bigram_hits > 0 or relevance.distinctive_term_hits >= 4)
+    )
+
+
+def _is_strong_current_truth_match(relevance: QueryRelevance) -> bool:
+    return (
+        relevance.hit_ratio >= 0.15
+        and relevance.unique_term_hits >= 4
+        and relevance.distinctive_term_hits >= 4
+        and (relevance.phrase_bigram_hits > 0 or relevance.distinctive_term_hits >= 5)
+    )
+
+
+def _canonical_fact_match_is_admissible(match: CanonicalFactMatch) -> bool:
+    if match.reason == "original_query":
+        return True
+    if match.reason in _CURRENT_TRUTH_DERIVED_CANONICAL_REASONS:
+        return _is_strong_current_truth_match(match.relevance)
+    return query_reason_priority_for_relevance(
+        match.reason, match.relevance
+    ) > 0 or _is_strong_derived_match(match.relevance)
+
+
+def _dedupe_retrieval_queries(
+    retrieval_queries: tuple[QueryExpansion, ...],
+) -> tuple[tuple[int, QueryExpansion], ...]:
+    result: list[tuple[int, QueryExpansion]] = []
+    seen: set[str] = set()
+    for index, retrieval_query in enumerate(retrieval_queries):
+        normalized = " ".join(retrieval_query.query.split()).casefold()
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        result.append((index, retrieval_query))
+    return tuple(result)
+
+
+def _match_rank_key(match: CanonicalFactMatch) -> tuple[float | int, ...]:
+    return query_relevance_rank_key((match.query, match.reason, match.relevance))
+
+
+def _fact_match_is_preferred(
+    candidate: CanonicalFactMatch,
+    *,
+    current: CanonicalFactMatch,
+) -> bool:
+    if candidate.reason == "original_query" or current.reason == "original_query":
+        derived_reason = (
+            current.reason if candidate.reason == "original_query" else candidate.reason
+        )
+        if derived_reason in _CURRENT_TRUTH_DERIVED_CANONICAL_REASONS:
+            return candidate.reason == "original_query"
+    candidate_rank = _match_rank_key(candidate)
+    current_rank = _match_rank_key(current)
+    if candidate_rank != current_rank:
+        return candidate_rank > current_rank
+    return candidate.reason == "original_query" and current.reason != "original_query"
+
+
+def _relevance_rank_key(relevance: QueryRelevance) -> tuple[float | int, ...]:
+    return (
+        relevance.phrase_bigram_hits,
+        relevance.phrase_boost,
+        relevance.score_boost,
+        relevance.unique_term_hits,
+        relevance.hit_ratio,
+        relevance.capped_frequency_hits,
+    )

infinity_context_core/application/context_causal_reason_rerank.py

@@ -0,0 +1,145 @@
+"""Causal reason rerank signals for why/reason memory queries."""
+
+from __future__ import annotations
+
+import re
+
+from infinity_context_core.application.context_domain_rerank_signals import DomainRerankSignal
+from infinity_context_core.application.context_relevance import QueryRelevance
+from infinity_context_core.application.context_score_signal_rerank import score_signal_reason
+from infinity_context_core.application.dto import ContextItem
+
+_CAUSAL_REASON_RERANK_REASONS = frozenset(
+    (
+        "business_start_reason_bridge",
+        "charity_brand_sponsorship_bridge",
+        "family_motivation_context_bridge",
+        "motivation_reason_bridge",
+        "pottery_color_reason_bridge",
+        "running_reason_bridge",
+        "running_reason_question_bridge",
+        "shelter_comfort_reason_bridge",
+        "support_career_motivation_bridge",
+        "yoga_delay_gaming_bridge",
+    )
+)
+_CAUSAL_REASON_QUERY_RE = re.compile(
+    r"\b(?:why|reason|because|cause|caused|gave|motivat(?:e|ed|ion)|"
+    r"inspired?|led\s+to|made\s+(?:me|her|him|them)|sense\s+of\s+belonging)\b|"
+    r"\b(?:почему|причин\w*|потому|мотивир\w*|вдохнов\w*)\b",
+    re.IGNORECASE,
+)
+_CAUSAL_REASON_MARKER_RE = re.compile(
+    r"\b(?:because|so|since|therefore|as\s+a\s+result|which\s+made|"
+    r"that\s+made|this\s+made|led\s+(?:me|her|him|them)?\s*to|"
+    r"inspired|motivated|made\s+(?:me|her|him|them)\s+(?:feel|realize|want)|"
+    r"gave\s+(?:me|her|him|them)|wanted\s+to|in\s+order\s+to|so\s+(?:i|she|he|they))\b|"
+    r"\b(?:потому|поэтому|из-за|вдохнов\w*|мотивир\w*|чтобы)\b",
+    re.IGNORECASE,
+)
+_CAUSAL_REASON_DOMAIN_EVIDENCE_RE = re.compile(
+    r"\b(?:lost\s+(?:her|his|their|my)?\s*(?:door\s+dash\s+)?job|job\s+loss|"
+    r"passionate\s+about\s+fashion|blend\s+dance\s+and\s+fashion|"
+    r"sitting\s+alone|looking\s+sad|no\s+other\s+family|offered\s+comfort|"
+    r"listening\s+ear|made\s+her\s+laugh|give\s+back|make\s+a\s+difference|"
+    r"inspire\s+people|disadvantaged\s+kids|nike|gatorade|under\s+armou?r|"
+    r"sponsorship|basketball\s+shoe\s+and\s+gear|sports?\s+brands?|"
+    r"working\s+with\s+(?:such\s+)?big\s+brands|walking\s+dead|console\s+games|"
+    r"instead\s+of\s+(?:doing\s+)?yoga|clear\s+(?:my|her|his|their)?\s*head|"
+    r"stress\s+relief|relax|refresh|made\s+me\s+realize|mental\s+health|"
+    r"help\s+people\s+feel\s+safe|catch\s+(?:the\s+)?eye|make\s+people\s+smile)\b",
+    re.IGNORECASE,
+)
+_CAUSAL_REASON_WEAK_TOPIC_RE = re.compile(
+    r"\b(?:mentioned|talked\s+about|discussed|heard\s+about|general\s+planning|"
+    r"notes?|update|topic|context|saw|watched|visited|attended)\b|"
+    r"\b(?:обсуждал\w*|упомянул\w*|заметк\w*|контекст)\b",
+    re.IGNORECASE,
+)
+_YOGA_DELAY_GAMING_PLANNED_PLAY_RE = re.compile(
+    r"\b(?:plan(?:ned|ning)?|arrang(?:ed|ing)?|going|intend(?:ed|ing)?|wanted)\s+"
+    r"(?:to\s+)?(?:play|try)\b"
+    r"(?=.{0,140}\b(?:console|video\s*games?|videogames?|xbox|"
+    r"playstation|nintendo|switch|games?)\b)|"
+    r"\b(?:plan(?:ned|ning)?|arrang(?:ed|ing)?|going)\s+to\s+play\s+"
+    r"\"[^\"\n]{1,80}\""
+    r"(?=.{0,120}\b(?:next|later|tomorrow|weekend|saturday|sunday|"
+    r"monday|tuesday|wednesday|thursday|friday)\b)|"
+    r"\b(?:play|playing)\b"
+    r"(?=.{0,90}\b(?:console|video\s*games?|videogames?|games?)\b)"
+    r"(?=.{0,150}\b(?:partner|next|planned|planning|instead)\b)",
+    re.IGNORECASE | re.DOTALL,
+)
+_YOGA_DELAY_GAMING_ACTIVE_PLAY_RE = re.compile(
+    r"\b(?:gaming|played|playing)\b"
+    r"(?=.{0,120}\b(?:console|video\s*games?|videogames?|games?|xbox|"
+    r"playstation|nintendo|switch)\b)|"
+    r"\b(?:console|video\s*games?|videogames?|games?|xbox|playstation|"
+    r"nintendo|switch)\b"
+    r"(?=.{0,120}\b(?:gaming|played|playing)\b)",
+    re.IGNORECASE | re.DOTALL,
+)
+_YOGA_DELAY_GAMING_BACKGROUND_RE = re.compile(
+    r"\b(?:partner'?s\s+video\s+games|video\s*games?|videogames?|"
+    r"game\s+console|new\s+game\s+console)\b",
+    re.IGNORECASE,
+)
+
+
+def causal_reason_rerank_signal(
+    *,
+    query: str,
+    query_reason: str,
+    item: ContextItem,
+    relevance: QueryRelevance,
+) -> DomainRerankSignal:
+    if not _is_causal_reason_candidate(
+        query=query,
+        query_reason=query_reason,
+        item=item,
+    ):
+        return DomainRerankSignal()
+    if _causal_reason_exact_evidence(item.text) and relevance.distinctive_term_hits >= 3:
+        return DomainRerankSignal(boost=0.026, reason="causal_reason_exact_evidence")
+    if (
+        _CAUSAL_REASON_WEAK_TOPIC_RE.search(item.text) is not None
+        or relevance.distinctive_term_hits >= 4
+    ):
+        return DomainRerankSignal(penalty=0.04, reason="causal_reason_weak_evidence")
+    return DomainRerankSignal()
+
+
+def _is_causal_reason_candidate(
+    *,
+    query: str,
+    query_reason: str,
+    item: ContextItem,
+) -> bool:
+    if query_reason in _CAUSAL_REASON_RERANK_REASONS:
+        return True
+    if _score_signal_reason(item) in _CAUSAL_REASON_RERANK_REASONS:
+        return True
+    return _CAUSAL_REASON_QUERY_RE.search(query) is not None
+
+
+def _causal_reason_exact_evidence(text: str) -> bool:
+    return (
+        _CAUSAL_REASON_MARKER_RE.search(text) is not None
+        or _CAUSAL_REASON_DOMAIN_EVIDENCE_RE.search(text) is not None
+        or yoga_delay_gaming_answer_rank(text) <= 1
+    )
+
+
+def _score_signal_reason(item: ContextItem) -> str:
+    return score_signal_reason(item)
+
+
+def yoga_delay_gaming_answer_rank(text: str) -> int:
+    """Rank English evidence for yoga being displaced by planned gaming."""
+    if _YOGA_DELAY_GAMING_PLANNED_PLAY_RE.search(text) is not None:
+        return 0
+    if _YOGA_DELAY_GAMING_ACTIVE_PLAY_RE.search(text) is not None:
+        return 1
+    if _YOGA_DELAY_GAMING_BACKGROUND_RE.search(text) is not None:
+        return 2
+    return 5

infinity_context_core/application/context_choice_reason_rerank.py

@@ -0,0 +1,109 @@
+"""Choice-reason rerank signals for why/pick/select memory queries."""
+
+from __future__ import annotations
+
+import re
+
+from infinity_context_core.application.context_diagnostics import (
+    safe_diagnostic_mapping,
+    safe_score_signals,
+)
+from infinity_context_core.application.context_domain_rerank_signals import (
+    DomainRerankSignal,
+)
+from infinity_context_core.application.context_relevance import QueryRelevance
+from infinity_context_core.application.dto import ContextItem
+
+_REASON = "choice_reason_bridge"
+_QUERY_RE = re.compile(
+    r"\b(?:why|reason)\b(?=.{0,120}\b(?:choose|chose|chosen|pick|picked|"
+    r"select|selected|choice|option|agency|provider|vendor|tool|model)\b)|"
+    r"\b(?:what\s+made|made\s+(?:you|her|him|them)\s+pick)\b",
+    re.IGNORECASE | re.DOTALL,
+)
+_CHOICE_ACTION_RE = re.compile(
+    r"\b(?:choose|chose|chosen|pick|picked|select|selected|went\s+with)\b",
+    re.IGNORECASE,
+)
+_REASON_MARKER_RE = re.compile(
+    r"\b(?:because|cause|'cause|cuz|since|reason|due\s+to|"
+    r"what\s+made|made\s+(?:me|her|him|them|you)|spoke\s+to\s+(?:me|her|him|them)|"
+    r"stood\s+out|appealed\s+to)\b",
+    re.IGNORECASE,
+)
+_CHOICE_REASON_DOMAIN_RE = re.compile(
+    r"\b(?:help(?:s|ed|ing)?|support(?:s|ed|ing)?|inclusive|inclusivity|"
+    r"lgbtq\+?|adoption|agency|provider|vendor|tool|model|service|option|"
+    r"safe|reliable|trusted|fit|fits|matched|align(?:s|ed)?|available|"
+    r"accessible|recommended|endorsed)\b",
+    re.IGNORECASE,
+)
+_ADOPTION_AGENCY_QUERY_RE = re.compile(
+    r"\b(?:adoption|agency|agencies)\b",
+    re.IGNORECASE,
+)
+_ADOPTION_AGENCY_EVIDENCE_RE = re.compile(
+    r"\b(?:adoption|agency|agencies|lgbtq\+?|inclusive|inclusivity|support)\b",
+    re.IGNORECASE,
+)
+_WEAK_TOPIC_RE = re.compile(
+    r"\b(?:mentioned|discussed|look(?:ing)?\s+into|research(?:ing)?|"
+    r"general\s+planning|dream|hope|goal|summary)\b",
+    re.IGNORECASE,
+)
+
+
+def choice_reason_rerank_signal(
+    *,
+    query: str,
+    query_reason: str,
+    item: ContextItem,
+    relevance: QueryRelevance,
+) -> DomainRerankSignal:
+    """Prefer exact evidence explaining why an option was chosen."""
+
+    if not _is_candidate(query=query, query_reason=query_reason, item=item):
+        return DomainRerankSignal()
+    text = item.text
+    if _exact_choice_reason_evidence(query=query, text=text):
+        return DomainRerankSignal(
+            boost=0.046,
+            reason="choice_reason_exact_evidence",
+            rank_signal_key="choice_reason_answer_evidence",
+            rank_signal=3.0,
+        )
+    if _WEAK_TOPIC_RE.search(text) is not None or relevance.distinctive_term_hits < 3:
+        return DomainRerankSignal(
+            penalty=0.046,
+            reason="choice_reason_weak_evidence",
+        )
+    return DomainRerankSignal()
+
+
+def _is_candidate(*, query: str, query_reason: str, item: ContextItem) -> bool:
+    if query_reason == _REASON:
+        return True
+    diagnostics = safe_diagnostic_mapping(item.diagnostics)
+    signals = safe_score_signals(diagnostics.get("score_signals"))
+    if signals.get("query_expansion_reason") == _REASON:
+        return True
+    return _QUERY_RE.search(query) is not None
+
+
+def _exact_choice_reason_evidence(*, query: str, text: str) -> bool:
+    if (
+        _ADOPTION_AGENCY_QUERY_RE.search(query) is not None
+        and _ADOPTION_AGENCY_EVIDENCE_RE.search(text) is None
+    ):
+        return False
+    if (
+        _ADOPTION_AGENCY_QUERY_RE.search(query) is not None
+        and _REASON_MARKER_RE.search(text) is not None
+        and _CHOICE_REASON_DOMAIN_RE.search(text) is not None
+    ):
+        return True
+    return (
+        _CHOICE_ACTION_RE.search(text) is not None
+        and _REASON_MARKER_RE.search(text) is not None
+        and _CHOICE_REASON_DOMAIN_RE.search(text) is not None
+    )