# Format Lumenia.io & règles de parsing

Lumenia.io produit deux fichiers `.txt` par query, avec un préfixe `premium-` + un ID numérique. Le skill détecte ces fichiers automatiquement par `find <dir> -maxdepth 1 -name 'premium-*.txt'`.

## Fichier 1 — Guide top-terms (`premium-XXXXXXXX.txt`)

Format ligne-par-ligne avec sections délimitées par `== <NOM> ==`. Toujours UTF-8, ordre fixe.

### Structure

```
Lumenia.io SEO GUIDE
Query        : <query>
Language     : <language>     ← clé pour la langue de sortie
Search Engine: <engine>

== TOP TERMS ==
1. <terme>
2. <terme>
...
50. <terme>

== TWO GRAMS ==
1. <bigramme>
...
20. <bigramme>

== THREE GRAMS ==
1. <trigramme>
...
20. <trigramme>

== NAMED ENTITIES ==
1. <entity>
...
20. <entity>

© <year> Lumenia.io
```

### Règles de parsing

- **En-tête** : 4 premières lignes. Capturer `query`, `language`, `search_engine` via split sur `:` (lstrip + rstrip sur les valeurs).
- **Sections** : chaque section commence par `== NOM ==` (deux espaces de chaque côté du nom). Le parsing :
  1. Détecter la ligne `== TOP TERMS ==` → début section.
  2. Lire les lignes suivantes du format `<n>. <terme>` jusqu'à la prochaine `== ... ==` ou ligne vide.
  3. Extraire `<terme>` après le `<n>. ` (les chiffres ne sont pas significatifs, juste un index).
- **Quantités attendues** : 50 top terms, 20 two-grams, 20 three-grams, 20 named entities. Si l'un est < à l'attendu, signaler mais continuer (Lumenia tronque parfois).
- **Grammage cible** : ❌ pas dans ce fichier. Le grammage cible se calcule en Phase 2 à partir du MAX concurrent. Lumenia.io fournit parfois un grammage suggéré dans son interface web, mais pas dans les `.txt` exportés.

### Exemple parsé (fixture jewellery-manufacturing)

```yaml
query: jewellery manufacturing
language: English (USA)
search_engine: GOOGLE

top_terms:
  - jewellery
  - jewelers
  - jewelry
  - jeweler
  - chainmaking
  # ... 45 autres

two_grams:
  - jewellery making
  - jewellery designing
  # ... 18 autres

three_grams:
  - jewellery process production
  - jewellery making designing
  # ... 18 autres

named_entities:
  - MKM Jewelry
  - Liberty Jewelry
  - Bamina Jewelry
  - Rhodium Plating
  - Computer Aided Manufacture
  # ... 15 autres
```

## Fichier 2 — Brief (`premium-XXXXXXXX-brief.txt`)

Format texte semi-structuré avec sections délimitées par `=======================`. Plus libre que le guide.

### Structure

```
Lumenia.io SEO Brief
Query: <query>
Language: <language>
Year: <year>

=======================
Context and Objective
=======================
Primary Intent: <intent>
Objective:
  - <objectif 1>
  - <objectif 2>
  ...

=======================
Main Topics to Cover
=======================
Key Subjects:
  - <topic 1>
  - <topic 2>
  ...
Questions to consider:
  - <question 1>
  - <question 2>
  ...

=======================
Writing Style and Tone
=======================
Recommended Tone:
  - <ton 1>
  - <ton 2>
  ...
Recommended Style:
  - <règle de style 1>
  - <règle de style 2>
  ...

=======================
Value Proposition
=======================
  - <bullet value prop 1>
  - <bullet value prop 2>
  ...

---
Generated by Lumenia.io © <year>
```

### Règles de parsing

- **Sections** : détecter `=======================` (suite de `=`) comme délimiteur. La ligne juste après le délimiteur est le titre de la section.
- **Champs simples** : `Primary Intent:` et les en-têtes (`Query:`, `Language:`, `Year:`) ont une valeur inline après le `:`.
- **Listes à puces** : sections en `<nom>:` suivies de lignes commençant par `  - ` (2 espaces + tiret + espace). Extraire jusqu'à la prochaine clé `<nom>:` ou prochain délimiteur.
- **Cas spécial "Main Topics to Cover"** : contient DEUX sous-clés (`Key Subjects:` et `Questions to consider:`). Bien les séparer — `key_subjects` deviennent les H2/H3, `questions` deviennent les H3 de la FAQ.

### Exemple parsé (fixture jewellery-manufacturing)

```yaml
query: jewellery manufacturing
language: English (USA)
year: 2026

intent: Informational
objectives:
  - The objective of this content is to provide a comprehensive overview...
  - It aims to educate readers about the different methods...
  - The content will also highlight industry trends...
  - Ultimately, it will serve as a valuable resource...

key_subjects:
  - Overview of jewellery manufacturing processes and techniques
  - Materials commonly used in jewellery making
  - Modern technologies and innovations in jewellery manufacturing
  - Steps involved in starting a jewellery manufacturing business
  - Sustainability and ethical considerations in jewellery production

questions:
  - What are the main methods used in jewellery manufacturing?
  - Which materials are most commonly used in making jewellery?
  - How has technology impacted the jewellery manufacturing industry?
  - What are the steps to start a jewellery manufacturing business?
  - How can jewellery manufacturing be made more sustainable and ethical?

tone:
  - Informative
  - Professional
  - Engaging

style:
  - The writing should be clear, concise, and structured...
  - Use engaging language to maintain interest...
  - Break down technical terms and processes for easy understanding...

value_proposition:
  - This content provides readers with a thorough understanding...
  - It demystifies the processes involved...
  - By addressing common questions and highlighting important considerations...
  - Readers will gain practical knowledge and a deeper appreciation...
```

## Erreurs courantes à anticiper

- **Mauvais encodage** : si le fichier n'est pas UTF-8 (rare avec Lumenia, mais possible si l'utilisateur l'a passé par un éditeur exotique), forcer le `latin-1` en fallback et logger un warning.
- **Sections manquantes** : si une section attendue est absente (ex: pas de `Questions to consider:` dans le brief), signaler `⚠️ MISSING INPUT: brief section 'Questions to consider'`. Ne pas inventer de FAQ.
- **Noms anglais vs français** : Lumenia produit les briefs dans la langue de la query. Si la query est en FR, les en-têtes restent en EN mais le contenu est en FR. Le parser ne dépend que des en-têtes (toujours EN), pas du contenu.
- **Doublons dans top_terms** : Lumenia liste parfois "jewellery" et "jewelry" séparément (variantes orthographiques EN-UK / EN-US). C'est intentionnel — garder les deux et les intégrer en Phase 6 selon la langue cible.