tagsearch 1.0.0__tar.gz

tagsearch-1.0.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: tagsearch
+Version: 1.0.0
+Summary: In-memory tag search engine for e-commerce (DAWG + BM25 + hybrid ranking)
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

tagsearch-1.0.0/README.md

@@ -0,0 +1,64 @@
+# tagsearch — Python Engine
+
+In-memory tag search engine for e-commerce. DAWG + BM25 + 5-dimension hybrid ranking.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from tagsearch import SearchEngine, ProductMeta, ProductType, SearchPreferences
+
+engine = SearchEngine(cache_size=200)
+engine.load_catalog("../shared-assets/catalog.json")
+
+# Recherche simple
+results, status = engine.search("gaming")
+
+# Recherche avec préférences
+prefs = SearchPreferences(preferred_type=ProductType.DIGITAL, max_price=50.0)
+results, status = engine.search("cuisine", prefs=prefs, fuzzy=True, max_dist=1)
+```
+
+## API
+
+### `SearchEngine.search(query, prefs, fuzzy, max_dist, top_k)`
+
+| Paramètre | Type | Défaut | Description |
+|-----------|------|--------|-------------|
+| `query`   | `str` | — | Requête utilisateur |
+| `prefs`   | `SearchPreferences` | `None` | Préférences de re-ranking |
+| `fuzzy`   | `bool` | `True` | Active la recherche floue (Levenshtein) |
+| `max_dist`| `int` | `1` | Distance de Levenshtein maximale |
+| `top_k`   | `int` | `10` | Nombre de résultats retournés |
+
+Retourne `(list[dict], status)` où `status` ∈ `{"CALCULÉ", "CACHÉ", "MISS"}`.
+
+### Score final (formule canonique)
+
+```
+score = bm25_norm × quality_mult × type_factor × niche_boost × proximity × price_factor
+```
+
+- `bm25_norm` = `min(bm25_raw / 10.0, 1.0)`, plancher à `0.05`
+- `quality_mult` = `(bayesian_rating / 5.0) ** 1.5`
+- `bayesian_rating` = `(count × rating + 3.5 × 10) / (count + 10)`
+
+## Tests
+
+```bash
+pytest --cov=tagsearch
+```
+
+## Benchmark attendu
+
+| Opération | Complexité | Temps typique (10k tags) |
+|-----------|-----------|--------------------------|
+| Autocomplete | O(L) | < 0.1 ms |
+| Fuzzy search (max_dist=1) | O(L × 5%) | < 1 ms |
+| Scoring 100 candidats | O(n) | < 0.5 ms |
+| Cache HIT | O(1) | < 0.01 ms |

tagsearch-1.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tagsearch"
+version = "1.0.0"
+description = "In-memory tag search engine for e-commerce (DAWG + BM25 + hybrid ranking)"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tagsearch*"]

tagsearch-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tagsearch-1.0.0/tagsearch/__init__.py

@@ -0,0 +1,12 @@
+"""tagsearch — In-memory tag search engine for e-commerce."""
+from .engine import SearchEngine
+from .models import ProductMeta, ProductType, SearchPreferences
+from .scoring import calculate_final_score
+
+__all__ = [
+    "SearchEngine",
+    "ProductMeta",
+    "ProductType",
+    "SearchPreferences",
+    "calculate_final_score",
+]

tagsearch-1.0.0/tagsearch/engine.py

@@ -0,0 +1,242 @@
+"""
+tagsearch.engine
+================
+SearchEngine : point d'entrée public de la bibliothèque.
+Orchestre DAWG, BM25Index, CompressedPostingsList, LRUCache et calculate_final_score.
+"""
+
+from __future__ import annotations
+import json
+import logging
+import sys
+from pathlib import Path
+
+from .models import ProductMeta, ProductType, SearchPreferences
+from .scoring import BM25Index, calculate_final_score
+from .structures import DAWG, CompressedPostingsList, LRUCache
+
+logger = logging.getLogger(__name__)
+
+
+class SearchEngine:
+    """
+    Moteur de recherche in-memory pour tags e-commerce.
+
+    Architecture :
+        DAWG                  → index des tags (autocomplete + fuzzy Levenshtein)
+        CompressedPostingsList → inverted index compressé (delta + VarInt)
+        BM25Index             → scoring textuel
+        calculate_final_score → re-ranking 5 dimensions
+        LRUCache              → cache des résultats de recherche
+
+    Example:
+        >>> engine = SearchEngine()
+        >>> engine.load_catalog("shared-assets/catalog.json")
+        >>> results, status = engine.search("gaming", fuzzy=True)
+
+    Args:
+        cache_size: Capacité du cache LRU (nombre de requêtes mémorisées).
+    """
+
+    def __init__(self, cache_size: int = 200) -> None:
+        self._all_tags: list[str] = []
+        self.dawg: DAWG = DAWG()
+        self.inverted_index: dict[str, CompressedPostingsList] = {}
+        self.catalog: dict[int, ProductMeta] = {}
+        self.bm25: BM25Index = BM25Index()
+        self.cache: LRUCache = LRUCache(capacity=cache_size)
+        logger.info("SearchEngine initialisé (cache_size=%d)", cache_size)
+
+    # ── Chargement ──────────────────────────────────────────────────────────
+
+    def load_catalog(self, path: str | Path) -> None:
+        """
+        Charge un catalogue depuis un fichier JSON (format shared-assets/catalog.json).
+
+        Args:
+            path: Chemin vers le fichier JSON.
+
+        Raises:
+            FileNotFoundError: Si le fichier n'existe pas.
+            ValueError:        Si le JSON est malformé ou un produit est invalide.
+        """
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"Catalogue introuvable : {path}")
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"JSON malformé dans {path} : {exc}") from exc
+
+        products = data.get("products", [])
+        if not products:
+            logger.warning("Catalogue vide : aucun produit chargé depuis %s", path)
+            return
+
+        for raw in products:
+            try:
+                meta = ProductMeta(
+                    name         = raw["name"],
+                    product_type = ProductType.from_str(raw["type"]),
+                    niche        = raw["niche"],
+                    price        = float(raw["price"]),
+                    location     = raw.get("location"),
+                    avg_rating   = float(raw["avg_rating"]),
+                    review_count = int(raw["review_count"]),
+                    tags         = [str(t) for t in raw["tags"]],
+                )
+                self.add_product(int(raw["id"]), meta)
+            except (KeyError, TypeError, ValueError) as exc:
+                raise ValueError(f"Produit invalide (id={raw.get('id', '?')}) : {exc}") from exc
+
+        logger.info("Catalogue chargé : %d produits depuis %s", len(products), path)
+
+    def add_product(self, product_id: int, meta: ProductMeta) -> None:
+        """
+        Indexe un produit.
+
+        Args:
+            product_id: Identifiant unique (entier positif).
+            meta:       Métadonnées complètes du produit.
+
+        Raises:
+            ValueError: Si product_id est négatif ou déjà présent.
+        """
+        if product_id < 0:
+            raise ValueError(f"product_id doit être >= 0, reçu : {product_id}")
+        if product_id in self.catalog:
+            logger.warning("Produit %d déjà indexé — écrasement.", product_id)
+
+        self.catalog[product_id] = meta
+
+        for tag in meta.tags:
+            tag_lower = tag.lower()
+            if tag_lower not in self.inverted_index:
+                self.inverted_index[tag_lower] = CompressedPostingsList()
+                self._all_tags.append(tag_lower)
+            self.inverted_index[tag_lower].add(product_id)
+
+        self.bm25.index(product_id, meta.tags)
+
+        for pl in self.inverted_index.values():
+            pl.flush()
+        self.dawg = DAWG.build(self._all_tags)
+        self.cache.invalidate()
+        logger.debug("Produit %d indexé : '%s'", product_id, meta.name)
+
+    # ── Recherche ────────────────────────────────────────────────────────────
+
+    def search(
+        self,
+        query    : str,
+        prefs    : SearchPreferences | None = None,
+        fuzzy    : bool = True,
+        max_dist : int  = 1,
+        top_k    : int  = 10,
+    ) -> tuple[list[dict], str]:
+        """
+        Recherche multidimensionnelle in-memory.
+
+        Flux :
+            1. DAWG fuzzy/autocomplete → matched_tags
+            2. CompressedPostingsList  → candidate_ids
+            3. BM25Index.score()       → bm25_raw par produit
+            4. calculate_final_score() → score final (5 dimensions)
+            5. Tri décroissant + top_k + cache LRU
+
+        Args:
+            query:    Requête utilisateur (chaîne brute, normalisée en interne).
+            prefs:    Préférences de re-ranking. None = comportement neutre.
+            fuzzy:    Si True, utilise la recherche floue (Levenshtein + pruning).
+            max_dist: Distance de Levenshtein maximale (1 = 1 faute de frappe).
+            top_k:    Nombre maximum de résultats retournés.
+
+        Returns:
+            Tuple (results, status) où :
+                results : liste de dicts triés par score décroissant.
+                    Champs : id, name, type, niche, price, rating, reviews, score.
+                status  : "CACHÉ" | "CALCULÉ" | "MISS".
+
+        Raises:
+            ValueError: Si query est vide ou max_dist < 0.
+        """
+        if not query or not query.strip():
+            raise ValueError("La requête ne peut pas être vide.")
+        if max_dist < 0:
+            raise ValueError(f"max_dist doit être >= 0, reçu : {max_dist}")
+        if not self.catalog:
+            logger.warning("search() appelé sur un index vide.")
+            return [], "MISS"
+
+        if prefs is None:
+            prefs = SearchPreferences()
+
+        cache_key = f"{query.strip().lower()}|{prefs}"
+        cached = self.cache.get(cache_key)
+        if cached is not None:
+            logger.debug("Cache HIT pour '%s'", query)
+            return cached, "CACHÉ"
+
+        query_lower = query.strip().lower()
+
+        # 1. Tags via DAWG
+        try:
+            matched_tags = (
+                self.dawg.fuzzy_search(query_lower, max_dist)
+                if fuzzy else
+                self.dawg.autocomplete(query_lower)
+            )
+        except Exception as exc:
+            logger.error("Erreur DAWG pour '%s' : %s", query, exc)
+            return [], "MISS"
+
+        if not matched_tags:
+            logger.debug("Aucun tag trouvé pour '%s'", query)
+            return [], "MISS"
+
+        # 2. Candidats via inverted index
+        candidate_ids: set[int] = set()
+        for tag in matched_tags:
+            if tag in self.inverted_index:
+                try:
+                    candidate_ids.update(self.inverted_index[tag].decompress())
+                except Exception as exc:
+                    logger.error("Erreur décompression postings '%s' : %s", tag, exc)
+
+        if not candidate_ids:
+            return [], "MISS"
+
+        # 3. BM25 + re-ranking
+        results: list[dict] = []
+        for pid in candidate_ids:
+            meta = self.catalog.get(pid)
+            if meta is None:
+                logger.warning("product_id %d dans l'index mais absent du catalogue.", pid)
+                continue
+            try:
+                bm25_raw    = self.bm25.score(pid, matched_tags)
+                final_score = calculate_final_score(pid, meta, bm25_raw, prefs)
+            except Exception as exc:
+                logger.error("Erreur scoring produit %d : %s", pid, exc)
+                continue
+
+            if final_score is None:
+                continue
+
+            results.append({
+                "id"     : pid,
+                "name"   : meta.name,
+                "type"   : meta.product_type.name,
+                "niche"  : meta.niche,
+                "price"  : meta.price,
+                "rating" : meta.avg_rating,
+                "reviews": meta.review_count,
+                "score"  : final_score,
+            })
+
+        results.sort(key=lambda x: x["score"], reverse=True)
+        final_list = results[:top_k]
+
+        self.cache.put(cache_key, final_list)
+        logger.info("Recherche '%s' : %d résultats (%d candidats)", query, len(final_list), len(candidate_ids))
+        return final_list, "CALCULÉ"

tagsearch-1.0.0/tagsearch/models.py

@@ -0,0 +1,81 @@
+"""
+tagsearch.models
+================
+Structures de données métier : ProductType, ProductMeta, SearchPreferences.
+Tous les dataclasses utilisent slots=True (Python 3.10+) pour minimiser la RAM.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ProductType(Enum):
+    """Type de produit. Encodé comme entier pour comparaison O(1)."""
+    PHYSICAL = 0
+    DIGITAL  = 1
+
+    @classmethod
+    def from_str(cls, value: str) -> "ProductType":
+        """Parse depuis une chaîne JSON ('PHYSICAL' | 'DIGITAL')."""
+        try:
+            return cls[value.upper()]
+        except KeyError:
+            raise ValueError(f"ProductType invalide : '{value}'. Attendu : PHYSICAL | DIGITAL")
+
+
+@dataclass(slots=True)
+class ProductMeta:
+    """
+    Métadonnées complètes d'un produit.
+
+    Args:
+        name:         Nom affiché du produit.
+        product_type: PHYSICAL ou DIGITAL.
+        niche:        Catégorie (gaming, cuisine, beauté…). Interné via sys.intern.
+        price:        Prix en euros (float).
+        location:     Zone de livraison. None pour les produits digitaux.
+        avg_rating:   Note moyenne des avis (0.0–5.0).
+        review_count: Nombre d'avis. Pondère la fiabilité du rating (Bayesian).
+        tags:         Liste de tags indexés.
+    """
+    name         : str
+    product_type : ProductType
+    niche        : str
+    price        : float
+    location     : str | None
+    avg_rating   : float
+    review_count : int
+    tags         : list[str]
+
+    def __post_init__(self) -> None:
+        import sys
+        self.niche = sys.intern(self.niche.lower())
+        if not 0.0 <= self.avg_rating <= 5.0:
+            raise ValueError(f"avg_rating doit être dans [0.0, 5.0], reçu : {self.avg_rating}")
+        if self.review_count < 0:
+            raise ValueError(f"review_count doit être >= 0, reçu : {self.review_count}")
+        if self.price < 0:
+            raise ValueError(f"price doit être >= 0, reçu : {self.price}")
+
+
+@dataclass(slots=True)
+class SearchPreferences:
+    """
+    Préférences utilisateur pour le re-ranking multidimensionnel.
+    Toutes les valeurs sont optionnelles (None = neutre).
+
+    Args:
+        preferred_type:  Filtre doux sur le type (PHYSICAL/DIGITAL).
+        preferred_niche: Boost +20% si la niche correspond.
+        max_price:       Filtre dur : exclut les produits au-dessus.
+        min_price:       Filtre dur : exclut les produits en-dessous.
+        user_location:   Bonus +15% si la zone de livraison correspond.
+        min_rating:      Filtre dur : exclut les produits en-dessous de ce seuil.
+    """
+    preferred_type  : ProductType | None = None
+    preferred_niche : str | None         = None
+    max_price       : float | None       = None
+    min_price       : float | None       = None
+    user_location   : str | None         = None
+    min_rating      : float              = 0.0

tagsearch-1.0.0/tagsearch/scoring.py

@@ -0,0 +1,177 @@
+"""
+tagsearch.scoring
+=================
+BM25Index + calculate_final_score.
+
+Formules canoniques documentées ici — source de vérité pour le portage TS/PHP.
+Toute modification doit être répercutée dans shared-assets/catalog.json
+(section scoring_constants) et dans les tests cross-langage.
+"""
+
+from __future__ import annotations
+import logging
+import math
+from collections import defaultdict
+
+from .models import ProductMeta, ProductType, SearchPreferences
+
+logger = logging.getLogger(__name__)
+
+# ── Constantes de scoring (synchronisées avec shared-assets/catalog.json) ───
+BM25_K1          = 1.5
+BM25_B           = 0.75
+BM25_CAP         = 10.0   # Plafond de normalisation BM25 → score dans [0,1]
+BM25_FLOOR       = 0.05   # Plancher : tag très fréquent reste visible
+QUALITY_EXPONENT = 1.5    # Courbe convexe : pénalise sévèrement les notes < 3/5
+PRIOR_MEAN       = 3.5    # Note a priori marché e-commerce
+PRIOR_WEIGHT     = 10.0   # Équivalent 10 avis fictifs (lissage Bayesian)
+TYPE_MISMATCH    = 0.1    # Facteur si type ne correspond pas (filtre doux)
+NICHE_BOOST      = 1.2    # +20% si niche correspond
+PROXIMITY_BONUS  = 1.15   # +15% si zone de livraison correspond
+PRICE_BUDGET_BOOST = 1.1  # +10% si prix ≤ 50% du budget max
+
+
+class BM25Index:
+    """
+    BM25 (Okapi BM25) in-memory sur les tags produits.
+
+    Formule IDF :
+        IDF(q) = log( (N - df(q) + 0.5) / (df(q) + 0.5) + 1 )
+        Le +1 évite les valeurs négatives pour les termes très fréquents.
+
+    Formule TF normalisée :
+        TF_norm(q, d) = tf(q,d) × (K1+1) / (tf(q,d) + K1×(1 - B + B×dl/avgdl))
+
+    Score BM25(d, Q) = Σ IDF(qi) × TF_norm(qi, d)
+    """
+
+    def __init__(self) -> None:
+        self.tf:    dict[str, dict[int, int]] = defaultdict(lambda: defaultdict(int))
+        self.df:    dict[str, int]            = defaultdict(int)
+        self.dl:    dict[int, int]            = {}
+        self.N:     int                       = 0
+        self.avgdl: float                     = 0.0
+
+    def index(self, product_id: int, tags: list[str]) -> None:
+        """
+        Indexe les tags d'un produit.
+
+        Args:
+            product_id: Identifiant unique du produit.
+            tags:       Liste de tags (non normalisés, la normalisation est interne).
+        """
+        tags_lower = [t.lower() for t in tags]
+        self.dl[product_id] = len(tags_lower)
+        self.N += 1
+        self.avgdl = sum(self.dl.values()) / self.N
+        for tag in tags_lower:
+            self.tf[tag][product_id] += 1
+            if self.tf[tag][product_id] == 1:
+                self.df[tag] += 1
+        logger.debug("BM25: produit %d indexé (%d tags, avgdl=%.2f)", product_id, len(tags_lower), self.avgdl)
+
+    def score(self, product_id: int, query_tags: list[str]) -> float:
+        """
+        Calcule le score BM25 brut pour un produit et une liste de tags requête.
+
+        Args:
+            product_id:  ID du produit à scorer.
+            query_tags:  Tags issus de la recherche DAWG (matched_tags).
+
+        Returns:
+            Score BM25 brut (non normalisé, non plafonné). Typiquement dans [0, 15].
+        """
+        if self.N == 0 or self.avgdl == 0:
+            return 0.0
+        total = 0.0
+        dl_d = self.dl.get(product_id, 0)
+        for tag in query_tags:
+            tag = tag.lower()
+            tf_val = self.tf[tag].get(product_id, 0)
+            if tf_val == 0: continue
+            df_val = self.df.get(tag, 0)
+            idf  = math.log((self.N - df_val + 0.5) / (df_val + 0.5) + 1)
+            norm = tf_val * (BM25_K1 + 1) / (tf_val + BM25_K1 * (1 - BM25_B + BM25_B * dl_d / self.avgdl))
+            total += idf * norm
+        return total
+
+
+def calculate_final_score(
+    product_id: int,
+    meta:       ProductMeta,
+    bm25_raw:   float,
+    prefs:      SearchPreferences,
+) -> float | None:
+    """
+    Re-ranking multidimensionnel Phase 2.
+
+    Formule (multiplicative) :
+        final = bm25_norm × quality_mult × type_factor × niche_boost
+                × proximity_bonus × price_factor
+
+    Args:
+        product_id: ID du produit (utilisé pour le logging).
+        meta:       Métadonnées complètes du produit.
+        bm25_raw:   Score BM25 brut retourné par BM25Index.score().
+        prefs:      Préférences utilisateur pour le re-ranking.
+
+    Returns:
+        float arrondi à 4 décimales, ou None si le produit est exclu par un filtre dur.
+
+    Raises:
+        TypeError: Si meta ou prefs ne sont pas du bon type.
+    """
+    if not isinstance(meta, ProductMeta):
+        raise TypeError(f"meta doit être ProductMeta, reçu : {type(meta)}")
+    if not isinstance(prefs, SearchPreferences):
+        raise TypeError(f"prefs doit être SearchPreferences, reçu : {type(prefs)}")
+
+    # ── Filtres durs ────────────────────────────────────────────────────────
+    if prefs.max_price is not None and meta.price > prefs.max_price:
+        logger.debug("Produit %d exclu : prix %.2f > max %.2f", product_id, meta.price, prefs.max_price)
+        return None
+    if prefs.min_price is not None and meta.price < prefs.min_price:
+        logger.debug("Produit %d exclu : prix %.2f < min %.2f", product_id, meta.price, prefs.min_price)
+        return None
+    if meta.avg_rating < prefs.min_rating:
+        logger.debug("Produit %d exclu : rating %.1f < min %.1f", product_id, meta.avg_rating, prefs.min_rating)
+        return None
+
+    # ── Dim 1 : BM25 normalisé ──────────────────────────────────────────────
+    bm25_norm = max(min(bm25_raw / BM25_CAP, 1.0), BM25_FLOOR)
+
+    # ── Dim 2 : Qualité Bayesian ────────────────────────────────────────────
+    bayesian = (meta.review_count * meta.avg_rating + PRIOR_MEAN * PRIOR_WEIGHT) / (meta.review_count + PRIOR_WEIGHT)
+    quality_mult = (bayesian / 5.0) ** QUALITY_EXPONENT
+
+    # ── Dim 3 : Type + Niche ────────────────────────────────────────────────
+    type_factor = TYPE_MISMATCH if (
+        prefs.preferred_type is not None and meta.product_type != prefs.preferred_type
+    ) else 1.0
+
+    niche_factor = NICHE_BOOST if (
+        prefs.preferred_niche is not None
+        and meta.niche == prefs.preferred_niche.lower()
+    ) else 1.0
+
+    # ── Dim 4 : Proximité ───────────────────────────────────────────────────
+    if meta.location is None:
+        proximity = 1.0
+    elif prefs.user_location is not None and meta.location.lower() == prefs.user_location.lower():
+        proximity = PROXIMITY_BONUS
+    else:
+        proximity = 1.0
+
+    # ── Dim 5 : Prix (filtre doux) ──────────────────────────────────────────
+    if prefs.max_price is not None and prefs.max_price > 0:
+        price_factor = PRICE_BUDGET_BOOST if (meta.price / prefs.max_price) <= 0.5 else 1.0
+    else:
+        price_factor = 1.0
+
+    final = bm25_norm * quality_mult * type_factor * niche_factor * proximity * price_factor
+    result = round(final, 4)
+    logger.debug(
+        "Produit %d | bm25=%.4f qmult=%.4f type=%.1f niche=%.1f prox=%.2f price=%.1f → %.4f",
+        product_id, bm25_norm, quality_mult, type_factor, niche_factor, proximity, price_factor, result
+    )
+    return result

tagsearch-1.0.0/tagsearch/structures.py

@@ -0,0 +1,360 @@
+"""
+tagsearch.structures
+====================
+Structures de données bas niveau (Phase 1) :
+  - TrieNode / Trie       : __slots__ + tableau fixe O(1)
+  - DAWGNode / DAWG       : FST simplifié, partage de suffixes
+  - VarInt                : encodage variable-length integer
+  - CompressedPostingsList: delta-encoding + VarInt
+  - LRUCache              : OrderedDict-based O(1) get/put
+"""
+
+from __future__ import annotations
+from collections import OrderedDict
+import logging
+
+logger = logging.getLogger(__name__)
+
+# ── Alphabet ────────────────────────────────────────────────────────────────
+ALPHA_SIZE = 38  # a-z(0-25), 0-9(26-35), -(36), espace(37)
+
+
+def _char_index(c: str) -> int:
+    if 'a' <= c <= 'z': return ord(c) - ord('a')
+    if '0' <= c <= '9': return ord(c) - ord('0') + 26
+    if c == '-': return 36
+    if c == ' ': return 37
+    return -1
+
+
+def _index_to_char(idx: int) -> str:
+    if idx <= 25: return chr(ord('a') + idx)
+    if idx <= 35: return chr(ord('0') + idx - 26)
+    if idx == 36: return '-'
+    return ' '
+
+
+# ── Trie (Phase 1.1 + 1.2) ──────────────────────────────────────────────────
+
+class TrieNode:
+    """Nœud Trie : __slots__ + tableau fixe de 38 pointeurs (lazy init)."""
+    __slots__ = ('children', 'is_terminal', 'tag')
+
+    def __init__(self) -> None:
+        self.children: list | None = None
+        self.is_terminal: bool = False
+        self.tag: str | None = None
+
+    def get_child(self, c: str) -> TrieNode | None:
+        if self.children is None: return None
+        idx = _char_index(c)
+        return None if idx == -1 else self.children[idx]
+
+    def set_child(self, c: str, node: TrieNode) -> None:
+        if self.children is None:
+            self.children = [None] * ALPHA_SIZE
+        idx = _char_index(c)
+        if idx != -1:
+            self.children[idx] = node
+
+    def iter_children(self):
+        if self.children is None: return
+        for idx, child in enumerate(self.children):
+            if child is not None: yield idx, child
+
+
+class Trie:
+    """Trie optimisé mémoire. Utilisé comme buffer d'écriture avant rebuild DAWG."""
+
+    def __init__(self) -> None:
+        self.root = TrieNode()
+
+    def insert(self, word: str) -> None:
+        node = self.root
+        for char in word.lower():
+            child = node.get_child(char)
+            if child is None:
+                child = TrieNode()
+                node.set_child(char, child)
+            node = child
+        node.is_terminal = True
+        node.tag = word
+
+    def autocomplete(self, prefix: str) -> list[str]:
+        node = self.root
+        for char in prefix.lower():
+            node = node.get_child(char)
+            if node is None: return []
+        results: list[str] = []
+        self._dfs(node, results)
+        return results
+
+    def _dfs(self, node: TrieNode, results: list[str]) -> None:
+        if node.is_terminal: results.append(node.tag)  # type: ignore[arg-type]
+        for _, child in node.iter_children():
+            self._dfs(child, results)
+
+    def fuzzy_search(self, query: str, max_distance: int = 1) -> list[str]:
+        """Levenshtein DP avec pruning : coupe les branches si min(row) > max_distance."""
+        query = query.lower()
+        results: list[tuple[str, int]] = []
+        init_row = list(range(len(query) + 1))
+        for idx, child in self.root.iter_children():
+            self._fuzzy_dfs(child, _index_to_char(idx), query, init_row, max_distance, results)
+        results.sort(key=lambda x: x[1])
+        return [tag for tag, _ in results]
+
+    def _fuzzy_dfs(self, node: TrieNode, char: str, query: str,
+                   prev_row: list[int], max_dist: int,
+                   results: list[tuple[str, int]]) -> None:
+        cur = [prev_row[0] + 1]
+        for col in range(1, len(query) + 1):
+            cur.append(min(cur[col-1]+1, prev_row[col]+1,
+                           prev_row[col-1] + (0 if query[col-1] == char else 1)))
+        if min(cur) > max_dist: return
+        if cur[-1] <= max_dist and node.is_terminal:
+            results.append((node.tag, cur[-1]))  # type: ignore[arg-type]
+        for idx, child in node.iter_children():
+            self._fuzzy_dfs(child, _index_to_char(idx), query, cur, max_dist, results)
+
+
+# ── DAWG (Phase 1.3) ────────────────────────────────────────────────────────
+
+class DAWGNode:
+    """Nœud DAWG avec identité structurelle pour déduplication de suffixes."""
+    __slots__ = ('children', 'is_terminal', 'tag', 'frozen', '_hash_cache')
+
+    def __init__(self) -> None:
+        self.children: dict[str, DAWGNode] = {}
+        self.is_terminal: bool = False
+        self.tag: str | None = None
+        self.frozen: bool = False
+        self._hash_cache: int | None = None
+
+    def structural_key(self) -> tuple:
+        return (self.is_terminal, self.tag,
+                tuple(sorted((c, id(n)) for c, n in self.children.items())))
+
+    def __hash__(self) -> int:
+        if self._hash_cache is None:
+            self._hash_cache = hash(self.structural_key())
+        return self._hash_cache
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, DAWGNode) and self.structural_key() == other.structural_key()
+
+
+class DAWG:
+    """
+    DAWG (Directed Acyclic Word Graph) via algorithme de Daciuk.
+    Partage les suffixes communs → 30-50% moins de nœuds vs Trie sur corpus e-commerce.
+    IMMUTABLE après finish(). Utiliser Trie comme buffer pour les insertions dynamiques.
+    """
+
+    def __init__(self) -> None:
+        self.root = DAWGNode()
+        self._minimized: dict[tuple, DAWGNode] = {}
+        self._last_word: str = ""
+        self._unchecked: list[tuple[DAWGNode, str, DAWGNode]] = []
+
+    def _minimize(self, down_to: int) -> None:
+        for i in range(len(self._unchecked) - 1, down_to - 1, -1):
+            parent, char, child = self._unchecked[i]
+            key = child.structural_key()
+            if key in self._minimized:
+                parent.children[char] = self._minimized[key]
+            else:
+                child.frozen = True
+                self._minimized[key] = child
+            self._unchecked.pop()
+
+    def insert(self, word: str) -> None:
+        word = word.lower()
+        if word <= self._last_word and self._last_word:
+            raise ValueError(f"DAWG: insertion hors ordre — '{word}' après '{self._last_word}'.")
+        common = 0
+        for i, (c1, c2) in enumerate(zip(word, self._last_word)):
+            if c1 != c2: break
+            common = i + 1
+        else:
+            common = min(len(word), len(self._last_word))
+        self._minimize(common)
+        node = self.root if not self._unchecked else self._unchecked[-1][2]
+        for char in word[common:]:
+            new_node = DAWGNode()
+            node.children[char] = new_node
+            self._unchecked.append((node, char, new_node))
+            node = new_node
+        node.is_terminal = True
+        node.tag = word
+        self._last_word = word
+
+    def finish(self) -> None:
+        self._minimize(0)
+
+    @classmethod
+    def build(cls, tags: list[str]) -> DAWG:
+        """Construit un DAWG depuis une liste de tags (tri automatique)."""
+        dawg = cls()
+        for tag in sorted(set(t.lower() for t in tags)):
+            dawg.insert(tag)
+        dawg.finish()
+        logger.debug("DAWG construit : %d nœuds uniques", dawg.node_count())
+        return dawg
+
+    def contains(self, word: str) -> bool:
+        node = self.root
+        for char in word.lower():
+            node = node.children.get(char)  # type: ignore[assignment]
+            if node is None: return False
+        return node.is_terminal  # type: ignore[union-attr]
+
+    def autocomplete(self, prefix: str) -> list[str]:
+        node = self.root
+        for char in prefix.lower():
+            node = node.children.get(char)  # type: ignore[assignment]
+            if node is None: return []
+        results: list[str] = []
+        self._dfs(node, results)  # type: ignore[arg-type]
+        return results
+
+    def _dfs(self, node: DAWGNode, results: list[str]) -> None:
+        if node.is_terminal: results.append(node.tag)  # type: ignore[arg-type]
+        for child in node.children.values():
+            self._dfs(child, results)
+
+    def fuzzy_search(self, query: str, max_distance: int = 1) -> list[str]:
+        query = query.lower()
+        results: list[tuple[str, int]] = []
+        init_row = list(range(len(query) + 1))
+        for char, child in self.root.children.items():
+            self._fuzzy_dfs(child, char, query, init_row, max_distance, results)
+        results.sort(key=lambda x: x[1])
+        return [tag for tag, _ in results]
+
+    def _fuzzy_dfs(self, node: DAWGNode, char: str, query: str,
+                   prev_row: list[int], max_dist: int,
+                   results: list[tuple[str, int]]) -> None:
+        cur = [prev_row[0] + 1]
+        for col in range(1, len(query) + 1):
+            cur.append(min(cur[col-1]+1, prev_row[col]+1,
+                           prev_row[col-1] + (0 if query[col-1] == char else 1)))
+        if min(cur) > max_dist: return
+        if cur[-1] <= max_dist and node.is_terminal:
+            results.append((node.tag, cur[-1]))  # type: ignore[arg-type]
+        for next_char, child in node.children.items():
+            self._fuzzy_dfs(child, next_char, query, cur, max_dist, results)
+
+    def node_count(self) -> int:
+        visited: set[int] = set()
+        self._count(self.root, visited)
+        return len(visited)
+
+    def _count(self, node: DAWGNode, visited: set[int]) -> None:
+        if id(node) in visited: return
+        visited.add(id(node))
+        for child in node.children.values():
+            self._count(child, visited)
+
+
+# ── VarInt + CompressedPostingsList (Phase 1.4) ─────────────────────────────
+
+class VarInt:
+    """Encodage variable-length integer (Protocol Buffers style)."""
+
+    @staticmethod
+    def encode(value: int) -> bytes:
+        if value < 0:
+            raise ValueError(f"VarInt: valeur négative non supportée : {value}")
+        buf = []
+        while True:
+            byte = value & 0x7F
+            value >>= 7
+            buf.append(byte | 0x80 if value else byte)
+            if not value: break
+        return bytes(buf)
+
+    @staticmethod
+    def decode(data: bytes, offset: int = 0) -> tuple[int, int]:
+        result, shift = 0, 0
+        while True:
+            if offset >= len(data):
+                raise ValueError("VarInt: données tronquées (offset hors limites).")
+            byte = data[offset]; offset += 1
+            result |= (byte & 0x7F) << shift
+            if not (byte & 0x80): break
+            shift += 7
+        return result, offset
+
+
+class CompressedPostingsList:
+    """
+    Postings list compressée : delta-encoding + VarInt.
+    ~98% de réduction vs set Python sur 500 IDs aléatoires.
+    Dirty buffer : flush() déclenche la compression en batch.
+    """
+
+    def __init__(self) -> None:
+        self._compressed: bytes = b''
+        self._pending: list[int] = []
+        self._dirty: bool = False
+
+    def add(self, product_id: int) -> None:
+        if product_id < 0:
+            raise ValueError(f"product_id doit être >= 0, reçu : {product_id}")
+        self._pending.append(product_id)
+        self._dirty = True
+
+    def flush(self) -> None:
+        if not self._dirty: return
+        all_ids = sorted(set(self.decompress()) | set(self._pending))
+        buf = bytearray()
+        prev = 0
+        for pid in all_ids:
+            buf += VarInt.encode(pid - prev)
+            prev = pid
+        self._compressed = bytes(buf)
+        self._pending.clear()
+        self._dirty = False
+
+    def decompress(self) -> list[int]:
+        ids, offset, current = [], 0, 0
+        while offset < len(self._compressed):
+            delta, offset = VarInt.decode(self._compressed, offset)
+            current += delta
+            ids.append(current)
+        if self._pending:
+            ids = sorted(set(ids) | set(self._pending))
+        return ids
+
+    def __contains__(self, pid: int) -> bool:
+        return pid in self.decompress()
+
+    def memory_bytes(self) -> int:
+        return len(self._compressed) + len(self._pending) * 28
+
+
+# ── LRU Cache ────────────────────────────────────────────────────────────────
+
+class LRUCache:
+    """Cache LRU O(1) get/put via OrderedDict."""
+
+    def __init__(self, capacity: int) -> None:
+        if capacity <= 0:
+            raise ValueError(f"LRUCache capacity doit être > 0, reçu : {capacity}")
+        self._cache: OrderedDict = OrderedDict()
+        self.capacity = capacity
+
+    def get(self, key: str):
+        if key not in self._cache: return None
+        self._cache.move_to_end(key)
+        return self._cache[key]
+
+    def put(self, key: str, value) -> None:
+        if key in self._cache: self._cache.move_to_end(key)
+        self._cache[key] = value
+        if len(self._cache) > self.capacity:
+            self._cache.popitem(last=False)
+
+    def invalidate(self) -> None:
+        self._cache.clear()

tagsearch-1.0.0/tagsearch.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: tagsearch
+Version: 1.0.0
+Summary: In-memory tag search engine for e-commerce (DAWG + BM25 + hybrid ranking)
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

tagsearch-1.0.0/tagsearch.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+tagsearch/__init__.py
+tagsearch/engine.py
+tagsearch/models.py
+tagsearch/scoring.py
+tagsearch/structures.py
+tagsearch.egg-info/PKG-INFO
+tagsearch.egg-info/SOURCES.txt
+tagsearch.egg-info/dependency_links.txt
+tagsearch.egg-info/requires.txt
+tagsearch.egg-info/top_level.txt
+tests/test_cross_language.py

tagsearch-1.0.0/tagsearch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tagsearch-1.0.0/tagsearch.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8.0
+pytest-cov

tagsearch-1.0.0/tagsearch.egg-info/top_level.txt

@@ -0,0 +1 @@
+tagsearch

tagsearch-1.0.0/tests/test_cross_language.py

@@ -0,0 +1,187 @@
+"""
+Tests cross-langage — source de vérité Python.
+Charge shared-assets/catalog.json et génère les scores de référence.
+Ces mêmes cas sont rejoués en TS (Vitest) et PHP (PHPUnit) avec tolérance 1e-9.
+"""
+
+import json
+import math
+import pytest
+from pathlib import Path
+
+from tagsearch import SearchEngine, SearchPreferences
+from tagsearch.models import ProductType
+from tagsearch.scoring import (
+    BM25Index, calculate_final_score,
+    BM25_K1, BM25_B, BM25_CAP, BM25_FLOOR,
+    QUALITY_EXPONENT, PRIOR_MEAN, PRIOR_WEIGHT,
+)
+
+CATALOG_PATH = Path(__file__).parent.parent.parent / "shared-assets" / "catalog.json"
+TOLERANCE    = 1e-9
+
+
+@pytest.fixture(scope="module")
+def engine() -> SearchEngine:
+    eng = SearchEngine(cache_size=50)
+    eng.load_catalog(CATALOG_PATH)
+    return eng
+
+
+# ── Tests unitaires BM25 (composants isolés) ────────────────────────────────
+
+class TestBM25Components:
+    """Valide chaque composant BM25 séparément pour le portage cross-langage."""
+
+    def test_idf_formula(self):
+        """IDF = log((N - df + 0.5) / (df + 0.5) + 1)"""
+        N, df = 10, 3
+        expected = math.log((N - df + 0.5) / (df + 0.5) + 1)
+        assert abs(expected - math.log(7.5 / 3.5 + 1)) < TOLERANCE
+
+    def test_tf_norm_saturation(self):
+        """TF normalisé sature : tf=10 ne vaut pas 10× tf=1."""
+        dl, avgdl = 5, 5.0
+        tf1  = 1  * (BM25_K1 + 1) / (1  + BM25_K1 * (1 - BM25_B + BM25_B * dl / avgdl))
+        tf10 = 10 * (BM25_K1 + 1) / (10 + BM25_K1 * (1 - BM25_B + BM25_B * dl / avgdl))
+        assert tf10 < tf1 * 10, "BM25 doit saturer la fréquence des termes"
+
+    def test_bm25_zero_on_missing_tag(self):
+        idx = BM25Index()
+        idx.index(1, ["gaming", "tech"])
+        assert idx.score(1, ["cuisine"]) == 0.0
+
+    def test_bm25_positive_on_matching_tag(self):
+        idx = BM25Index()
+        idx.index(1, ["gaming", "tech"])
+        idx.index(2, ["cuisine"])
+        score = idx.score(1, ["gaming"])
+        assert score > 0.0
+
+
+# ── Tests scoring multidimensionnel ─────────────────────────────────────────
+
+class TestScoringDimensions:
+
+    def _make_engine(self) -> SearchEngine:
+        eng = SearchEngine(cache_size=10)
+        eng.load_catalog(CATALOG_PATH)
+        return eng
+
+    def test_tc01_cuisine_physical_beats_digital(self, engine):
+        """TC01 : Robot pâtissier (Physical) > E-book (Digital) sans filtre."""
+        results, _ = engine.search("cuisine", fuzzy=False)
+        ids = [r["id"] for r in results]
+        assert 4 in ids and 5 in ids
+        score_robot  = next(r["score"] for r in results if r["id"] == 4)
+        score_ebook  = next(r["score"] for r in results if r["id"] == 5)
+        assert score_robot > score_ebook
+
+    def test_tc02_digital_filter_inverts_order(self, engine):
+        """TC02 : preferred_type=DIGITAL → E-book devant Robot."""
+        prefs = SearchPreferences(preferred_type=ProductType.DIGITAL)
+        results, _ = engine.search("cuisine", prefs=prefs, fuzzy=False)
+        ids = [r["id"] for r in results]
+        assert ids.index(5) < ids.index(4)
+
+    def test_tc03_price_filter_excludes_clavier(self, engine):
+        """TC03 : budget 100€ → Clavier (129.99€) exclu."""
+        prefs = SearchPreferences(max_price=100.0)
+        results, _ = engine.search("gaming", prefs=prefs, fuzzy=False)
+        ids = [r["id"] for r in results]
+        assert 1 not in ids   # Clavier exclu
+        assert 2 in ids       # Souris présente
+
+    def test_tc04_min_rating_excludes_serum(self, engine):
+        """TC04 : min_rating=4.0 → Sérum (2.8★) exclu."""
+        prefs = SearchPreferences(min_rating=4.0)
+        results, _ = engine.search("beauté", prefs=prefs, fuzzy=False)
+        ids = [r["id"] for r in results]
+        assert 7 not in ids   # Sérum exclu
+        assert 8 in ids       # Palette présente
+
+    def test_tc05_fuzzy_gaming_typo(self, engine):
+        """TC05 : 'gaiming' → résultats gaming via fuzzy."""
+        results, _ = engine.search("gaiming", fuzzy=True, max_dist=1)
+        niches = {r["niche"] for r in results}
+        assert "gaming" in niches
+
+    def test_bayesian_rating_smoothing(self, engine):
+        """Produit avec peu d'avis est tiré vers la moyenne marché."""
+        serum   = engine.catalog[7]   # 2.8★, 12 avis
+        palette = engine.catalog[8]   # 4.5★, 276 avis
+        br_serum   = (serum.review_count   * serum.avg_rating   + PRIOR_MEAN * PRIOR_WEIGHT) / (serum.review_count   + PRIOR_WEIGHT)
+        br_palette = (palette.review_count * palette.avg_rating + PRIOR_MEAN * PRIOR_WEIGHT) / (palette.review_count + PRIOR_WEIGHT)
+        # Le sérum est tiré vers 3.5 (PRIOR_MEAN), la palette reste proche de 4.5
+        assert br_serum > serum.avg_rating      # Tiré vers le haut (était très bas)
+        assert br_palette < palette.avg_rating  # Légèrement tiré vers le bas
+        assert br_palette > br_serum
+
+
+# ── Génération des scores de référence (cross-language fixture) ──────────────
+
+class TestCrossLanguageFixtures:
+    """
+    Génère et valide les scores de référence pour TS et PHP.
+    Ces scores sont la source de vérité : les autres langages doivent
+    tomber dans |score_ref - score_impl| < TOLERANCE (1e-9).
+    """
+
+    def test_reference_scores_stable(self, engine):
+        """Les scores de référence ne doivent pas changer entre runs."""
+        results, _ = engine.search("cuisine", fuzzy=False)
+        scores = {r["id"]: r["score"] for r in results}
+        # Scores attendus (calculés lors de la validation Phase 2)
+        assert abs(scores[4] - 0.1354) < 1e-3   # Robot pâtissier
+        assert abs(scores[5] - 0.1082) < 1e-3   # E-book
+
+    def test_type_mismatch_factor(self, engine):
+        """Le facteur TYPE_MISMATCH=0.1 doit diviser le score par ~10.
+        Tolérance 1e-3 : les scores sont arrondis à 4 décimales avant division,
+        ce qui introduit une erreur d'arrondi de l'ordre de 1e-4/score_base.
+        """
+        results_no_filter, _ = engine.search("cuisine", fuzzy=False)
+        prefs = SearchPreferences(preferred_type=ProductType.DIGITAL)
+        results_digital, _   = engine.search("cuisine", prefs=prefs, fuzzy=False)
+
+        score_robot_base    = next(r["score"] for r in results_no_filter if r["id"] == 4)
+        score_robot_digital = next(r["score"] for r in results_digital   if r["id"] == 4)
+        ratio = score_robot_digital / score_robot_base
+        assert abs(ratio - 0.1) < 1e-3, f"Ratio attendu ~0.1, obtenu {ratio}"
+
+
+# ── Tests robustesse & gestion d'erreurs ────────────────────────────────────
+
+class TestRobustness:
+
+    def test_empty_query_raises(self, engine):
+        with pytest.raises(ValueError, match="vide"):
+            engine.search("")
+
+    def test_whitespace_query_raises(self, engine):
+        with pytest.raises(ValueError, match="vide"):
+            engine.search("   ")
+
+    def test_negative_max_dist_raises(self, engine):
+        with pytest.raises(ValueError, match="max_dist"):
+            engine.search("gaming", max_dist=-1)
+
+    def test_unknown_query_returns_miss(self, engine):
+        results, status = engine.search("xyzqwerty123", fuzzy=False)
+        assert results == []
+        assert status == "MISS"
+
+    def test_cache_hit_on_repeat(self, engine):
+        engine.search("yoga", fuzzy=False)
+        _, status = engine.search("yoga", fuzzy=False)
+        assert status == "CACHÉ"
+
+    def test_load_nonexistent_file_raises(self):
+        eng = SearchEngine()
+        with pytest.raises(FileNotFoundError):
+            eng.load_catalog("/nonexistent/path/catalog.json")
+
+    def test_invalid_rating_raises(self):
+        from tagsearch.models import ProductMeta, ProductType
+        with pytest.raises(ValueError, match="avg_rating"):
+            ProductMeta("Test", ProductType.PHYSICAL, "gaming", 10.0, None, 6.0, 10, ["tag"])