# Text mining des descriptions — `louka/textmine.py`

Analyse déterministe des descriptions d'annonces, exécutée à l'ingestion
(~1 ms par annonce en moyenne, p95 ≈ 4 ms sur le corpus complet de 3 763
descriptions). Aucune dépendance lourde : ni spaCy, ni LLM — uniquement des
règles et des expressions régulières françaises, plus la réutilisation des
extracteurs de `louka/normalize.py` (`parse_price`, `parse_availability_date`,
`extract_details`, `strip_accents`).

## API

```python
from louka.textmine import analyser

resultat = analyser(description, price=..., sector=..., city=...)
# None si description vide ou < 40 caractères, sinon un dict JSON strict
```

Les arguments `price`, `sector` et `city` (champs de l'annonce) ne servent
qu'aux contrôles de cohérence — jamais à inventer un fait absent du texte.

## Pipeline

### Étape A — nettoyage (déterministe)

- **Lignes/segments EN MAJUSCULES** (> 60 % de majuscules, > 8 caractères,
  ≤ 60, sans `!`/`?` ni point final) → titres de section, remis en
  capitalisation de titre (« L'ESPACE DE VIE » → « L'espace de vie »).
  Les phrases criées (« FRAIS PEINT !! ») sont remises en casse de phrase
  sans devenir des titres. Garde-fou : une description entièrement en
  majuscules ne produit aucun titre.
- **Mots consécutifs dupliqués** (« Disponible disponible » → « Disponible »),
  insensible à la casse et aux accents, avec récupération de la ponctuation.
- **Phrases collées** : « lumineuxVenez » → « lumineux. Venez » (deux
  minuscules + majuscule + trois minuscules ; « McDonald » est épargné).
- **Typographie québécoise** : espace insécable avant `$` et `%`
  (« 450$ » → « 450 $ »), espaces multiples réduits, puces variées → « • ».
- **Ponctuation répétée** neutralisée (« !!! » → « ! »).
- Les paragraphes (sauts de ligne) sont préservés dans `texte_nettoye`.

### Étape B — extraction de faits

- `prix_mensuel` et `date_disponibilite` via `normalize.parse_price` /
  `parse_availability_date` ; la disponibilité est ancrée sur un mot-clé
  (« disponible », « libre », « occupation ») pour ne pas dater une porte
  ouverte, et « indisponible » est écarté.
- `extract_details` de normalize fournit la base (inclusions,
  électroménagers, animaux, fumeur, meublé) ; le texte nettoyé lui est passé
  ligne par ligne (pré-filtré et tronçonné) pour garder ses motifs négatifs
  précis et l'exécution rapide.
- Compléments propres au module : durée de bail minimale (« minimum
  3 mois », « bail d'un an »), nombre d'occupants (« Total de
  11 chambreurs », « colocation de 5 »), salle de bain / cuisine commune ou
  privée, micro-ondes/poêle, dépôt mentionné (extrait source, jamais
  reformulé), quartier mentionné (≈ 40 quartiers courants de Québec, Lévis
  et du Grand Montréal).

### Étape C — sections

- Texte découpé selon les titres détectés à l'étape A (le préambule devient
  « Description »).
- Sans titres et texte > 400 caractères : découpage par thème via ancres
  regex — règles/interdits → « Bon à savoir » ; colocation/espaces communs →
  « L'espace de vie » ; frais/inclusions → « Frais et conditions » ; reste →
  « Description ».
- Chaque section est du texte source nettoyé, **jamais reformulé**.

### Étape D — synthèse

- `en_bref` : 1 à 3 phrases assemblées **par gabarit** à partir des seuls
  faits en confiance « haute » (aucune invention) : loyer/disponibilité,
  meublé/inclusions, vie commune/bail.
- `confiance` : « haute » ou « faible » par fait extrait (prix sans contexte
  mensuel, durée de bail dans une promotion, quartier sans préposition… →
  « faible », non affiché en badge).
- `incoherences` : quartier mentionné ≠ secteur de l'annonce, quartier d'une
  autre ville, prix du texte ≠ prix de l'annonce.
- `completude` (0-100) : prix 20, disponibilité 15, inclusions 20,
  sdb/cuisine 10, occupants 10, contraintes 10, texte > 200 caractères 15.

## Complétude sur le corpus

- 20 annonces aléatoires (graine 42) : moyenne **26,5 / 100**
  (valeurs : 0, 80, 35, 15, 0, 55, 15, 50, 35, 45, 0, 20, 15, 15, 0, 20, 60, 35, 35, 0).
- Corpus complet (3 763 descriptions ≥ 40 caractères) : moyenne **18,9 / 100**
  — la plupart des descriptions de gestionnaires sont du texte de marque
  sans prix ni disponibilité, ce que le score reflète.

## Exemples réels (JSON produit)

### `gestipro:24813` — 2435 boul. Laurier (Gestipro) — chambre, cas de référence
```json
{
 "version": 1,
 "texte_nettoye": "Chambre meublé de base en location située au 2435 boul. Laurier à Sillery. Disponible\ndès maintenant\nà 450 $ par mois, chauffage, électricité, eau chaude et wifi inclus. Location pour minimum 3 mois.\nL’espace de vie\nTotal de 11 chambreurs dans la maison\nCuisine et salle de bain commune aux autres occupants de l’appartement\nRéfrigérateur, cuisinière, laveuse et sécheuse inclus dans les pièces communes\nChambre meublée de base comme sur les photos, pour occupation simple seulement\n\nFrais et charges\nChauffage, eau chaude et électricité inclus\nWifi inclus\nÀ proximité / secteur\nSecteur très prisé de la ville\nÀ proximité des ponts, de l’autoroute Robert-Bourassa et de l’autoroute Henri IV\nPrès de tous les services de Sillery et Ste-Foy dont Laurier Québec, Place de la Cité et Place Ste-Foy.\nUniversité Laval à distance de marche\nPrendre note qu’afin d’offrir à nos locataires une tranquillité, les animaux ne sont pas acceptés. Enquête de crédit obligatoire pour tous nos nouveaux locataires.\nPour visiter, communiquez avec Gestipro au 418-522-2525 poste 1\nPour consulter tous nos appartements à louer, visitez le www.gestipro.info",
 "en_bref": "Loyer de 450 $ par mois, disponible dès maintenant. Meublé ; chauffage, électricité, eau chaude et wifi inclus. 11 occupants au total, cuisine et salle de bain communes, bail minimum de 3 mois.",
 "sections": [
  {
   "titre": "Description",
   "texte": "Chambre meublé de base en location située au 2435 boul. Laurier à Sillery. Disponible\ndès maintenant\nà 450 $ par mois, chauffage, électricité, eau chaude et wifi inclus. Location pour minimum 3 mois."
  },
  {
   "titre": "L’espace de vie",
   "texte": "Total de 11 chambreurs dans la maison\nCuisine et salle de bain commune aux autres occupants de l’appartement\nRéfrigérateur, cuisinière, laveuse et sécheuse inclus dans les pièces communes\nChambre meublée de base comme sur les photos, pour occupation simple seulement"
  },
  {
   "titre": "Frais et charges",
   "texte": "Chauffage, eau chaude et électricité inclus\nWifi inclus"
  },
  {
   "titre": "À proximité / secteur",
   "texte": "Secteur très prisé de la ville\nÀ proximité des ponts, de l’autoroute Robert-Bourassa et de l’autoroute Henri IV\nPrès de tous les services de Sillery et Ste-Foy dont Laurier Québec, Place de la Cité et Place Ste-Foy.\nUniversité Laval à distance de marche\nPrendre note qu’afin d’offrir à nos locataires une tranquillité, les animaux ne sont pas acceptés. Enquête de crédit obligatoire pour tous nos nouveaux locataires.\nPour visiter, communiquez avec Gestipro au 418-522-2525 poste 1\nPour consulter tous nos appartements à louer, visitez le www.gestipro.info"
  }
 ],
 "faits": {
  "prix_mensuel": 450.0,
  "date_disponibilite": "now",
  "duree_bail_minimale_mois": 3,
  "nb_occupants_total": 11,
  "salle_de_bain": "commune",
  "cuisine": "commune",
  "electromenagers": [
   "frigo",
   "cuisiniere",
   "laveuse",
   "secheuse"
  ],
  "inclusions": [
   "chauffage",
   "electricite",
   "eau_chaude",
   "wifi",
   "meuble"
  ],
  "contraintes": [
   "pas_d_animaux",
   "references_requises",
   "occupation_simple"
  ],
  "depot_mentionne": null,
  "quartier_mentionne": "Sillery"
 },
 "confiance": {
  "prix_mensuel": "haute",
  "date_disponibilite": "haute",
  "duree_bail_minimale_mois": "haute",
  "nb_occupants_total": "haute",
  "salle_de_bain": "haute",
  "cuisine": "haute",
  "electromenagers": "haute",
  "inclusions": "haute",
  "contraintes": "haute",
  "quartier_mentionne": "haute"
 },
 "incoherences": [
  "quartier mentionné (Sillery) ≠ secteur de l'annonce (Sainte-Foy)"
 ],
 "completude": 100
}
```

### `gimcote:10143` — 606 rue Napoléon (GIM Côté) — 3½ Saint-Jean-Baptiste
```json
{
 "version": 1,
 "texte_nettoye": "418-655-8281\nÀ voir au 606 rue Napoléon, superbe grand 3 1/2, entièrement refait à neuf ! Situé dans un immeuble tranquille, situé au 2e et dernier étage. Galerie arrière.\nFrais peint !\nTrès belle cuisine avec magnifiques armoires. Logement bien éclairé!\nPossibilité d’avoir laveuse-sécheuse et frigo inclus moyennant un supplément.\nPlancher de bois et céramique.\nBelle salle de bain, entrée laveuse-sécheuse.\nInstallation lave-vaisselle.\nNon-fumeur.\nChat opéré accepté, pas de chien.\nSituation idéal, en plein coeur du Centre-Ville, accès rapide à la Haute-Ville et aux commerces de la Cité Électronique. Tout les services à proximité tel que épicerie, banques, pharmacie, restaurant etc.. Transport en commun très proche !\n850 $ par mois non-chauffé, non-éclairé\nLibre maintenant\nPour plus d’information ou pour visité, téléphonez à Michel au 418-655-8281",
 "en_bref": "Loyer de 850 $ par mois, disponible dès maintenant.",
 "sections": [
  {
   "titre": "Description",
   "texte": "418-655-8281 À voir au 606 rue Napoléon, superbe grand 3 1/2, entièrement refait à neuf ! Situé dans un immeuble tranquille, situé au 2e et dernier étage. Galerie arrière. Très belle cuisine avec magnifiques armoires. Logement bien éclairé! Plancher de bois et céramique. Belle salle de bain, entrée laveuse-sécheuse. Installation lave-vaisselle. Chat opéré accepté, pas de chien. Situation idéal, en plein coeur du Centre-Ville, accès rapide à la Haute-Ville et aux commerces de la Cité Électronique. Tout les services à proximité tel que épicerie, banques, pharmacie, restaurant etc.. Transport en commun très proche ! Libre maintenant Pour plus d’information ou pour visité, téléphonez à Michel au 418-655-8281"
  },
  {
   "titre": "Frais et conditions",
   "texte": "Frais peint ! Possibilité d’avoir laveuse-sécheuse et frigo inclus moyennant un supplément. 850 $ par mois non-chauffé, non-éclairé"
  },
  {
   "titre": "Bon à savoir",
   "texte": "Non-fumeur."
  }
 ],
 "faits": {
  "prix_mensuel": 850.0,
  "date_disponibilite": "now",
  "duree_bail_minimale_mois": null,
  "nb_occupants_total": null,
  "salle_de_bain": null,
  "cuisine": null,
  "electromenagers": [
   "frigo",
   "lave_vaisselle"
  ],
  "inclusions": [],
  "contraintes": [
   "non_fumeur"
  ],
  "depot_mentionne": null,
  "quartier_mentionne": null
 },
 "confiance": {
  "prix_mensuel": "haute",
  "date_disponibilite": "haute",
  "electromenagers": "haute",
  "contraintes": "haute"
 },
 "incoherences": [],
 "completude": 60
}
```

### `immomarketing:10150-rue-lajeunesse-montreal-3-et-demi` — 10150 rue Lajeunesse (Immo Marketing) — 3½ Ahuntsic
```json
{
 "version": 1,
 "texte_nettoye": "Promotion 2 mois gratuit sur certaines\nUNITÉS ! À louer – Charmant 3 ½ au cœur de Ahuntsic-Cartierville Découvrez ce 3 ½ lumineux et bien entretenu , situé dans un secteur recherché de Cartierville, à deux pas de la station de métro Sauvé (ligne orange). Parfait pour une personne seule ou un couple à la recherche d’un environnement urbain pratique, avec un accès facile aux services essentiels. Ce qui est inclus : Cuisinière et réfrigérateur Chauffage et eau chaude Service de buanderie dans l’immeuble Un emplacement de choix : À moins de 5 minutes à pied du métro Sauvé Épiceries, écoles et pharmacies à proximité Entouré de nombreux parcs et espaces verts , parfaits pour vos moments de détente ou vos activités de plein air Informations supplémentaires Non-fumeur Animaux non acceptés Enquête de crédit exigée Photos à titre indicatif Gestionnaire de l’immeuble Pour toute demande de visite ou information concernant l’immeuble, veuillez communiquer directement avec le gestionnaire : Guy : 438-373-7153 Sadrack : 514-998-8421 Il se fera un plaisir de vous répondre. N’attendez plus pour planifier votre visite! Ce logement allie confort, accessibilité et tranquillité dans un quartier en pleine vie. — 1 chambre(s), 1 salle(s) de bain.",
 "en_bref": "Chauffage et eau chaude inclus.",
 "sections": [
  {
   "titre": "Promotion 2 mois gratuit sur certaines",
   "texte": "UNITÉS ! À louer – Charmant 3 ½ au cœur de Ahuntsic-Cartierville Découvrez ce 3 ½ lumineux et bien entretenu , situé dans un secteur recherché de Cartierville, à deux pas de la station de métro Sauvé (ligne orange). Parfait pour une personne seule ou un couple à la recherche d’un environnement urbain pratique, avec un accès facile aux services essentiels. Ce qui est inclus : Cuisinière et réfrigérateur Chauffage et eau chaude Service de buanderie dans l’immeuble Un emplacement de choix : À moins de 5 minutes à pied du métro Sauvé Épiceries, écoles et pharmacies à proximité Entouré de nombreux parcs et espaces verts , parfaits pour vos moments de détente ou vos activités de plein air Informations supplémentaires Non-fumeur Animaux non acceptés Enquête de crédit exigée Photos à titre indicatif Gestionnaire de l’immeuble Pour toute demande de visite ou information concernant l’immeuble, veuillez communiquer directement avec le gestionnaire : Guy : 438-373-7153 Sadrack : 514-998-8421 Il se fera un plaisir de vous répondre. N’attendez plus pour planifier votre visite! Ce logement allie confort, accessibilité et tranquillité dans un quartier en pleine vie. — 1 chambre(s), 1 salle(s) de bain."
  }
 ],
 "faits": {
  "prix_mensuel": null,
  "date_disponibilite": null,
  "duree_bail_minimale_mois": null,
  "nb_occupants_total": null,
  "salle_de_bain": null,
  "cuisine": null,
  "electromenagers": [
   "frigo",
   "cuisiniere"
  ],
  "inclusions": [
   "chauffage",
   "eau_chaude"
  ],
  "contraintes": [
   "non_fumeur",
   "pas_d_animaux",
   "references_requises"
  ],
  "depot_mentionne": null,
  "quartier_mentionne": "Ahuntsic"
 },
 "confiance": {
  "electromenagers": "haute",
  "inclusions": "haute",
  "contraintes": "haute",
  "quartier_mentionne": "haute"
 },
 "incoherences": [],
 "completude": 45
}
```

### `progim:332233` — Progim 332233 — texte générique de gestionnaire
```json
{
 "version": 1,
 "texte_nettoye": "Situé dans le secteur paisible et recherché de Dorval, cet appartement bénéficie d’un emplacement idéal à proximité du bord de l’eau, de plusieurs parcs, commerces et services essentiels, tout en offrant un accès rapide aux autoroutes et au transport en commun. Il offre : • • • L’immeuble se trouve dans un environnement calme et résidentiel, parfait pour les familles, couples et professionnels recherchant une qualité de vie agréable à proximité du centre-ville et de l’aéroport. Points forts du secteur : • À proximité du bord de l’eau et du chemin du Bord-du-Lac-Lakeshore • Près des parcs Winds",
 "en_bref": null,
 "sections": [
  {
   "titre": "Description",
   "texte": "Situé dans le secteur paisible et recherché de Dorval, cet appartement bénéficie d’un emplacement idéal à proximité du bord de l’eau, de plusieurs parcs, commerces et services essentiels, tout en offrant un accès rapide aux autoroutes et au transport en commun. Il offre : • • • L’immeuble se trouve dans un environnement calme et résidentiel, parfait pour les familles, couples et professionnels recherchant une qualité de vie agréable à proximité du centre-ville et de l’aéroport. Points forts du secteur : • À proximité du bord de l’eau et du chemin du Bord-du-Lac-Lakeshore • Près des parcs Winds"
  }
 ],
 "faits": {
  "prix_mensuel": null,
  "date_disponibilite": null,
  "duree_bail_minimale_mois": null,
  "nb_occupants_total": null,
  "salle_de_bain": null,
  "cuisine": null,
  "electromenagers": [],
  "inclusions": [],
  "contraintes": [],
  "depot_mentionne": null,
  "quartier_mentionne": null
 },
 "confiance": {},
 "incoherences": [],
 "completude": 15
}
```

### `cogir:1522-3` — Cogir 1522-3 — texte de marque d'un projet locatif
```json
{
 "version": 1,
 "texte_nettoye": "Les condos Domo à louer dans le Vieux-Montréal proposent des unités élégantes avec électroménagers et services inclus. Profitez d'une boulangerie et du marché Aisle 24 directement dans votre immeuble. Les espaces communs somptueux comprennent une piscine sur le toit, une terrasse, un salon social ainsi qu'une salle de sport entièrement équipée. L'entrée sans clé et le stationnement souterrain, ainsi que les espaces de rangement et les supports à vélos, ajoutent un niveau supplémentaire de commodité.",
 "en_bref": null,
 "sections": [
  {
   "titre": "Description",
   "texte": "Profitez d'une boulangerie et du marché Aisle 24 directement dans votre immeuble."
  },
  {
   "titre": "L'espace de vie",
   "texte": "Les espaces communs somptueux comprennent une piscine sur le toit, une terrasse, un salon social ainsi qu'une salle de sport entièrement équipée."
  },
  {
   "titre": "Frais et conditions",
   "texte": "Les condos Domo à louer dans le Vieux-Montréal proposent des unités élégantes avec électroménagers et services inclus. L'entrée sans clé et le stationnement souterrain, ainsi que les espaces de rangement et les supports à vélos, ajoutent un niveau supplémentaire de commodité."
  }
 ],
 "faits": {
  "prix_mensuel": null,
  "date_disponibilite": null,
  "duree_bail_minimale_mois": null,
  "nb_occupants_total": null,
  "salle_de_bain": null,
  "cuisine": null,
  "electromenagers": [
   "frigo"
  ],
  "inclusions": [],
  "contraintes": [],
  "depot_mentionne": null,
  "quartier_mentionne": null
 },
 "confiance": {
  "electromenagers": "haute"
 },
 "incoherences": [],
 "completude": 15
}
```