infinity-context 0.1.0__py3-none-any.whl

infinity_context_core/application/context_anchors.py

@@ -0,0 +1,393 @@
+"""Prompt-safe context projection for canonical memory anchors."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from infinity_context_core.application.context_anchor_identity import anchor_identity_profile
+from infinity_context_core.application.context_query_intent import QueryAnchorMatch
+from infinity_context_core.application.context_relevance import (
+    QueryRelevance,
+    query_relevance_score_signals,
+)
+from infinity_context_core.application.dto import ContextItem
+from infinity_context_core.application.safe_payload import safe_metadata_text
+from infinity_context_core.domain.entities import MemoryAnchor
+
+_IDENTITY_METADATA_KEYS = (
+    "anchor_family",
+    "canonical_key",
+    "person_canonical_key",
+    "project_canonical_key",
+    "organization_canonical_key",
+    "event_type",
+    "event_type_canonical",
+    "event_participant_label",
+    "event_participant_relation",
+    "event_participant_canonical_key",
+    "event_project_label",
+    "event_project_relation",
+    "event_project_canonical_key",
+    "project_canonical_key",
+    "event_temporal_phrase",
+    "event_temporal_hint_code",
+    "event_temporal_quantity",
+    "event_temporal_unit",
+    "identity_key",
+    "identity_scope",
+)
+_IDENTITY_LIST_METADATA_KEYS = ("event_identity_terms", "alias_identity_terms")
+
+
+def anchor_retrieval_text(anchor: MemoryAnchor) -> str:
+    return " ".join(
+        part
+        for part in (
+            anchor.kind.value,
+            anchor.label,
+            " ".join(anchor.aliases),
+            anchor.description or "",
+            anchor_identity_retrieval_text(anchor),
+        )
+        if part
+    )
+
+
+def anchor_identity_retrieval_text(anchor: MemoryAnchor) -> str:
+    terms: list[str] = []
+    for key in _IDENTITY_METADATA_KEYS:
+        terms.extend(_metadata_search_terms(anchor.metadata.get(key)))
+    for key in _IDENTITY_LIST_METADATA_KEYS:
+        value = anchor.metadata.get(key)
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                terms.extend(_metadata_search_terms(item))
+    return " ".join(_dedupe_preserve_order(tuple(terms)))
+
+
+def anchor_context_item(
+    anchor: MemoryAnchor,
+    *,
+    relevance: QueryRelevance,
+    identity_relevance: QueryRelevance,
+    now: datetime | None,
+    query_anchor_match: QueryAnchorMatch | None = None,
+) -> ContextItem:
+    score = _anchor_score(
+        anchor,
+        relevance=relevance,
+        identity_relevance=identity_relevance,
+        now=now,
+        query_anchor_match=query_anchor_match,
+    )
+    metadata = _anchor_identity_metadata(anchor)
+    identity_profile = anchor_identity_profile(anchor, metadata=metadata)
+    ranking_reason = (
+        "canonical semantic anchor matched query via structured identity metadata"
+        if identity_relevance.unique_term_hits > 0 or query_anchor_match is not None
+        else "canonical semantic anchor matched query"
+    )
+    match_diagnostics = (
+        query_anchor_match.diagnostics() if query_anchor_match is not None else {}
+    )
+    return ContextItem(
+        item_id=str(anchor.id),
+        item_type="anchor",
+        text=_anchor_render_text(anchor, metadata=metadata),
+        score=score,
+        source_refs=anchor.evidence_refs,
+        diagnostics={
+            "memory_scope_id": str(anchor.memory_scope_id),
+            "retrieval_source": "canonical_anchors",
+            "retrieval_sources": ["canonical_anchors"],
+            "ranking_reason": ranking_reason,
+            "score_signals": {
+                "base_score": 0.72,
+                "final_score": score,
+                "retrieval_channel": "canonical_anchors",
+                "anchor_kind": anchor.kind.value,
+                "confidence": anchor.confidence.value,
+                "anchor_identity_term_count": identity_profile["identity_term_count"],
+                "anchor_alias_identity_term_count": identity_profile[
+                    "alias_identity_term_count"
+                ],
+                **query_relevance_score_signals(relevance),
+                "identity_unique_term_hits": identity_relevance.unique_term_hits,
+                "identity_hit_ratio": identity_relevance.hit_ratio,
+                "identity_relevance_boost": identity_relevance.score_boost,
+                "query_anchor_intent_boost": (
+                    query_anchor_match.score_boost if query_anchor_match is not None else 0.0
+                ),
+            },
+            "provenance": {
+                "retrieval_sources": ["canonical_anchors"],
+                "source_ref_count": len(anchor.evidence_refs),
+                "anchor_kind": anchor.kind.value,
+                "anchor_status": anchor.status.value,
+                "normalized_key": anchor.normalized_key,
+                "observed_at": anchor.observed_at.isoformat(),
+                "valid_from": anchor.valid_from.isoformat() if anchor.valid_from else None,
+                "valid_to": anchor.valid_to.isoformat() if anchor.valid_to else None,
+                "anchor_identity_profile": identity_profile,
+                "identity_metadata": metadata,
+                **match_diagnostics,
+            },
+            "anchor_kind": anchor.kind.value,
+            "normalized_key": anchor.normalized_key,
+            "confidence": anchor.confidence.value,
+            "observed_at": anchor.observed_at.isoformat(),
+            "updated_at": anchor.updated_at.isoformat(),
+            "anchor_identity_profile": identity_profile,
+            "identity_metadata": metadata,
+            **match_diagnostics,
+            **metadata,
+        },
+    )
+
+
+def related_anchor_context_item(
+    anchor: MemoryAnchor,
+    *,
+    source_anchor: MemoryAnchor,
+    relation_type: str,
+    relation_key: str,
+    parent_score: float,
+    now: datetime | None,
+) -> ContextItem:
+    metadata = _anchor_identity_metadata(anchor)
+    identity_profile = anchor_identity_profile(anchor, metadata=metadata)
+    score = _related_anchor_score(anchor, parent_score=parent_score, now=now)
+    safe_relation_type = _metadata_text(relation_type, limit=80) or "related_anchor"
+    safe_relation_key = _metadata_text(relation_key, limit=160) or anchor.normalized_key
+    return ContextItem(
+        item_id=str(anchor.id),
+        item_type="anchor",
+        text=_anchor_render_text(anchor, metadata=metadata),
+        score=score,
+        source_refs=anchor.evidence_refs,
+        diagnostics={
+            "memory_scope_id": str(anchor.memory_scope_id),
+            "retrieval_source": "canonical_anchor_relations",
+            "retrieval_sources": ["canonical_anchor_relations"],
+            "ranking_reason": (
+                "canonical anchor related to selected event anchor via structured identity metadata"
+            ),
+            "score_signals": {
+                "base_score": 0.62,
+                "final_score": score,
+                "retrieval_channel": "canonical_anchor_relations",
+                "parent_anchor_score": round(parent_score, 4),
+                "anchor_kind": anchor.kind.value,
+                "confidence": anchor.confidence.value,
+                "anchor_identity_term_count": identity_profile["identity_term_count"],
+            },
+            "provenance": {
+                "retrieval_sources": ["canonical_anchor_relations"],
+                "source_ref_count": len(anchor.evidence_refs),
+                "anchor_kind": anchor.kind.value,
+                "anchor_status": anchor.status.value,
+                "normalized_key": anchor.normalized_key,
+                "observed_at": anchor.observed_at.isoformat(),
+                "valid_from": anchor.valid_from.isoformat() if anchor.valid_from else None,
+                "valid_to": anchor.valid_to.isoformat() if anchor.valid_to else None,
+                "anchor_identity_profile": identity_profile,
+                "identity_metadata": metadata,
+                "relation_source_anchor_id": str(source_anchor.id),
+                "relation_source_anchor_kind": source_anchor.kind.value,
+                "relation_source_anchor_key": source_anchor.normalized_key,
+                "relation_type": safe_relation_type,
+                "relation_key": safe_relation_key,
+            },
+            "anchor_kind": anchor.kind.value,
+            "normalized_key": anchor.normalized_key,
+            "confidence": anchor.confidence.value,
+            "observed_at": anchor.observed_at.isoformat(),
+            "updated_at": anchor.updated_at.isoformat(),
+            "anchor_identity_profile": identity_profile,
+            "identity_metadata": metadata,
+            "related_anchor_source_id": str(source_anchor.id),
+            "related_anchor_source_kind": source_anchor.kind.value,
+            "related_anchor_relation_type": safe_relation_type,
+            "related_anchor_relation_key": safe_relation_key,
+            **metadata,
+        },
+    )
+
+
+def _anchor_render_text(anchor: MemoryAnchor, *, metadata: dict[str, object]) -> str:
+    alias_text = ", ".join(alias for alias in anchor.aliases if alias != anchor.label)
+    parts = [f"{anchor.kind.value}: {anchor.label}"]
+    if alias_text:
+        parts.append(f"aliases: {alias_text}")
+    if anchor.description:
+        parts.append(f"description: {anchor.description}")
+    event_details = _event_render_parts(metadata)
+    if event_details:
+        parts.append("identity: " + "; ".join(event_details))
+    elif identity_terms := _identity_terms(metadata):
+        parts.append("identity: " + ", ".join(identity_terms))
+    return ". ".join(parts)
+
+
+def _event_render_parts(metadata: dict[str, object]) -> tuple[str, ...]:
+    parts: list[str] = []
+    if event_type := _metadata_text(
+        metadata.get("event_type_canonical") or metadata.get("event_type"),
+        limit=80,
+    ):
+        parts.append(f"event_type: {event_type}")
+    if participant := _metadata_text(metadata.get("event_participant_label"), limit=120):
+        relation = _metadata_text(metadata.get("event_participant_relation"), limit=80) or "with"
+        parts.append(f"{relation}: {participant}")
+    if project := _metadata_text(metadata.get("event_project_label"), limit=120):
+        relation = _metadata_text(metadata.get("event_project_relation"), limit=80) or "about"
+        parts.append(f"{relation}: {project}")
+    if temporal := _metadata_text(metadata.get("event_temporal_phrase"), limit=160):
+        parts.append(f"time: {temporal}")
+    return tuple(parts)
+
+
+def _identity_terms(metadata: dict[str, object]) -> tuple[str, ...]:
+    value = metadata.get("event_identity_terms")
+    if isinstance(value, list):
+        return tuple(
+            text
+            for item in value[:6]
+            if (text := _metadata_text(item, limit=120))
+        )
+    terms: list[str] = []
+    for key in (
+        "person_canonical_key",
+        "project_canonical_key",
+        "organization_canonical_key",
+        "canonical_key",
+    ):
+        if text := _metadata_text(metadata.get(key), limit=120):
+            terms.append(text)
+            break
+    value = metadata.get("alias_identity_terms")
+    if isinstance(value, list):
+        terms.extend(
+            text
+            for item in value[:6]
+            if (text := _metadata_text(item, limit=120))
+        )
+    return tuple(_dedupe_preserve_order(tuple(terms)))
+
+
+def _anchor_score(
+    anchor: MemoryAnchor,
+    *,
+    relevance: QueryRelevance,
+    identity_relevance: QueryRelevance,
+    now: datetime | None,
+    query_anchor_match: QueryAnchorMatch | None,
+) -> float:
+    confidence_boost = _level_boost(anchor.confidence.value, low=0.01, medium=0.025, high=0.045)
+    freshness_boost = _freshness_boost(anchor.updated_at, now=now)
+    identity_boost = min(0.035, identity_relevance.score_boost * 0.5)
+    query_intent_boost = (
+        min(0.09, query_anchor_match.score_boost) if query_anchor_match is not None else 0.0
+    )
+    return min(
+        0.94,
+        round(
+            0.72
+            + relevance.score_boost
+            + identity_boost
+            + query_intent_boost
+            + confidence_boost
+            + freshness_boost,
+            4,
+        ),
+    )
+
+
+def _related_anchor_score(
+    anchor: MemoryAnchor,
+    *,
+    parent_score: float,
+    now: datetime | None,
+) -> float:
+    confidence_boost = _level_boost(anchor.confidence.value, low=0.005, medium=0.015, high=0.025)
+    freshness_boost = _freshness_boost(anchor.updated_at, now=now) * 0.5
+    return min(
+        0.88,
+        max(
+            0.6,
+            round(parent_score - 0.065 + confidence_boost + freshness_boost, 4),
+        ),
+    )
+
+
+def _anchor_identity_metadata(anchor: MemoryAnchor) -> dict[str, object]:
+    metadata: dict[str, object] = {}
+    for key in _IDENTITY_METADATA_KEYS:
+        if value := _metadata_text(anchor.metadata.get(key), limit=160):
+            metadata[key] = value
+    for key in _IDENTITY_LIST_METADATA_KEYS:
+        value = anchor.metadata.get(key)
+        if isinstance(value, (list, tuple)):
+            items = [
+                text
+                for item in value[:8]
+                if (text := _metadata_text(item, limit=120))
+            ]
+            if items:
+                metadata[key] = items
+    return metadata
+
+
+def _metadata_search_terms(value: object) -> tuple[str, ...]:
+    text = _metadata_text(value, limit=160)
+    if not text:
+        return ()
+    normalized = text.replace("_", " ").replace("-", " ")
+    colon_parts = tuple(part for part in normalized.replace(":", " ").split() if len(part) >= 2)
+    return _dedupe_preserve_order((text, normalized, *colon_parts))
+
+
+def _metadata_text(value: object, *, limit: int) -> str:
+    if value is None:
+        return ""
+    return safe_metadata_text(str(value), limit=limit).strip()
+
+
+def _dedupe_preserve_order(values: tuple[str, ...]) -> tuple[str, ...]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        normalized = " ".join(value.strip().split())
+        key = normalized.casefold()
+        if not normalized or key in seen:
+            continue
+        seen.add(key)
+        result.append(normalized)
+    return tuple(result)
+
+
+def _level_boost(value: str, *, low: float, medium: float, high: float) -> float:
+    if value == "high":
+        return high
+    if value == "low":
+        return low
+    return medium
+
+
+def _freshness_boost(updated_at: datetime, *, now: datetime | None) -> float:
+    if now is None:
+        return 0.0
+    comparable_updated_at = updated_at
+    comparable_now = now
+    if comparable_updated_at.tzinfo is None and comparable_now.tzinfo is not None:
+        comparable_updated_at = comparable_updated_at.replace(tzinfo=comparable_now.tzinfo)
+    elif comparable_updated_at.tzinfo is not None and comparable_now.tzinfo is None:
+        comparable_now = comparable_now.replace(tzinfo=comparable_updated_at.tzinfo)
+    age_days = max(0.0, (comparable_now - comparable_updated_at).total_seconds() / 86400)
+    if age_days <= 7:
+        return 0.02
+    if age_days <= 30:
+        return 0.012
+    if age_days <= 180:
+        return 0.006
+    return 0.0

infinity_context_core/application/context_answer_evidence_types.py

@@ -0,0 +1,14 @@
+"""Shared answer-evidence signal contracts for deterministic reranking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AnswerEvidenceSignal:
+    """Bounded score adjustment for an item's answer-evidence fit."""
+
+    boost: float = 0.0
+    penalty: float = 0.0
+    reason: str = ""

infinity_context_core/application/context_answer_unit_shapes.py

@@ -0,0 +1,207 @@
+"""Typed answer-unit shape helpers for retrieval evidence ranking."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from functools import cache
+
+_NUMBER_VALUE = (
+    r"\d+(?:\.\d+)?|"
+    r"one|two|three|four|five|six|seven|eight|nine|ten|"
+    r"eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|"
+    r"eighteen|nineteen|twenty|thirty|forty|fifty|sixty|seventy|"
+    r"eighty|ninety|hundred|a|an"
+)
+_NUMBER_VALUE_RE = rf"(?:{_NUMBER_VALUE})"
+
+_AGE_QUERY_RE = re.compile(
+    r"\bhow\s+old\b|"
+    r"\bwhat\b.{0,48}\bage\b|"
+    r"\bage\b.{0,48}\b(?:is|was|of)\b",
+    re.IGNORECASE | re.DOTALL,
+)
+_DURATION_QUERY_RE = re.compile(
+    r"\bhow\s+long\b|\bduration\b|\bfor\s+how\s+many\b|\bhow\s+many\b",
+    re.IGNORECASE,
+)
+_DISTANCE_QUERY_RE = re.compile(
+    r"\bhow\s+far\b|\bdistance\b|\bhow\s+many\b",
+    re.IGNORECASE,
+)
+_QUANTITY_QUERY_RE = re.compile(
+    r"\bhow\s+(?:many|much)\b|\bwhat\b.{0,64}\b"
+    r"(?:amount|quantity|total|cost|price|value|fee|deposit|budget|"
+    r"salary|rent|payment)\b",
+    re.IGNORECASE | re.DOTALL,
+)
+_MONEY_VALUE_QUERY_RE = re.compile(
+    r"\bhow\s+much\b.{0,80}\b(?:cost|costs|paid|pay|spent|spend|"
+    r"charge|charged|fee|deposit|rent|salary|budget|payment)\b|"
+    r"\bwhat\b.{0,80}\b(?:amount|cost|price|value|fee|deposit|budget|"
+    r"salary|rent|payment)\b|"
+    r"\b(?:amount|cost|price|value|fee|deposit|budget|salary|rent|payment)\b"
+    r".{0,40}\b(?:dollar|dollars|usd|\$)\b",
+    re.IGNORECASE | re.DOTALL,
+)
+
+_AGE_UNITS = (
+    ("year", ("year", "years", "yr", "yrs")),
+    ("month", ("month", "months", "mo", "mos")),
+)
+_DURATION_UNITS = (
+    ("year", ("year", "years", "yr", "yrs")),
+    ("month", ("month", "months", "mo", "mos")),
+    ("week", ("week", "weeks", "wk", "wks")),
+    ("day", ("day", "days")),
+    ("hour", ("hour", "hours", "hr", "hrs")),
+    ("minute", ("minute", "minutes", "min", "mins")),
+)
+_DISTANCE_UNITS = (
+    ("mile", ("mile", "miles", "mi")),
+    ("kilometer", ("kilometer", "kilometers", "kilometre", "kilometres", "km")),
+    ("meter", ("meter", "meters", "metre", "metres", "m")),
+    ("foot", ("foot", "feet", "ft")),
+)
+_QUANTITY_UNITS = (
+    ("cup", ("cup", "cups")),
+    ("ounce", ("ounce", "ounces", "oz")),
+    ("pound", ("pound", "pounds", "lb", "lbs")),
+    ("gram", ("gram", "grams", "g")),
+    ("kilogram", ("kilogram", "kilograms", "kg")),
+    ("liter", ("liter", "liters", "litre", "litres", "l")),
+    ("milliliter", ("milliliter", "milliliters", "millilitre", "millilitres", "ml")),
+    ("dollar", ("dollar", "dollars", "usd")),
+)
+
+
+def requested_answer_unit_shapes(query: str) -> tuple[str, ...]:
+    """Return precise answer-unit shapes requested by the query."""
+
+    shapes: list[str] = []
+    if _AGE_QUERY_RE.search(query):
+        shapes.append(f"age_{_first_unit_match(query, _AGE_UNITS) or 'year'}")
+    elif _DURATION_QUERY_RE.search(query):
+        shapes.extend(
+            f"duration_{unit}" for unit in _unit_matches(query, _DURATION_UNITS)
+        )
+    if _DISTANCE_QUERY_RE.search(query):
+        shapes.extend(f"distance_{unit}" for unit in _unit_matches(query, _DISTANCE_UNITS))
+    if _QUANTITY_QUERY_RE.search(query):
+        quantity_units = _unit_matches(query, _QUANTITY_UNITS)
+        if not quantity_units and _MONEY_VALUE_QUERY_RE.search(query):
+            quantity_units = ("dollar",)
+        shapes.extend(f"quantity_{unit}" for unit in quantity_units)
+    return _bounded_unique(shapes)
+
+
+def covered_answer_unit_shapes(text: str) -> tuple[str, ...]:
+    """Return precise answer-unit shapes stated by evidence text."""
+
+    shapes: list[str] = []
+    for unit, aliases in _AGE_UNITS:
+        if _age_evidence_re(aliases, allow_unitless=unit == "year").search(text):
+            shapes.append(f"age_{unit}")
+    for unit, aliases in _DURATION_UNITS:
+        if _duration_evidence_re(aliases).search(text):
+            shapes.append(f"duration_{unit}")
+    for unit, aliases in _DISTANCE_UNITS:
+        if _numbered_unit_re(aliases).search(text):
+            shapes.append(f"distance_{unit}")
+    for unit, aliases in _QUANTITY_UNITS:
+        if _quantity_evidence_re(unit=unit, aliases=aliases).search(text):
+            shapes.append(f"quantity_{unit}")
+    return _bounded_unique(shapes)
+
+
+def is_typed_answer_unit_shape(shape: str) -> bool:
+    return shape.startswith(("age_", "duration_", "distance_", "quantity_"))
+
+
+def _first_unit_match(
+    text: str,
+    units: tuple[tuple[str, tuple[str, ...]], ...],
+) -> str:
+    return next(iter(_unit_matches(text, units)), "")
+
+
+def _unit_matches(
+    text: str,
+    units: tuple[tuple[str, tuple[str, ...]], ...],
+) -> tuple[str, ...]:
+    return _bounded_unique(
+        unit for unit, aliases in units if _unit_alias_re(aliases).search(text)
+    )
+
+
+@cache
+def _age_evidence_re(
+    aliases: tuple[str, ...],
+    *,
+    allow_unitless: bool,
+) -> re.Pattern[str]:
+    unit = _unit_alias_pattern(aliases)
+    unitless = (
+        rf"|\bage\s*(?:is|was|:)?\s*{_NUMBER_VALUE_RE}\b"
+        rf"|\bturn(?:ed|s|ing)?\s+{_NUMBER_VALUE_RE}\b"
+        if allow_unitless
+        else ""
+    )
+    return re.compile(
+        rf"\b{_NUMBER_VALUE_RE}\s+{unit}\s+old\b|"
+        rf"\bage\s*(?:is|was|:)?\s*{_NUMBER_VALUE_RE}\s+{unit}\b"
+        rf"{unitless}",
+        re.IGNORECASE,
+    )
+
+
+@cache
+def _duration_evidence_re(aliases: tuple[str, ...]) -> re.Pattern[str]:
+    unit = _unit_alias_pattern(aliases)
+    return re.compile(
+        rf"\b(?:for|over|about|around|nearly|almost|approximately|approx\.?|"
+        rf"lasted|lasting|duration(?:\s+of)?|spent|practiced|worked|known|"
+        rf"married|dated|lived)\s+{_NUMBER_VALUE_RE}\s+{unit}\b|"
+        rf"\b{_NUMBER_VALUE_RE}\s+{unit}\s+"
+        rf"(?:long|duration|period|stretch|of|in|after|before|later|ago)\b",
+        re.IGNORECASE,
+    )
+
+
+@cache
+def _quantity_evidence_re(*, unit: str, aliases: tuple[str, ...]) -> re.Pattern[str]:
+    unit_pattern = _unit_alias_pattern(aliases)
+    currency_value = r"\$\s*\d+(?:\.\d+)?\b|" if unit == "dollar" else ""
+    return re.compile(
+        rf"{currency_value}"
+        rf"\b{_NUMBER_VALUE_RE}\s+{unit_pattern}\b",
+        re.IGNORECASE,
+    )
+
+
+@cache
+def _numbered_unit_re(aliases: tuple[str, ...]) -> re.Pattern[str]:
+    return re.compile(
+        rf"\b{_NUMBER_VALUE_RE}\s+{_unit_alias_pattern(aliases)}\b",
+        re.IGNORECASE,
+    )
+
+
+@cache
+def _unit_alias_re(aliases: tuple[str, ...]) -> re.Pattern[str]:
+    return re.compile(rf"\b{_unit_alias_pattern(aliases)}\b", re.IGNORECASE)
+
+
+def _unit_alias_pattern(aliases: tuple[str, ...]) -> str:
+    return r"(?:" + "|".join(re.escape(alias) for alias in aliases) + r")"
+
+
+def _bounded_unique(values: Iterable[str]) -> tuple[str, ...]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        result.append(value)
+    return tuple(result)