headroom-ai 0.2.13__py3-none-any.whl

headroom/relevance/__init__.py

@@ -0,0 +1,124 @@
+"""Relevance scoring module for Headroom SDK.
+
+This module provides a unified interface for computing item relevance against
+query contexts. All scorers implement the RelevanceScorer protocol:
+
+    relevance(item, context) -> RelevanceScore
+
+Available scorers:
+
+1. HybridScorer (DEFAULT - recommended)
+   - Combines BM25 + embeddings for best accuracy
+   - Adaptive alpha: more BM25 for UUIDs, more semantic for natural language
+   - Falls back gracefully to BM25 if sentence-transformers not installed
+   - Install for full support: pip install headroom[relevance]
+
+2. BM25Scorer (zero dependencies)
+   - Fast keyword matching
+   - Good for exact UUIDs, IDs, specific terms
+   - May miss semantic matches ("errors" won't match "failed")
+
+3. EmbeddingScorer (requires sentence-transformers)
+   - Pure semantic similarity
+   - Best for natural language queries
+   - Install: pip install headroom[relevance]
+
+WHY HYBRID IS DEFAULT:
+- Missing important items during compression is catastrophic
+- BM25 alone gives low scores for single-term matches (e.g., "Alice" = 0.07)
+- Semantic matching catches "errors" -> "failed", "issues", etc.
+- 5-10ms latency is acceptable vs. losing critical data
+
+Example usage:
+    from headroom.relevance import HybridScorer, create_scorer
+
+    # Default: Hybrid (recommended)
+    scorer = create_scorer()  # or HybridScorer()
+
+    # Zero-dependency fallback
+    scorer = create_scorer("bm25")
+
+    # Score items
+    items = [
+        '{"id": "123", "name": "Alice"}',
+        '{"id": "456", "name": "Bob"}',
+    ]
+    scores = scorer.score_batch(items, "find user 123")
+    # scores[0].score > scores[1].score
+"""
+
+from typing import Any
+
+from .base import RelevanceScore, RelevanceScorer
+from .bm25 import BM25Scorer
+from .embedding import EmbeddingScorer, embedding_available
+from .hybrid import HybridScorer
+
+__all__ = [
+    # Base types
+    "RelevanceScore",
+    "RelevanceScorer",
+    # Scorers
+    "BM25Scorer",
+    "EmbeddingScorer",
+    "HybridScorer",
+    # Utilities
+    "embedding_available",
+    # Factory function
+    "create_scorer",
+]
+
+
+def create_scorer(
+    tier: str = "hybrid",
+    **kwargs: Any,
+) -> RelevanceScorer:
+    """Factory function to create a relevance scorer.
+
+    Args:
+        tier: Scorer tier to create:
+            - "hybrid": Hybrid BM25 + embedding (DEFAULT, recommended)
+            - "bm25": BM25 keyword scorer (zero deps, fast)
+            - "embedding": Embedding scorer (requires sentence-transformers)
+        **kwargs: Additional arguments passed to scorer constructor.
+
+    Returns:
+        RelevanceScorer instance.
+
+    Raises:
+        ValueError: If tier is unknown.
+        RuntimeError: If tier requires unavailable dependencies.
+
+    Note:
+        HybridScorer gracefully falls back to BM25 if sentence-transformers
+        is not installed, so it's safe to use as the default.
+
+    Example:
+        # Create default hybrid scorer (recommended)
+        scorer = create_scorer()
+
+        # Create BM25 scorer for zero-dependency environments
+        scorer = create_scorer("bm25")
+
+        # Create hybrid scorer with custom alpha
+        scorer = create_scorer("hybrid", alpha=0.6, adaptive=True)
+    """
+    tier = tier.lower()
+
+    if tier == "bm25":
+        return BM25Scorer(**kwargs)
+
+    elif tier == "embedding":
+        if not EmbeddingScorer.is_available():
+            raise RuntimeError(
+                "EmbeddingScorer requires sentence-transformers. "
+                "Install with: pip install headroom[relevance]"
+            )
+        return EmbeddingScorer(**kwargs)
+
+    elif tier == "hybrid":
+        return HybridScorer(**kwargs)
+
+    else:
+        valid_tiers = ["bm25", "embedding", "hybrid"]
+        raise ValueError(f"Unknown scorer tier: {tier}. Valid tiers: {valid_tiers}")

headroom/relevance/base.py

@@ -0,0 +1,106 @@
+"""Base protocol for relevance scoring in Headroom SDK.
+
+This module defines the RelevanceScorer protocol - a unified interface for
+computing item relevance against a query context. All transforms that make
+keep/drop decisions can use this abstraction.
+
+The pattern: relevance(item, context) -> float [0.0, 1.0]
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RelevanceScore:
+    """Relevance score with explainability.
+
+    Attributes:
+        score: Relevance score from 0.0 (irrelevant) to 1.0 (highly relevant).
+        reason: Human-readable explanation of the score.
+        matched_terms: List of terms that contributed to the match (for debugging).
+    """
+
+    score: float
+    reason: str = ""
+    matched_terms: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        """Clamp score to valid range."""
+        self.score = max(0.0, min(1.0, self.score))
+
+
+class RelevanceScorer(ABC):
+    """Abstract base class for relevance scoring.
+
+    All relevance scorers must implement:
+    - score(): Score a single item against context
+    - score_batch(): Score multiple items efficiently
+
+    Example usage:
+        scorer = BM25Scorer()
+        items = ['{"id": "123", "name": "Alice"}', '{"id": "456", "name": "Bob"}']
+        context = "find user 123"
+        scores = scorer.score_batch(items, context)
+        # scores[0].score > scores[1].score (item 0 matches "123")
+    """
+
+    @abstractmethod
+    def score(self, item: str, context: str) -> RelevanceScore:
+        """Score a single item's relevance to the context.
+
+        Args:
+            item: String representation of the item (typically JSON).
+            context: Query context (user message, tool call args, etc.).
+
+        Returns:
+            RelevanceScore with score [0.0, 1.0] and explanation.
+        """
+        pass
+
+    @abstractmethod
+    def score_batch(self, items: list[str], context: str) -> list[RelevanceScore]:
+        """Score multiple items efficiently.
+
+        Default implementation calls score() for each item.
+        Subclasses should override for batch-optimized implementations.
+
+        Args:
+            items: List of string representations of items.
+            context: Query context to score against.
+
+        Returns:
+            List of RelevanceScore objects, one per item.
+        """
+        pass
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """Check if this scorer is available (dependencies installed).
+
+        Override in subclasses that have optional dependencies.
+
+        Returns:
+            True if the scorer can be instantiated.
+        """
+        return True
+
+
+def default_batch_score(
+    scorer: RelevanceScorer, items: list[str], context: str
+) -> list[RelevanceScore]:
+    """Default batch implementation that calls score() per item.
+
+    Use this as a fallback for scorers that don't have optimized batching.
+
+    Args:
+        scorer: The scorer instance.
+        items: List of items to score.
+        context: Query context.
+
+    Returns:
+        List of scores.
+    """
+    return [scorer.score(item, context) for item in items]

headroom/relevance/bm25.py

@@ -0,0 +1,255 @@
+"""BM25 relevance scorer for Headroom SDK.
+
+This module provides a BM25-based relevance scorer with ZERO external dependencies.
+BM25 (Best Match 25) is a bag-of-words retrieval function that ranks documents
+based on query term frequency.
+
+Key features:
+- Zero dependencies (pure Python)
+- Fast execution (~0ms per item)
+- Excellent for exact matches (UUIDs, IDs, specific terms)
+- Returns matched terms for explainability
+
+Limitations:
+- No semantic understanding ("errors" won't match "failed")
+- Sensitive to tokenization
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+
+from .base import RelevanceScore, RelevanceScorer
+
+
+class BM25Scorer(RelevanceScorer):
+    """BM25 keyword relevance scorer.
+
+    Zero dependencies, instant execution. Excellent for exact ID/UUID matching.
+
+    BM25 formula:
+        score(D, Q) = sum over q in Q of:
+            IDF(q) * (f(q,D) * (k1 + 1)) / (f(q,D) + k1 * (1 - b + b * |D|/avgdl))
+
+    Where:
+        - f(q,D) = frequency of term q in document D
+        - |D| = length of document D
+        - avgdl = average document length
+        - k1, b = tuning parameters
+
+    Example:
+        scorer = BM25Scorer()
+        score = scorer.score(
+            '{"id": "550e8400-e29b-41d4-a716-446655440000", "name": "Alice"}',
+            "find record 550e8400-e29b-41d4-a716-446655440000"
+        )
+        # score.score > 0.5 (UUID matches exactly)
+    """
+
+    # Tokenization pattern: alphanumeric sequences, UUIDs, numeric IDs
+    _TOKEN_PATTERN = re.compile(
+        r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"  # UUIDs
+        r"|\b\d{4,}\b"  # Numeric IDs (4+ digits)
+        r"|[a-zA-Z0-9_]+"  # Alphanumeric tokens
+    )
+
+    def __init__(
+        self,
+        k1: float = 1.5,
+        b: float = 0.75,
+        normalize_score: bool = True,
+        max_score: float = 10.0,
+    ):
+        """Initialize BM25 scorer.
+
+        Args:
+            k1: Term frequency saturation parameter (default 1.5).
+                Higher values increase term frequency impact.
+            b: Length normalization parameter (default 0.75).
+                0 = no length normalization, 1 = full normalization.
+            normalize_score: If True, normalize score to [0, 1].
+            max_score: Maximum raw score for normalization.
+        """
+        self.k1 = k1
+        self.b = b
+        self.normalize_score = normalize_score
+        self.max_score = max_score
+
+    def _tokenize(self, text: str) -> list[str]:
+        """Tokenize text into terms.
+
+        Preserves:
+        - UUIDs as single tokens
+        - Numeric IDs
+        - Alphanumeric words
+
+        Args:
+            text: Text to tokenize.
+
+        Returns:
+            List of lowercase tokens.
+        """
+        if not text:
+            return []
+
+        tokens = self._TOKEN_PATTERN.findall(text.lower())
+        return tokens
+
+    def _compute_idf(self, term: str, doc_count: int, doc_freq: int) -> float:
+        """Compute inverse document frequency.
+
+        Uses the standard BM25 IDF formula:
+            IDF = log((N - n + 0.5) / (n + 0.5) + 1)
+
+        Where N = total docs, n = docs containing term.
+
+        For single-document scoring, we use a simplified version.
+        """
+        if doc_freq == 0:
+            return 0.0
+
+        # Simplified IDF for single-document case
+        # Term present = higher IDF, term absent = 0
+        return math.log(2.0)  # Constant since we have single document
+
+    def _bm25_score(
+        self,
+        doc_tokens: list[str],
+        query_tokens: list[str],
+        avg_doc_len: float | None = None,
+    ) -> tuple[float, list[str]]:
+        """Compute BM25 score between document and query.
+
+        Args:
+            doc_tokens: Tokenized document.
+            query_tokens: Tokenized query.
+            avg_doc_len: Average document length (optional).
+
+        Returns:
+            Tuple of (score, matched_terms).
+        """
+        if not doc_tokens or not query_tokens:
+            return 0.0, []
+
+        doc_len = len(doc_tokens)
+        avgdl = avg_doc_len or doc_len
+
+        doc_freq = Counter(doc_tokens)
+        query_freq = Counter(query_tokens)
+
+        score = 0.0
+        matched_terms: list[str] = []
+
+        for term, qf in query_freq.items():
+            if term not in doc_freq:
+                continue
+
+            f = doc_freq[term]
+            matched_terms.append(term)
+
+            # BM25 term score
+            idf = math.log(2.0)  # Simplified for single doc
+            numerator = f * (self.k1 + 1)
+            denominator = f + self.k1 * (1 - self.b + self.b * doc_len / avgdl)
+
+            term_score = idf * numerator / denominator
+            score += term_score * qf  # Weight by query frequency
+
+        return score, matched_terms
+
+    def score(self, item: str, context: str) -> RelevanceScore:
+        """Score item relevance to context using BM25.
+
+        Args:
+            item: Item text (typically JSON string).
+            context: Query context.
+
+        Returns:
+            RelevanceScore with BM25-based score.
+        """
+        item_tokens = self._tokenize(item)
+        context_tokens = self._tokenize(context)
+
+        raw_score, matched = self._bm25_score(item_tokens, context_tokens)
+
+        # Normalize to [0, 1]
+        if self.normalize_score:
+            normalized = min(1.0, raw_score / self.max_score)
+        else:
+            normalized = raw_score
+
+        # Bonus for exact long-token matches (UUIDs, long IDs)
+        # These are high-value matches that should be preserved
+        long_matches = [t for t in matched if len(t) >= 8]
+        if long_matches:
+            normalized = min(1.0, normalized + 0.3)
+
+        match_count = len(matched)
+        if match_count == 0:
+            reason = "BM25: no term matches"
+        elif match_count == 1:
+            reason = f"BM25: matched '{matched[0]}'"
+        else:
+            reason = f"BM25: matched {match_count} terms ({', '.join(matched[:3])}{'...' if match_count > 3 else ''})"
+
+        return RelevanceScore(
+            score=normalized,
+            reason=reason,
+            matched_terms=matched[:10],  # Limit for readability
+        )
+
+    def score_batch(self, items: list[str], context: str) -> list[RelevanceScore]:
+        """Score multiple items.
+
+        BM25 is fast enough that sequential scoring is efficient.
+        Could be optimized with vectorization if needed.
+
+        Args:
+            items: List of items to score.
+            context: Query context.
+
+        Returns:
+            List of RelevanceScore objects.
+        """
+        # Pre-tokenize context once
+        context_tokens = self._tokenize(context)
+
+        if not context_tokens:
+            return [RelevanceScore(score=0.0, reason="BM25: empty context") for _ in items]
+
+        # Compute average document length for normalization
+        all_tokens = [self._tokenize(item) for item in items]
+        avg_len = sum(len(t) for t in all_tokens) / max(len(items), 1)
+
+        results = []
+        for item_tokens in all_tokens:
+            raw_score, matched = self._bm25_score(item_tokens, context_tokens, avg_doc_len=avg_len)
+
+            # Normalize
+            if self.normalize_score:
+                normalized = min(1.0, raw_score / self.max_score)
+            else:
+                normalized = raw_score
+
+            # Bonus for long matches
+            long_matches = [t for t in matched if len(t) >= 8]
+            if long_matches:
+                normalized = min(1.0, normalized + 0.3)
+
+            match_count = len(matched)
+            if match_count == 0:
+                reason = "BM25: no matches"
+            else:
+                reason = f"BM25: {match_count} terms"
+
+            results.append(
+                RelevanceScore(
+                    score=normalized,
+                    reason=reason,
+                    matched_terms=matched[:5],
+                )
+            )
+
+        return results