infinity-context 0.1.0__py3-none-any.whl

infinity_context_core/application/context_stage_diagnostics.py

@@ -0,0 +1,111 @@
+"""Bounded, text-free stage timings for context assembly diagnostics."""
+
+from __future__ import annotations
+
+from math import isfinite
+from time import perf_counter
+
+MAX_CONTEXT_STAGE_DURATION_MS = 86_400_000.0
+
+# Tuple order is the stable public order. Callers cannot add request-derived labels.
+CONTEXT_STAGE_NAMES = (
+    "scope_resolution",
+    "planning_expansion",
+    "canonical_collect",
+    "vector_collect",
+    "graph_collect",
+    "rag_collect",
+    "artifact_evidence",
+    "enrichment_hydration",
+    "final_rank",
+    "rerank",
+    "pack",
+    "response_mapping",
+    "total",
+    "keyword_aggregation_seed",
+    "keyword_chunk_rank",
+    "keyword_aggregation",
+    "keyword_neighbors",
+    "keyword_source_siblings",
+    "exact_source_ref_hydration",
+    "dedupe_hydrate",
+    "temporal_relations",
+    "stale_review",
+    "pending_review",
+    "context_links",
+    "linked_temporal_relations",
+    "final_rank_source_merge",
+    "final_rank_temporal_boost",
+    "final_rank_anchor_boost",
+    "final_rank_requirement_boost",
+    "final_rank_bm25",
+    "final_rank_fusion",
+    "final_rank_deterministic",
+    "final_rank_dedupe",
+)
+MAX_CONTEXT_STAGE_TIMINGS = len(CONTEXT_STAGE_NAMES)
+
+
+def record_context_stage_timing(
+    diagnostics: dict[str, object],
+    stage: str,
+    started_at: float,
+) -> None:
+    """Record elapsed time for one allowlisted stage."""
+    record_context_stage_interval(
+        diagnostics,
+        stage=stage,
+        started_at=started_at,
+        finished_at=perf_counter(),
+    )
+
+
+def record_context_stage_interval(
+    diagnostics: dict[str, object],
+    *,
+    stage: str,
+    started_at: float,
+    finished_at: float,
+) -> None:
+    """Record an explicit interval so sequential stage boundaries stay testable."""
+    record_context_stage_duration(
+        diagnostics,
+        stage=stage,
+        duration_ms=(finished_at - started_at) * 1000,
+    )
+
+
+def record_context_stage_duration(
+    diagnostics: dict[str, object],
+    *,
+    stage: str,
+    duration_ms: object,
+) -> None:
+    """Record one fixed-name duration and reject dynamic stage labels."""
+    if stage not in CONTEXT_STAGE_NAMES:
+        return
+    timings = diagnostics.get("stage_timings_ms")
+    if not isinstance(timings, dict):
+        timings = {}
+        diagnostics["stage_timings_ms"] = timings
+    if len(timings) >= MAX_CONTEXT_STAGE_TIMINGS and stage not in timings:
+        return
+    timings[stage] = _bounded_duration(duration_ms)
+
+
+def normalize_context_stage_timings(value: object) -> dict[str, float]:
+    """Return only allowlisted names with bounded numeric values."""
+    if not isinstance(value, dict):
+        return {}
+    return {
+        stage: _bounded_duration(value[stage]) for stage in CONTEXT_STAGE_NAMES if stage in value
+    }
+
+
+def _bounded_duration(value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return 0.0
+    duration = float(value)
+    if not isfinite(duration):
+        return 0.0
+    return round(min(MAX_CONTEXT_STAGE_DURATION_MS, max(0.0, duration)), 2)

infinity_context_core/application/context_state_evidence.py

@@ -0,0 +1,196 @@
+"""State lifecycle evidence markers for temporal retrieval decisions."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from infinity_context_core.application.dto import ContextItem
+
+_STATUS_KEYS = ("fact_status", "anchor_status", "relation_status", "state_status")
+_ACTIVE_STATUSES = frozenset({"active", "current"})
+_STALE_STATUSES = frozenset(
+    {
+        "deleted",
+        "deprecated",
+        "expired",
+        "inactive",
+        "obsolete",
+        "stale",
+        "superseded",
+    }
+)
+_LIFECYCLE_STATUSES = frozenset((*_ACTIVE_STATUSES, *_STALE_STATUSES, "disputed"))
+_STATE_NOUN = (
+    r"provider|tool|model|option|engine|database|service|plan|policy|"
+    r"decision|choice|source|endpoint|token|rule|setting|config|"
+    r"requirement|scope|memory|note|fact|meeting|call|demo|event|date|time"
+)
+_RU_STATE_NOUN = (
+    r"провайдер\w*|инструмент\w*|модел\w*|вариант\w*|движок\w*|"
+    r"баз\w+\s+данн\w*|сервис\w*|план\w*|политик\w*|решени\w*|"
+    r"выбор\w*|источник\w*|эндпоинт\w*|токен\w*|правил\w*|"
+    r"настройк\w*|конфиг\w*|требовани\w*|скоуп\w*|памят\w*|"
+    r"заметк\w*|факт\w*"
+)
+_ACTIVE_STATE_TEXT_RE = re.compile(
+    r"\b(?:current|currently|active|recommended|preferred|selected|chosen|"
+    r"settled|final|canonical|source\s+of\s+truth)\b|"
+    r"\b(?:still|remain(?:s|ed)?|kept)\b"
+    r"(?=.{0,80}\b(?:valid|active|current|recommended|preferred|use|using|"
+    r"available|chosen|selected|option|plan|provider|tool|model|policy)\b)|"
+    r"\b(?:актуальн\w*|текущ\w*|выбранн\w*|финальн\w*|окончательн\w*)\b|"
+    r"\b(?:вс[её]\s+еще|вс[её]\s+ещ[её]|по-прежнему|остается|остался|"
+    r"осталась|остались)\b"
+    r"(?=.{0,80}\b(?:актуал|действует|валидн|использовать|выбран|"
+    r"вариант|план|провайдер|инструмент|модель|политик)\w*)",
+    re.IGNORECASE | re.DOTALL,
+)
+_STALE_STATE_TEXT_RE = re.compile(
+    r"\b(?:no\s+longer|anymore|any\s+longer|not\s+current)\b"
+    r"(?=.{0,80}\b(?:valid|active|current|recommended|preferred|use|using|"
+    r"available|chosen|selected|option|plan|provider|tool|model|policy)\b)|"
+    r"\b(?:stale|outdated|obsolete|deprecated|expired|superseded)\b|"
+    rf"\b(?:previous|prior|old|former)\s+(?:\w+\s+){{0,3}}(?:{_STATE_NOUN})\b|"
+    rf"\b(?:{_STATE_NOUN})\b(?=.{0,60}\b(?:previous|prior|old|former)\b)|"
+    r"\bpreviously\s+valid\b|"
+    r"\b(?:больше\s+не|уже\s+не|перестал\w*)\b"
+    r"(?=.{0,80}\b(?:актуал|действует|валидн|использовать|выбран|"
+    r"вариант|план|провайдер|инструмент|модель|политик)\w*)|"
+    r"\bустаревш\w*\b|"
+    rf"\b(?:стар\w*|предыдущ\w*)\s+(?:\w+\s+){{0,3}}(?:{_RU_STATE_NOUN})\b|"
+    rf"\b(?:{_RU_STATE_NOUN})\b(?=.{0,60}\b(?:стар\w*|предыдущ\w*)\b)",
+    re.IGNORECASE | re.DOTALL,
+)
+_TRANSITION_STATE_TEXT_RE = re.compile(
+    r"\bchanged?\b(?=.{0,80}\bfrom\b)(?=.{0,120}\bto\b)|"
+    r"\b(?:provider|tool|model|plan|policy|decision|source|option|choice|"
+    r"date|time|meeting|call|demo|event)\b(?=.{0,160}\bnot\b.{0,80}\bbut\b)|"
+    r"\bnot\b(?=.{0,80}\bbut\b)(?=.{0,160}\b(?:provider|tool|model|plan|"
+    r"policy|decision|source|option|choice|date|time|meeting|call|demo|event)\b)|"
+    r"\b(?:switch(?:ed|ing)?|migrat(?:e|ed|ing)|transition(?:ed|ing)?)\b"
+    r"(?=.{0,100}\b(?:from|to)\b)|"
+    r"\breplac(?:e|ed|ing)\b(?=.{0,100}\b(?:by|with|from|to|instead\s+of)\b)|"
+    r"\bsuperseded\b(?=.{0,100}\bby\b)|"
+    r"\b(?:cancell?ed|rescheduled|postponed|moved|delayed)\b"
+    r"(?=.{0,140}\b(?:to|for|until|from|after|instead|new|now|current|"
+    r"latest|date|time|day|week|month|meeting|call|demo|event|plan)\b)|"
+    r"\b(?:изменил\w*|изменилось|обновил\w*|заменил\w*|поменял\w*|"
+    r"сменил\w*|переключил\w*|переш[её]л\w*|мигрировал\w*)\b"
+    r"(?=.{0,100}\b(?:с|со|на|вместо)\b)",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+@dataclass(frozen=True)
+class StateEvidenceMarkers:
+    """Bounded lifecycle markers derived from metadata and item text."""
+
+    metadata_active: bool = False
+    metadata_stale: bool = False
+    metadata_lifecycle: bool = False
+    review_only: bool = False
+    text_active: bool = False
+    text_stale: bool = False
+    text_transition: bool = False
+
+    @property
+    def has_lifecycle(self) -> bool:
+        return (
+            self.metadata_lifecycle
+            or self.text_active
+            or self.text_stale
+            or self.text_transition
+        )
+
+    @property
+    def has_active_state(self) -> bool:
+        return self.metadata_active or self.text_active
+
+    @property
+    def has_previous_state(self) -> bool:
+        return self.review_only or self.metadata_stale or self.text_stale or self.text_transition
+
+    @property
+    def stale_only(self) -> bool:
+        return (
+            self.review_only or self.metadata_stale or self.text_stale
+        ) and not self.has_active_state and not self.text_transition
+
+
+def state_evidence_markers(item: ContextItem) -> StateEvidenceMarkers:
+    diagnostics = item.diagnostics if isinstance(item.diagnostics, Mapping) else {}
+    provenance = _safe_mapping(diagnostics.get("provenance"))
+    metadata_active, metadata_stale, metadata_lifecycle = _metadata_state_markers(
+        diagnostics,
+        provenance,
+    )
+    if str(diagnostics.get("retrieval_source") or "") == "superseded_review":
+        metadata_stale = True
+        metadata_lifecycle = True
+    text_active, text_stale, text_transition = state_text_markers(item.text)
+    return StateEvidenceMarkers(
+        metadata_active=metadata_active,
+        metadata_stale=metadata_stale,
+        metadata_lifecycle=metadata_lifecycle,
+        review_only=diagnostics.get("review_only") is True,
+        text_active=text_active,
+        text_stale=text_stale,
+        text_transition=text_transition,
+    )
+
+
+def state_text_markers(text: str) -> tuple[bool, bool, bool]:
+    """Return active/stale/transition markers without exposing raw regex details."""
+
+    text_active = bool(_ACTIVE_STATE_TEXT_RE.search(text))
+    text_stale = bool(_STALE_STATE_TEXT_RE.search(text))
+    text_transition = bool(_TRANSITION_STATE_TEXT_RE.search(text))
+    return text_active, text_stale, text_transition
+
+
+def item_has_state_lifecycle_evidence(item: ContextItem) -> bool:
+    return state_evidence_markers(item).has_lifecycle
+
+
+def _metadata_state_markers(
+    diagnostics: Mapping[str, object],
+    provenance: Mapping[str, object],
+) -> tuple[bool, bool, bool]:
+    metadata_active = False
+    metadata_stale = False
+    metadata_lifecycle = False
+    for value in (diagnostics, provenance):
+        active, stale, lifecycle = _mapping_state_markers(value)
+        metadata_active = metadata_active or active
+        metadata_stale = metadata_stale or stale
+        metadata_lifecycle = metadata_lifecycle or lifecycle
+    return metadata_active, metadata_stale, metadata_lifecycle
+
+
+def _safe_mapping(value: object) -> Mapping[str, object]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _mapping_state_markers(value: Mapping[str, object]) -> tuple[bool, bool, bool]:
+    metadata_active = False
+    metadata_stale = False
+    metadata_lifecycle = False
+    for key in _STATUS_KEYS:
+        status = str(value.get(key) or "").strip().casefold()
+        if status in _ACTIVE_STATUSES:
+            metadata_active = True
+            metadata_lifecycle = True
+        elif status in _STALE_STATUSES:
+            metadata_stale = True
+            metadata_lifecycle = True
+        elif status in _LIFECYCLE_STATUSES:
+            metadata_lifecycle = True
+    if value.get("is_current") is True:
+        metadata_active = True
+        metadata_lifecycle = True
+    elif value.get("is_current") is False:
+        metadata_stale = True
+        metadata_lifecycle = True
+    return metadata_active, metadata_stale, metadata_lifecycle

infinity_context_core/application/context_state_residence_inference.py

@@ -0,0 +1,163 @@
+"""State residence inference evidence signals."""
+
+from __future__ import annotations
+
+import re
+
+from infinity_context_core.application.context_answer_evidence_types import (
+    AnswerEvidenceSignal,
+)
+from infinity_context_core.application.context_geo_residence_aliases import (
+    named_us_states_in_text,
+    requests_named_state_residence,
+    state_city_alias_terms,
+    state_name_terms,
+)
+from infinity_context_core.application.context_lexical import query_terms
+
+_TOKEN_RE = re.compile(r"\w+", re.UNICODE)
+
+_STATE_RESIDENCE_QUERY_TERMS = frozenset(
+    {
+        "live",
+        "lives",
+        "living",
+        "reside",
+        "residence",
+        "state",
+    }
+)
+_STATE_RESIDENCE_GEO_TEXT_TERMS = frozenset(
+    {
+        "caption",
+        "city",
+        "county",
+        "forest",
+        "hiking",
+        "image",
+        "lake",
+        "map",
+        "minnesota",
+        "national",
+        "park",
+        "photo",
+        "route",
+        "state",
+        "trail",
+        "trails",
+        "trees",
+        "voyageurs",
+    }
+)
+_STATE_RESIDENCE_STRONG_GEO_TERMS = frozenset(
+    {
+        "forest",
+        "hiking",
+        "lake",
+        "map",
+        "national",
+        "park",
+        "route",
+        "state",
+        "trail",
+        "trails",
+        "trees",
+        "voyageurs",
+    }
+)
+_STATE_RESIDENCE_LOCATION_TERMS = frozenset(
+    {
+        "city",
+        "county",
+        "minnesota",
+        "state",
+        "voyageurs",
+    }
+)
+_STATE_RESIDENCE_LOCAL_ACTIVITY_TERMS = frozenset(
+    {
+        "address",
+        "adopted",
+        "city",
+        "county",
+        "home",
+        "live",
+        "lives",
+        "living",
+        "local",
+        "moved",
+        "nearby",
+        "relocated",
+        "reside",
+        "residence",
+        "shelter",
+        "town",
+    }
+)
+_STATE_RESIDENCE_TECHNICAL_NOISE_RE = re.compile(
+    r"\b(?:state\s+machine|state\s+management|app\s+state|"
+    r"frontend|backend|database|code|repository|repo|workflow|config)\b|"
+    r"\b(?:map|mapping)\b.{0,80}\b(?:code|app|schema|database|object)\b",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def state_residence_inference_signal(*, query: str, text: str) -> AnswerEvidenceSignal:
+    """Return evidence-fit signal for inferred US state residence questions."""
+
+    if not _requests_state_residence_inference(query):
+        return AnswerEvidenceSignal()
+    text_tokens = _term_set(text)
+    query_states = named_us_states_in_text(query)
+    city_alias_hits = text_tokens & state_city_alias_terms(query_states)
+    state_name_hits = text_tokens & state_name_terms(query_states)
+    local_activity_hits = text_tokens & _STATE_RESIDENCE_LOCAL_ACTIVITY_TERMS
+    strong_geo_hits = text_tokens & _STATE_RESIDENCE_STRONG_GEO_TERMS
+    location_hits = text_tokens & _STATE_RESIDENCE_LOCATION_TERMS
+    technical_noise = _STATE_RESIDENCE_TECHNICAL_NOISE_RE.search(text)
+    if technical_noise and len(strong_geo_hits) < 3 and not local_activity_hits:
+        return AnswerEvidenceSignal(
+            penalty=0.034,
+            reason="inference_state_residence_technical_noise",
+        )
+    if city_alias_hits and local_activity_hits:
+        return AnswerEvidenceSignal(
+            boost=0.036,
+            reason="inference_state_residence_city_state_evidence",
+        )
+    if state_name_hits and local_activity_hits:
+        return AnswerEvidenceSignal(
+            boost=0.032,
+            reason="inference_state_residence_named_state_evidence",
+        )
+    if len(strong_geo_hits) >= 3 and (
+        location_hits or {"map", "trail"} <= text_tokens or {"map", "trails"} <= text_tokens
+    ):
+        return AnswerEvidenceSignal(
+            boost=0.03,
+            reason="inference_state_residence_geo_evidence",
+        )
+    if text_tokens & _STATE_RESIDENCE_GEO_TEXT_TERMS and len(strong_geo_hits) <= 1:
+        return AnswerEvidenceSignal(
+            penalty=0.026,
+            reason="inference_state_residence_topic_only_noise",
+        )
+    return AnswerEvidenceSignal()
+
+
+def _requests_state_residence_inference(query: str) -> bool:
+    query_tokens = _term_set(query)
+    if "state" in query_tokens and query_tokens & _STATE_RESIDENCE_QUERY_TERMS:
+        return True
+    return requests_named_state_residence(query)
+
+
+def _term_set(text: str) -> frozenset[str]:
+    terms: set[str] = set()
+    for term in query_terms(text, min_chars=2, max_terms=40):
+        terms.update(term.variants)
+    for match in _TOKEN_RE.finditer(text):
+        token = match.group(0).casefold().strip("_")
+        if len(token) >= 2:
+            terms.add(token)
+    return frozenset(terms)