DTLarchive — Manuel de référence v2.2-5
Référence fonctionnelle et technique du moteur local d'indexation, de recherche et de capitalisation des archives ChatGPT.
Préface
Ce manuel décrit la structure, les formats, les invariants et les interfaces internes de DTLarchive 2.2-5. Il constitue une référence d'architecture et de données. Il ne décrit volontairement ni parcours utilisateur, ni procédure de lancement, ni scénario pas à pas.
DTLarchive transforme des exports de conversations ChatGPT en un corpus local indexé. Son objectif est de rendre les connaissances contenues dans ces archives interrogeables, contextualisables et réutilisables par des traitements ultérieurs, sans dépendance à un service distant.
Audience visée
Le document s'adresse aux développeurs, mainteneurs, responsables de données et intégrateurs qui doivent comprendre le comportement du moteur, contrôler ses sorties ou raccorder ses résultats à d'autres outils de capitalisation des connaissances.
Principes structurants
- Localité : archives, requêtes, index et rapports restent sur l'ordinateur.
- Déterminisme : la sélection et le classement reposent sur des règles lexicales explicites.
- Traçabilité : chaque résultat conserve son fichier source, son identifiant et ses contextes.
- Incrémentalité : les sources inchangées ne sont pas réanalysées.
- Bilinguisme : l'interface et les sorties générées existent en français et en anglais.
- Absence d'IA externe : aucun modèle de langage, embedding ou service sémantique n'intervient dans l'analyse.
Architecture
Vue d'ensemble
L'architecture sépare l'importation persistante, la présélection par index plein texte et l'analyse exacte des conversations candidates. Cette séparation évite de relire et de recalculer l'ensemble du corpus à chaque recherche.
Composants
| Composant | Responsabilité |
|---|---|
| DTLarchive.py | Orchestration, lecture des exports, analyse lexicale, calcul de pertinence, génération des sorties et interface console. |
| dtlarchive_index.py | Schéma SQLite, import incrémental, déduplication, stockage des messages et interrogation FTS5. |
| dtlarchive_search.py | Façade de sélection des conversations candidates et comptage du corpus examiné. |
| dtlarchive_i18n.py | Catalogue FR/EN, langue active, interpolation et pluriels. |
| DTLarchive.spec | Description de construction de l'exécutable autonome. |
Chaîne de traitement
| Phase | Entrée | Sortie | Invariant |
|---|---|---|---|
| Résolution | Fichiers ou dossiers | Chemins absolus uniques | Ordre stable par chemin. |
| Importation | JSON ChatGPT | Sources, conversations, messages, FTS | Transaction par source. |
| Présélection | Termes, rôles, dates | Identifiants candidats | FTS réduit le corpus sans produire le résultat final. |
| Analyse | Conversations candidates | MiningResult | Vérification exacte des groupes et exclusions. |
| Publication | Résultats triés | JSON et HTML | Les messages archivés ne sont pas modifiés. |
Organisation des fichiers
Sources
DTLarchive.pydtlarchive_index.pydtlarchive_search.pydtlarchive_i18n.pyImplémentation du moteur, de l'index, de la sélection et du catalogue linguistique.
Données persistantes
DTLarchive-index.sqliteBase locale regroupant empreintes, provenance, conversations, messages et index FTS5.
Sorties
DTLarchive-output/logs/Résultats structurés, rapport principal, copies HTML des conversations et journal de diagnostic.
Données et index
Format source ChatGPT
Le lecteur accepte un tableau de conversations ou un objet conversation unique. Chaque conversation exploitable possède un dictionnaire mapping. La branche courante est reconstruite en remontant depuis current_node par les relations parent, puis inversée pour restituer l'ordre chronologique.
Seuls les messages dont le rôle vaut user ou assistant et dont le contenu textuel n'est pas vide sont conservés. Le texte provient de content.parts ou, à défaut, de content.text. Si la branche courante ne produit aucun message, un parcours de repli trie les messages exploitables par date.
Modèles internes
| Type | Champs | Rôle |
|---|---|---|
| Message | id, role, text, create_time | Message extrait d'une conversation. |
| Conversation | source_file, id, title, create_time, update_time, messages | Unité d'analyse complète. |
| QueryTerm | text, excluded, group | Terme lexical et appartenance à un groupe alternatif. |
| MiningResult | source, identifiants, date, mots-clés, compteurs, score, rôles, contextes, URL | Résultat sérialisable et affichable. |
| IndexUpdate | imported_files, unchanged_files, imported_conversations | Bilan d'une synchronisation de l'index. |
| SearchSelection | conversations, examined_count, candidate_count | Résultat de présélection avant analyse exacte. |
Schéma SQLite
| Objet | Clé | Contenu |
|---|---|---|
| metadata | key | Version du schéma de l'index. |
| sources | id / path unique | Taille, date de modification, SHA-256 et date d'indexation. |
| conversations | id | Titre, dates, horodatage de contenu et nombre de messages. |
| messages | id / conversation + ordinal | Identifiant externe, rôle, date et texte dans l'ordre original. |
| source_conversations | source + conversation | Relation plusieurs-à-plusieurs de provenance. |
| search_fts | FTS5 | Identifiant, rôle et texte indexé avec unicode61 remove_diacritics 2. |
Les clés étrangères sont actives et le journal SQLite utilise le mode WAL. Les index relationnels portent sur l'ordre des messages et les dates de conversation.
Importation incrémentale et déduplication
Une source est considérée inchangée lorsque sa taille et son horodatage correspondent à l'état mémorisé. Si ces métadonnées diffèrent mais que l'empreinte SHA-256 reste identique, seules les métadonnées sont actualisées. Une source réellement modifiée est relue dans une transaction.
L'identifiant ChatGPT constitue la clé de déduplication. En son absence, un SHA-256 déterministe est calculé à partir du chemin, du titre et des dates. Lorsqu'une conversation existe déjà, son contenu est remplacé si le couple (horodatage de contenu, nombre de messages) de la version entrante est supérieur ou égal à celui enregistré. Les relations de provenance permettent à une même conversation d'appartenir à plusieurs exports.
Moteur de recherche
Grammaire lexicale
| Construction | Sémantique interne |
|---|---|
| virgule, point-virgule, OU, OR | Création de groupes alternatifs. |
| ET, AND | Conjonction de tous les termes d'un groupe. |
| -terme | Exclusion globale de la conversation. |
| "expression" | Suppression des guillemets externes et conservation de l'expression. |
| préfixe* | Extension lexicale par caractères alphanumériques, tiret ou souligné. |
Les doublons sont éliminés par texte normalisé, statut d'exclusion et numéro de groupe.
Normalisation et comptage
La normalisation applique Unicode NFKD, supprime les diacritiques, convertit en minuscules, remplace l'apostrophe typographique et compacte les espaces. Les recherches sont donc insensibles à la casse et aux accents. Hors joker, les formes simples acceptent un suffixe pluriel s ou x, sauf lorsque le terme se termine déjà par l'un de ces caractères.
Présélection indexée
Pour chaque terme positif, FTS5 produit un ensemble d'identifiants limité aux sources, rôles et dates retenus. Les termes d'un même groupe sont intersectés ; les groupes alternatifs sont réunis. Le rôle title est toujours ajouté au périmètre. Cette phase produit des candidats et non des résultats définitifs.
Analyse exacte
Le titre et les messages appartenant au périmètre sont réunis puis normalisés. Toute occurrence d'un terme exclu élimine la conversation. Un groupe positif est validé uniquement si chacun de ses termes possède au moins une occurrence. Les comptes, rôles correspondants et positions des messages sont ensuite calculés sur le texte exact.
Calcul de pertinence
Le score est plafonné à 100 et suit la formule déterministe ci-dessous :
| Intervalle | Libellé |
|---|---|
| 80 à 100 | Très pertinent |
| 45 à 79 | Pertinent |
| 0 à 44 | Mention secondaire |
Le tri final est décroissant sur le score, puis sur la date de conversation. Il ne représente pas une probabilité et ne résulte d'aucun apprentissage statistique.
Fenêtres de contexte
Chaque message correspondant génère une fenêtre allant jusqu'à deux messages avant et deux après. Les fenêtres adjacentes ou chevauchantes sont fusionnées. Six fenêtres au maximum sont conservées par conversation. Le texte de chaque message de contexte est compacté à 1 200 caractères.
Sorties structurées
mining_results.json
Le document racine contient metadata et results. Les métadonnées décrivent l'application, la version, le schéma logique, l'heure UTC, les sources, l'index, les dates, la requête et le périmètre. Chaque résultat est la sérialisation complète d'un MiningResult.
| Famille | Champs principaux |
|---|---|
| Identification | source_file, conversation_id, conversation_title, conversation_url |
| Mesures | occurrence_count, message_count, relevance_score, relevance_label |
| Correspondances | matched_keywords, matched_roles, contexts |
| Contexte de traitement | source_files, index_path, période, recherche, role_scope |
Rapports HTML
DTLarchive-report.html présente les métriques, la répartition des termes, les premiers titres de conversations classées, le tableau des résultats et les fenêtres de contexte. Les titres affichés ne sont pas une synthèse sémantique. Chaque page conversation-<empreinte>.html reproduit la branche complète et positionne une ancre sur le premier message correspondant.
Les documents sont autonomes en CSS, encodés en UTF-8 et localisés selon la langue active. Le contenu des conversations reste dans sa langue originale.
Journal HTML
Le journal quotidien logs/DTLarchive_AAAAMMJJ.html reçoit des entrées horodatées de niveau information, action ou erreur. Il mémorise les grandes phases, les paramètres synthétiques, les compteurs d'importation et les exceptions. Une impossibilité d'écriture du journal n'interrompt pas le moteur.
Référence interne
Modules publics du projet
| Module | Dépendances principales | État détenu |
|---|---|---|
| DTLarchive | argparse, pathlib, sqlite3, tkinter, webbrowser | Langue de processus, arguments, corpus sélectionné et résultats. |
| dtlarchive_index | sqlite3, hashlib | Connexion SQLite et schéma persistant. |
| dtlarchive_search | ArchiveIndex | Sources autorisées pour une sélection. |
| dtlarchive_i18n | os.environ | Catalogue et variable DTLARCHIVE_LANG. |
Groupes de fonctions
| Groupe | Fonctions représentatives | Contrat |
|---|---|---|
| Texte | normalize, compact, unique, keyword_pattern, count_term | Normalisation et mesure lexicale déterministes. |
| Lecture | text_from_content, current_branch_messages, iter_conversations | Conversion tolérante du JSON ChatGPT vers les modèles internes. |
| Temps | parse_french_date, period_overlaps_archive, archive_period_label | Bornes inclusives et validation de recouvrement. |
| Analyse | mine_conversation, build_contexts, relevance_label | Production d'un résultat exact ou de None. |
| Publication | write_json, write_html_report, write_conversation_page | Écriture UTF-8 des sorties structurées et navigables. |
Internationalisation
Le catalogue TRANSLATIONS associe chaque clé à une valeur fr et en. current_language() lit DTLARCHIVE_LANG et revient au français si la valeur n'est pas prise en charge. t() sélectionne puis interpole le modèle ; plural_key() choisit les variantes singulière et plurielle.
La langue couvre la console, les boîtes de dialogue, l'aide, les erreurs, les rapports et le journal. Elle ne traduit pas le contenu source des conversations.
Erreurs, transactions et intégrité
- Une archive illisible peut être ignorée en mode tolérant ou provoquer une erreur en mode strict.
- L'importation d'une source modifiée est transactionnelle ; un échec de lecture préserve le contenu indexé antérieur.
- Une version d'index incompatible déclenche une erreur explicite avant toute recherche.
- Les périodes invalides, inversées ou hors corpus sont rejetées avant l'analyse.
- Les textes HTML sont échappés avant insertion dans les rapports.
- Les pages et fichiers JSON utilisent UTF-8 ; la console Windows est configurée en page de codes 65001.
Annexes
Limites connues
- La recherche est lexicale ; elle ne détecte ni synonymes, ni paraphrases, ni proximité sémantique.
- La présélection FTS utilise le premier jeton significatif d'une expression, puis l'analyse exacte confirme l'expression complète.
- Les titres présentés dans le résumé sont les cinq premiers titres uniques du classement, pas les sujets déduits du corpus.
- Seule la branche courante de chaque conversation est privilégiée ; le parcours de repli n'est utilisé qu'en l'absence de messages exploitables.
- Les contextes sont limités à six fenêtres et les messages y sont tronqués à 1 200 caractères.
- Le format source dépend de la structure des exports ChatGPT observée ; une évolution de ce format peut nécessiter une adaptation du lecteur.
Versions et schémas
| Identifiant | Valeur | Portée |
|---|---|---|
| Application | v2.2-5 | Fonctionnalités et interface distribuées. |
| Schéma logique | 2.1 | Valeur publiée dans les métadonnées de résultat. |
| Schéma d'index | 1 | Compatibilité de la base SQLite persistante. |
Glossaire
| Terme | Définition |
|---|---|
| Corpus | Ensemble des conversations rattachées aux archives sélectionnées. |
| Candidate | Conversation retenue par FTS5 avant validation lexicale exacte. |
| Contexte | Fenêtre de messages entourant une correspondance. |
| Provenance | Relation entre une conversation dédupliquée et ses fichiers sources. |
| FTS5 | Moteur de recherche plein texte intégré à SQLite. |
| WAL | Mode de journalisation SQLite favorisant robustesse et concurrence de lecture. |