frontend/help_page.py

"""
Page d'aide détaillée
"""

import streamlit as st


def render_help_page():
    """Affiche la page d'aide complète"""

    st.title("Guide d'utilisation")
    st.markdown("Tout ce que vous devez savoir pour utiliser l'application de scoring de feedbacks")

    st.markdown("---")

    # Section 1: Introduction
    st.markdown("## Objectif de l'application")
    st.markdown("""
    Cette application permet de **noter la qualité des feedbacks** générés pour des snippets de code.
    Vous allez évaluer si les feedbacks sont utiles, pertinents et bien formulés.

    **Échelle de notation : 0 à 5**
    - **0** : Pas utile / Incorrect
    - **1** : Très peu utile
    - **2** : Peu utile
    - **3** : Moyennement utile
    - **4** : Utile
    - **5** : Extrêmement utile
    """)

    st.markdown("---")

    # Section 2: Charger un dataset
    st.markdown("## Charger un dataset")

    col1, col2 = st.columns(2)

    with col1:
        st.markdown("### Option 1 : Fichier local")
        st.markdown("""
        1. Cliquez sur **"Choisissez une option: Fichier local (.jsonl)"**
        2. Cliquez sur **"Browse files"**
        3. Sélectionnez votre fichier `.jsonl`
        4. Cliquez sur **"Charger le fichier"**

        **Format attendu du JSONL :**
        ```json
        {"anchor": "code...", "positive": "feedback..."}
        {"anchor": "code...", "positive": "feedback..."}
        ```

         Chaque ligne doit contenir au minimum :
        - `anchor` ou `code` : le code source
        - `positive` : le feedback à évaluer
        """)

    with col2:
        st.markdown("### Option 2 : HuggingFace Hub")
        st.markdown("""
        1. Cliquez sur **"Choisissez une option: HuggingFace Hub"**
        2. Entrez le nom du dataset (ex: `username/dataset-name`)
        3. Choisissez le split (généralement `train`)
        4. Cliquez sur **" Charger depuis HF"**

        **Exemples de datasets :**
        - `username/my-feedback-dataset`
        - `organization/code-feedbacks-v1`

         Le dataset doit être public ou vous devez être authentifié
        """)

    st.markdown("---")

    # Section 3: Navigation
    st.markdown("## Navigation entre les exemples")

    st.markdown("""
    ### Boutons de navigation
    - **< Précédent** : Revenir à l'exemple précédent
    - **Suivant >** : Passer à l'exemple suivant
    - **Compteur central** : Affiche votre position (ex: "Exemple 5 / 100")

    ### Navigation rapide
    - **Aller au prochain non-scoré** : Saute directement au prochain exemple sans score
    - **Aller à l'exemple N** : Entrez un numéro et cliquez sur "Aller" pour y accéder directement

     **Astuce** : Utilisez les boutons Précédent/Suivant pour naviguer rapidement
    """)

    st.markdown("---")

    # Section 4: Scoring
    st.markdown("##  Noter un feedback")

    st.markdown("""
    ### 1. Lisez le code
    Le code source s'affiche en haut avec coloration syntaxique.

    ### 2. Lisez le feedback
    Le feedback à évaluer s'affiche dans un encadré vert.

    ### 3. Attribuez un score
    Déplacez le **slider de 0 à 5** selon votre évaluation :

    | Score | Signification | Quand l'utiliser |
    |-------|---------------|------------------|
    | **0** | Pas utile / Incorrect | Le feedback est faux, inutile ou hors sujet |
    | **1** | Très peu utile | Le feedback est vague ou très générique |
    | **2** | Peu utile | Le feedback manque de précision ou de profondeur |
    | **3** | Moyennement utile | Le feedback est correct mais sans détails |
    | **4** | Utile | Le feedback est pertinent et bien expliqué |
    | **5** | Extrêmement utile | Le feedback est excellent, précis et actionnable |

    ### 4. Ajoutez un commentaire (optionnel)
    Cliquez sur **"Ajouter un commentaire"** pour justifier votre score.
    Utile pour :
    - Expliquer un score particulier
    - Noter des détails spécifiques
    - Documenter votre raisonnement
    """)

    st.markdown("---")

    # Section 5: Progression
    st.markdown("##  Suivre votre progression")

    st.markdown("""
    ### Métriques en temps réel
    - **Total** : Nombre total d'exemples dans le dataset
    - **Scorés** : Nombre d'exemples que vous avez notés
    - **Restants** : Nombre d'exemples non scorés
    - **Progression** : Pourcentage d'avancement

    ### Barre de progression
    Une barre visuelle vous montre votre avancement global.

    ### Statistiques des scores
    Quand vous avez noté au moins un exemple, vous verrez :
    - **Score moyen** : Moyenne de tous vos scores
    - **Score le plus fréquent** : Le score que vous utilisez le plus
    - **Graphique de distribution** : Répartition de vos scores

     Ces statistiques vous aident à voir si vous êtes cohérent dans vos notations
    """)

    st.markdown("---")

    # Section 6: Export
    st.markdown("##  Exporter vos scores")

    st.markdown("""
    ### Quand exporter ?
    - À la fin de votre session de notation
    - Régulièrement pour sauvegarder votre travail
    - Quand vous voulez partager vos résultats

    ### Comment exporter ?
    1. Scrollez jusqu'à la section **"Export"**
    2. Vérifiez le nombre d'items à exporter
    3. Cliquez sur **"Télécharger JSONL"**
    4. Le fichier sera téléchargé : `feedback_scores.jsonl`

    ### Format du fichier exporté
    ```json
    {
      "code": "code source...",
      "feedback": "le feedback évalué...",
      "score": 4,
      "comment": "votre commentaire...",
      "original_index": 42
    }
    ```

    ### Aperçu de l'export
    Cliquez sur **"Aperçu Export (5 premiers)"** pour voir à quoi ressemblera votre fichier.

     **Important** : Les scores sont automatiquement enregistrés, mais téléchargez régulièrement votre fichier JSONL !
    """)

    st.markdown("---")

    # Section 7: Actions avancées
    st.markdown("## Actions avancées")

    st.markdown("""
    ### Réinitialiser tous les scores
    **Attention** : Cette action supprime TOUS vos scores !
    1. Cliquez sur **"Réinitialiser tous les scores"**
    2. Un avertissement apparaît
    3. Cliquez à nouveau pour confirmer

    Pensez à exporter avant de réinitialiser !

    ### Modifier un score existant
    Vous pouvez revenir sur un exemple déjà noté et changer le score.
    Le nouveau score remplacera automatiquement l'ancien.
    """)

    st.markdown("---")

    # Section 8: Bonnes pratiques
    st.markdown("## ✅ Bonnes pratiques")

    col1, col2 = st.columns(2)

    with col1:
        st.markdown("""
        ### Pour une notation cohérente
        - Lisez d'abord plusieurs exemples avant de commencer
        - Définissez vos critères de notation
        - Utilisez les commentaires pour les cas limites
        - Relisez régulièrement vos premiers scores
        - Vérifiez votre distribution de scores
        """)

    with col2:
        st.markdown("""
        ### Pour éviter les erreurs
        - Exportez régulièrement (toutes les 50 notations)
        - N'utilisez pas "Réinitialiser" par erreur
        - Lisez bien le code ET le feedback
        - Faites des pauses régulières
        - En cas de doute, mettez 3 et commentez
        """)

    st.markdown("---")

    # Section 9: FAQ
    st.markdown("## Questions fréquentes")

    with st.expander("Mes scores sont-ils sauvegardés automatiquement ?"):
        st.markdown("""
        **Oui !** Chaque score est enregistré dès que vous bougez le slider.

        Cependant, ils sont stockés temporairement dans l'application.
        **Pensez à télécharger votre fichier JSONL** régulièrement pour ne pas perdre votre travail.
        """)

    with st.expander("Puis-je fermer l'application et revenir plus tard ?"):
        st.markdown("""
        **Attention** : Si vous fermez le navigateur ou redémarrez Docker, vos scores seront perdus.

        **Solution** : Téléchargez votre fichier JSONL avant de fermer, et rechargez-le à votre retour.
        """)

    with st.expander("Comment gérer les feedbacks ambigus ?"):
        st.markdown("""
        Pour les feedbacks difficiles à évaluer :
        1. Mettez un score **3** (moyennement utile)
        2. Ajoutez un **commentaire** expliquant pourquoi c'est ambigu
        3. Continuez et revenez-y plus tard si besoin
        """)

    with st.expander("Que faire si un feedback est partiellement correct ?"):
        st.markdown("""
        Utilisez l'échelle graduée :
        - Partiellement incorrect → **1-2**
        - Partiellement utile → **2-3**
        - Majoritairement utile avec petits défauts → **3-4**

        Le score **3** est parfait pour "c'est correct mais sans plus".
        """)

    with st.expander("Le dataset ne se charge pas ?"):
        st.markdown("""
        Vérifiez :
        - Le fichier est bien au format `.jsonl`
        - Chaque ligne contient `{"anchor": "...", "positive": "..."}`
        - Le fichier n'est pas corrompu
        - Pour HuggingFace : le dataset existe et est accessible
        """)

    with st.expander("Comment partager mes résultats ?"):
        st.markdown("""
        1. Téléchargez votre fichier JSONL
        2. Envoyez-le par email, Slack, Drive, etc.
        3. Le fichier contient tous vos scores et commentaires

        Le fichier est lisible et peut être rechargé dans l'application.
        """)

    st.markdown("---")

    # Section 10: Raccourcis
    st.markdown("## ⌨Raccourcis et astuces")

    st.markdown("""
    ### Navigation rapide
    - Utilisez **Tab** pour naviguer entre les boutons
    - **Espace** ou **Entrée** pour cliquer sur un bouton
    - Cliquez directement sur le slider pour changer le score rapidement

    ### Workflow efficace
    1. **Première passe** : Notez rapidement tous les exemples évidents
    2. **Deuxième passe** : Revenez sur les cas ambigus avec "Aller au prochain non-scoré"
    3. **Révision** : Vérifiez vos statistiques et ajustez si besoin
    4. **Export** : Téléchargez votre travail

    ### Organisation
    - Notez par sessions de 20-50 exemples
    - Exportez à chaque fin de session
    - Nommez vos exports : `scores_session1.jsonl`, `scores_session2.jsonl`
    """)

    st.markdown("---")

    st.success("Vous êtes maintenant prêt à noter des feedbacks efficacement !")
    st.caption("Pour toute question, consultez cette page d'aide ou contactez matis.codjia@epita.fr")