llm-pig 0.1.0__tar.gz

llm_pig-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: llm-pig
+Version: 0.1.0
+Summary: A Python library to visualize LLM perplexity metrics in interactive graphs
+Author: Juan Morysson Viana Marciano
+Author-email: juanmorysson@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pandas (>=2.0.0)
+Requires-Dist: plotly (>=5.0.0)
+Description-Content-Type: text/markdown
+
+# llm-pig 🐷
+
+`llm-pig` is a comprehensive Python library designed for advanced LLM perplexity analysis, covering both token-level micro inspection and macro-level dataset evaluation. It provides clean, interactive HTML visualizations powered by Pandas and Plotly.
+
+---
+
+## Features
+
+* **Token-Level Curve Analysis**: Interactive line charts tracking token uncertainty across a prompt or document.
+* **Cascading Bar Charts**: Sorted bar representations highlighting peak perplexity tokens.
+* **SHAP-Style Text Highlights**: Individual and comparative multi-model text highlights using dynamic color gradient scales.
+* **Macro Statistical Distribution**: Comprehensive Boxplots and Violin Plots summarizing model performance across large test datasets (including Min, Q1, Median, Q3, and Max metrics).
+
+---
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install llm-pig

llm_pig-0.1.0/README.md

@@ -0,0 +1,21 @@
+# llm-pig 🐷
+
+`llm-pig` is a comprehensive Python library designed for advanced LLM perplexity analysis, covering both token-level micro inspection and macro-level dataset evaluation. It provides clean, interactive HTML visualizations powered by Pandas and Plotly.
+
+---
+
+## Features
+
+* **Token-Level Curve Analysis**: Interactive line charts tracking token uncertainty across a prompt or document.
+* **Cascading Bar Charts**: Sorted bar representations highlighting peak perplexity tokens.
+* **SHAP-Style Text Highlights**: Individual and comparative multi-model text highlights using dynamic color gradient scales.
+* **Macro Statistical Distribution**: Comprehensive Boxplots and Violin Plots summarizing model performance across large test datasets (including Min, Q1, Median, Q3, and Max metrics).
+
+---
+
+## Installation
+
+Install the package via pip:
+
+```bash
+pip install llm-pig

llm_pig-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[tool.poetry]
+name = "llm-pig"
+version = "0.1.0"
+description = "A Python library to visualize LLM perplexity metrics in interactive graphs"
+authors = ["Juan Morysson Viana Marciano <juanmorysson@gmail.com>"]
+readme = "README.md"
+packages = [{include = "llm_pig", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+plotly = ">=5.0.0"
+pandas = ">=2.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.1.1,<10.0.0)"
+]

llm_pig-0.1.0/src/llm_pig/__init__.py

@@ -0,0 +1,4 @@
+from .parser import PerplexityParser
+from .plots import PerplexityVisualizer
+
+__all__ = ["PerplexityParser", "PerplexityVisualizer"]

llm_pig-0.1.0/src/llm_pig/parser.py

@@ -0,0 +1,13 @@
+import pandas as pd
+
+class PerplexityParser:
+    def __init__(self, tokens: list, perplexities: list):
+        if len(tokens) != len(perplexities):
+            raise ValueError("A lista de tokens e a lista de perplexidades devem ter o mesmo tamanho.")
+        self.df = pd.DataFrame({
+            "token": tokens,
+            "perplexity": perplexities
+        })
+
+    def get_dataframe(self) -> pd.DataFrame:
+        return self.df

llm_pig-0.1.0/src/llm_pig/plots - Copia.py

@@ -0,0 +1,558 @@
+import plotly.express as px
+from .parser import PerplexityParser
+
+class PerplexityVisualizer:
+    def __init__(self, parser: PerplexityParser):
+        self.df = parser.get_dataframe()
+
+    def plot_token_curve(self, save_path: str = "perplexity_curve.html", x_axis: str = "index", tick_angle: int = 0):
+        """
+        Gera um gráfico de linha interativo da perplexidade por token.
+        
+        Parâmetros:
+        - save_path (str): Caminho para salvar o arquivo HTML gerado.
+        - x_axis (str): Define o que aparece no eixo X ('index' ou 'token').
+        - tick_angle (int): Ângulo de rotação dos rótulos do eixo X (ex: 0 para normal, 90 para vertical).
+        """
+        if x_axis not in ["index", "token"]:
+            raise ValueError("O parâmetro 'x_axis' deve ser 'index' ou 'token'.")
+
+        x_data = self.df.index if x_axis == "index" else self.df["token"]
+
+        fig = px.line(
+            self.df,
+            x=x_data,
+            y="perplexity",
+            hover_data=["token"],
+            markers=True,
+            title="LLM Perplexity Curve by Token",
+            labels={"x": "Token Position" if x_axis == "index" else "Token", "perplexity": "Perplexity"}
+        )
+        
+        fig.update_traces(
+            hovertemplate="<b>Token:</b> %{customdata[0]}<br><b>Perplexity:</b> %{y:.2f}<extra></extra>"
+        )
+        
+        fig.update_layout(xaxis=dict(tickangle=tick_angle))
+        
+        fig.write_html(save_path)
+        print(f"Interactive chart successfully saved to: {save_path}")
+        return fig
+
+    def plot_token_bars(self, save_path: str = "perplexity_bars.html", top_n: int = None, cascade: bool = True):
+        """
+        Gera um gráfico de barras horizontais com os tokens no eixo Y e valores exibidos nas barras.
+        
+        Parâmetros:
+        - save_path (str): Caminho para salvar o arquivo HTML gerado.
+        - top_n (int, opcional): Limita a quantidade de tokens exibidos.
+        - cascade (bool): Se True (padrão), ordena do maior para o menor (maior perplexidade no topo).
+        """
+        df_plot = self.df.copy()
+
+        if cascade:
+            df_plot = df_plot.sort_values(by="perplexity", ascending=True)
+        
+        if top_n is not None:
+            if cascade:
+                df_plot = df_plot.tail(top_n)
+            else:
+                df_plot = df_plot.head(top_n)
+
+        fig = px.bar(
+            df_plot,
+            x="perplexity",
+            y="token",
+            orientation="h",
+            text="perplexity", # Define a coluna que terá o valor exibido na barra
+            title="LLM Perplexity by Token (Bar Chart)",
+            labels={"perplexity": "Perplexity", "token": "Token"}
+        )
+
+        # Formata o texto para exibir duas casas decimais e posiciona o texto dentro/ao lado da barra
+        fig.update_traces(
+            texttemplate='%{text:.2f}',
+            textposition='inside',
+            hovertemplate="<b>Token:</b> %{y}<br><b>Perplexity:</b> %{x:.2f}<extra></extra>"
+        )
+
+        fig.write_html(save_path)
+        print(f"Interactive bar chart successfully saved to: {save_path}")
+        return fig
+
+    def perplexity_text(self, save_path: str = "perplexity_text.html", top_n: int = None):
+        """
+        Gera uma visualização em texto destacado (tipo SHAP) onde o degradê 
+        e a legenda são recalculados com base apenas nos tokens destacados pelo filtro.
+        """
+        df = self.df.copy()
+        
+        # Identifica os tokens que entram no top_n
+        if top_n is not None and top_n < len(df):
+            df_filtered = df.nlargest(top_n, "perplexity")
+            top_indices = df_filtered.index
+        else:
+            df_filtered = df
+            top_indices = df.index
+
+        # Recalcula min e max baseados estritamente nos itens que receberão o destaque
+        min_p = df_filtered["perplexity"].min()
+        max_p = df_filtered["perplexity"].max()
+
+        def get_color_and_text_color(val, is_highlighted):
+            if not is_highlighted:
+                return "transparent", "#333333", False
+                
+            if max_p == min_p:
+                norm_val = 0.5
+            else:
+                # Normaliza usando o novo limite inferior do filtro
+                norm_val = (val - min_p) / (max_p - min_p)
+
+            r = int(255 - norm_val * (255 - 128))
+            g = int(192 - norm_val * 192)
+            b = int(203 - norm_val * (203 - 32))
+            alpha = 0.3 + (norm_val * 0.7)
+            bg_color = f"rgba({r}, {g}, {b}, {alpha})"
+            text_color = "#ffffff" if norm_val > 0.5 else "#333333"
+            
+            return bg_color, text_color, True
+
+        spans = []
+        for idx, row in df.iterrows():
+            token = row["token"]
+            p_val = row["perplexity"]
+            is_hl = idx in top_indices
+            
+            bg_color, text_color, highlighted = get_color_and_text_color(p_val, is_hl)
+            safe_token = token.replace("\n", "<br>")
+            
+            if highlighted:
+                span_html = (
+                    f'<span style="background-color: {bg_color}; color: {text_color}; '
+                    f'padding: 3px 6px; margin: 2px; border-radius: 4px; display: inline-block; '
+                    f'font-weight: 500;" title="Perplexity: {p_val:.2f}">{safe_token}</span>'
+                )
+            else:
+                span_html = (
+                    f'<span style="background-color: transparent; color: {text_color}; '
+                    f'padding: 3px 6px; margin: 2px; display: inline-block;" '
+                    f'title="Perplexity: {p_val:.2f} (Not in Top {top_n})">{safe_token}</span>'
+                )
+            spans.append(span_html)
+
+        legend_start = "rgba(255, 192, 203, 0.3)"
+        legend_end = "rgba(128, 0, 32, 1.0)"
+
+        html_content = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="utf-8">
+            <title>LLM Perplexity Text Highlight</title>
+            <style>
+                body {{
+                    font-family: Arial, sans-serif;
+                    margin: 40px;
+                    background-color: #f9f9f9;
+                    color: #333;
+                }}
+                .container {{
+                    background: #fff;
+                    padding: 25px;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+                    line-height: 2.5;
+                    font-size: 18px;
+                }}
+                h2 {{
+                    margin-bottom: 20px;
+                }}
+                .legend-container {{
+                    margin-top: 25px;
+                    display: flex;
+                    align-items: center;
+                    gap: 15px;
+                    font-size: 14px;
+                    color: #555;
+                }}
+                .legend-bar {{
+                    width: 200px;
+                    height: 14px;
+                    border-radius: 4px;
+                    background: linear-gradient(to right, {legend_start}, {legend_end});
+                    border: 1px solid #ddd;
+                }}
+            </style>
+        </head>
+        <body>
+            <h2>LLM Perplexity Text Highlight (Top {top_n if top_n else 'All'} Tokens)</h2>
+            <div class="container">
+                {"".join(spans)}
+                
+                <div class="legend-container">
+                    <span>Low ({min_p:.2f})</span>
+                    <div class="legend-bar"></div>
+                    <span>High ({max_p:.2f})</span>
+                </div>
+            </div>
+        </body>
+        </html>
+        """
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            f.write(html_content)
+
+        print(f"Text highlight visualization with recalculated legend successfully saved to: {save_path}")
+
+    def compare_perplexity_texts(
+        self, 
+        save_path: str = "perplexity_comparison.html", 
+        tokens: list[list[str]] = None, 
+        perplexities: list[list[float]] = None, 
+        labels: list[str] = None, 
+        top_n: int = None
+    ):
+        """
+        Gera uma visualização comparativa em texto destacado utilizando escala de cores 
+        global e uma única legenda unificada no rodapé.
+        """
+        if not tokens or not perplexities or len(tokens) != len(perplexities):
+            raise ValueError("As listas 'tokens' e 'perplexities' devem ser fornecidas e ter o mesmo comprimento.")
+
+        if labels is None:
+            labels = [f"Model {i+1}" for i in range(len(tokens))]
+
+        if len(tokens) != len(labels):
+            raise ValueError("A quantidade de listas de tokens deve ser igual à quantidade de 'labels'.")
+
+        import pandas as pd
+
+        models_dfs = []
+        all_highlighted_perplexities = []
+
+        # Passo 1: Processa cada modelo e coleta os valores destacados globalmente
+        for model_tokens, model_perps, label in zip(tokens, perplexities, labels):
+            if len(model_tokens) != len(model_perps):
+                raise ValueError(f"As listas de tokens e perplexidades do modelo '{label}' devem ter o mesmo tamanho.")
+
+            df = pd.DataFrame({"token": model_tokens, "perplexity": model_perps})
+            
+            if top_n is not None and top_n < len(df):
+                df_filtered = df.nlargest(top_n, "perplexity")
+                top_indices = set(df_filtered.index)
+            else:
+                top_indices = set(df.index)
+                df_filtered = df
+
+            models_dfs.append({"df": df, "top_indices": top_indices, "label": label})
+            
+            if not df_filtered.empty:
+                all_highlighted_perplexities.extend(df_filtered["perplexity"].tolist())
+
+        # Passo 2: Determina o Mínimo e Máximo global entre todos os tokens destacados
+        if all_highlighted_perplexities:
+            global_min_p = min(all_highlighted_perplexities)
+            global_max_p = max(all_highlighted_perplexities)
+        else:
+            global_min_p = 0.0
+            global_max_p = 1.0
+
+        def get_color_and_text_color(val, is_highlighted):
+            if not is_highlighted:
+                return "transparent", "#333333", False
+                
+            if global_max_p == global_min_p:
+                norm_val = 0.5
+            else:
+                norm_val = (val - global_min_p) / (global_max_p - global_min_p)
+                norm_val = max(0.0, min(1.0, norm_val))
+
+            r = int(255 - norm_val * (255 - 128))
+            g = int(192 - norm_val * 192)
+            b = int(203 - norm_val * (203 - 32))
+            alpha = 0.3 + (norm_val * 0.7)
+            bg_color = f"rgba({r}, {g}, {b}, {alpha})"
+            text_color = "#ffffff" if norm_val > 0.5 else "#333333"
+            
+            return bg_color, text_color, True
+
+        sections_html = []
+
+        # Passo 3: Constrói o HTML de cada seção de texto
+        for item in models_dfs:
+            df = item["df"]
+            top_indices = item["top_indices"]
+            label = item["label"]
+
+            spans = []
+            for idx, row in df.iterrows():
+                token = row["token"]
+                p_val = row["perplexity"]
+                is_hl = idx in top_indices
+                
+                bg_color, text_color, highlighted = get_color_and_text_color(p_val, is_hl)
+                safe_token = token.replace("\n", "<br>")
+                
+                if highlighted:
+                    span_html = (
+                        f'<span style="background-color: {bg_color}; color: {text_color}; '
+                        f'padding: 3px 6px; margin: 2px; border-radius: 4px; display: inline-block; '
+                        f'font-weight: 500;" title="Perplexity: {p_val:.2f}">{safe_token}</span>'
+                    )
+                else:
+                    span_html = (
+                        f'<span style="background-color: transparent; color: {text_color}; '
+                        f'padding: 3px 6px; margin: 2px; display: inline-block;" '
+                        f'title="Perplexity: {p_val:.2f} (Not in Top {top_n})">{safe_token}</span>'
+                    )
+                spans.append(span_html)
+
+            section_content = f"""
+            <div class="model-section">
+                <h3>{label}</h3>
+                <div class="text-container">
+                    {"".join(spans)}
+                </div>
+            </div>
+            """
+            sections_html.append(section_content)
+
+        legend_start = "rgba(255, 192, 203, 0.3)"
+        legend_end = "rgba(128, 0, 32, 1.0)"
+
+        html_content = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="utf-8">
+            <title>LLM Perplexity Comparison</title>
+            <style>
+                body {{
+                    font-family: Arial, sans-serif;
+                    margin: 40px;
+                    background-color: #f9f9f9;
+                    color: #333;
+                }}
+                .model-section {{
+                    margin-bottom: 25px;
+                }}
+                h3 {{
+                    margin-bottom: 8px;
+                    color: #444;
+                }}
+                .text-container {{
+                    background: #fff;
+                    padding: 20px;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+                    line-height: 2.5;
+                    font-size: 18px;
+                }}
+                h2 {{
+                    margin-bottom: 30px;
+                }}
+                .global-legend-container {{
+                    margin-top: 35px;
+                    background: #fff;
+                    padding: 20px;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+                    display: flex;
+                    align-items: center;
+                    justify-content: center;
+                    gap: 20px;
+                    font-size: 15px;
+                    color: #555;
+                }}
+                .legend-bar {{
+                    width: 300px;
+                    height: 16px;
+                    border-radius: 4px;
+                    background: linear-gradient(to right, {legend_start}, {legend_end});
+                    border: 1px solid #ddd;
+                }}
+            </style>
+        </head>
+        <body>
+            <h2>LLM Perplexity Text Comparison (Top {top_n if top_n else 'All'} Tokens)</h2>
+            {"".join(sections_html)}
+            
+            <div class="global-legend-container">
+                <span>Low ({global_min_p:.2f})</span>
+                <div class="legend-bar"></div>
+                <span>High ({global_max_p:.2f})</span>
+            </div>
+        </body>
+        </html>
+        """
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            f.write(html_content)
+
+        print(f"Global comparison visualization successfully saved to: {save_path}")
+
+    def plot_macro_comparison(
+        self, 
+        macro_data: dict[str, list[float]], 
+        save_path: str = "macro_perplexity_comparison.html",
+        show_values: bool = False
+    ):
+        """
+        Gera um gráfico de caixa (Boxplot) interativo para comparação macro,
+        exibindo as 5 estatísticas principais com cores alinhadas aos modelos.
+        """
+        import pandas as pd
+        import numpy as np
+        import plotly.graph_objects as go
+
+        rows = []
+        for model_name, values in macro_data.items():
+            for val in values:
+                rows.append({"Model": model_name, "Perplexity": val})
+        
+        df_long = pd.DataFrame(rows)
+
+        fig = go.Figure()
+        colors = px.colors.qualitative.Plotly[:len(macro_data)]
+        models = list(macro_data.items())
+
+        for i, (model_name, values) in enumerate(models):
+            df_model = df_long[df_long["Model"] == model_name]
+            color = colors[i % len(colors)]
+
+            fig.add_trace(go.Box(
+                y=df_model["Perplexity"],
+                name=model_name,
+                boxpoints=False,
+                marker_color=color
+            ))
+
+            if show_values:
+                arr = np.array(values)
+                q1 = np.percentile(arr, 25)
+                median = np.median(arr)
+                q3 = np.percentile(arr, 75)
+                minimum = np.min(arr)
+                maximum = np.max(arr)
+
+                stat_y = [minimum, q1, median, q3, maximum]
+                stat_labels = [
+                    f"Min: {minimum:.2f}",
+                    f"Q1: {q1:.2f}",
+                    f"Median: {median:.2f}",
+                    f"Q3: {q3:.2f}",
+                    f"Max: {maximum:.2f}"
+                ]
+
+                fig.add_trace(go.Scatter(
+                    x=[model_name] * len(stat_y),
+                    y=stat_y,
+                    mode="markers+text",
+                    text=stat_labels,
+                    textposition="top right",
+                    textfont=dict(size=11, color=color, family="Arial Black"),
+                    marker=dict(color=color, size=6, symbol="circle"),
+                    showlegend=False,
+                    hovertemplate="Model: " + model_name + "<br>%{text}<extra></extra>"
+                ))
+
+        fig.update_layout(
+            title="Macro Comparison: Statistical Distribution Summary",
+            xaxis_title="Models",
+            yaxis_title="Perplexity",
+            showlegend=False,
+            margin=dict(r=150) # Corrigido de 'right' para 'r'
+        )
+
+        fig.write_html(save_path)
+        print(f"Macro comparison statistical chart successfully saved to: {save_path}")
+        return fig
+
+    def plot_macro_violin(
+        self, 
+        macro_data: dict[str, list[float]], 
+        save_path: str = "macro_violin_comparison.html",
+        show_values: bool = False
+    ):
+        """
+        Gera um Violin Plot interativo para comparação macro da distribuição de perplexidade,
+        exibindo opcionalmente as 5 principais estatísticas (Min, Q1, Median, Q3, Max) 
+        com cores sincronizadas ao modelo.
+        
+        Parâmetros:
+        - macro_data (dict): Dicionário de listas com as perplexidades dos modelos.
+        - save_path (str): Caminho para salvar o arquivo HTML gerado.
+        - show_values (bool): Se True, exibe as estatísticas numéricas ao lado direito de cada violino.
+        """
+        import pandas as pd
+        import numpy as np
+        import plotly.graph_objects as go
+
+        rows = []
+        for model_name, values in macro_data.items():
+            for val in values:
+                rows.append({"Model": model_name, "Perplexity": val})
+        
+        df_long = pd.DataFrame(rows)
+
+        fig = go.Figure()
+        colors = px.colors.qualitative.Plotly[:len(macro_data)]
+        models = list(macro_data.items())
+
+        for i, (model_name, values) in enumerate(models):
+            df_model = df_long[df_long["Model"] == model_name]
+            color = colors[i % len(colors)]
+
+            # Adiciona o Violin Plot com caixa interna (box) embutida
+            fig.add_trace(go.Violin(
+                y=df_model["Perplexity"],
+                name=model_name,
+                box_visible=True,        # Mostra o boxplot interno embutido no violino
+                meanline_visible=True,   # Mostra a linha da média
+                fillcolor=color,
+                opacity=0.6,
+                line_color=color
+            ))
+
+            if show_values:
+                arr = np.array(values)
+                q1 = np.percentile(arr, 25)
+                median = np.median(arr)
+                q3 = np.percentile(arr, 75)
+                minimum = np.min(arr)
+                maximum = np.max(arr)
+
+                stat_y = [minimum, q1, median, q3, maximum]
+                stat_labels = [
+                    f"Min: {minimum:.2f}",
+                    f"Q1: {q1:.2f}",
+                    f"Median: {median:.2f}",
+                    f"Q3: {q3:.2f}",
+                    f"Max: {maximum:.2f}"
+                ]
+
+                fig.add_trace(go.Scatter(
+                    x=[model_name] * len(stat_y),
+                    y=stat_y,
+                    mode="markers+text",
+                    text=stat_labels,
+                    textposition="top right",
+                    textfont=dict(size=11, color=color, family="Arial Black"),
+                    marker=dict(color=color, size=6, symbol="circle"),
+                    showlegend=False,
+                    hovertemplate="Model: " + model_name + "<br>%{text}<extra></extra>"
+                ))
+
+        fig.update_layout(
+            title="Macro Comparison: Violin Distribution Summary",
+            xaxis_title="Models",
+            yaxis_title="Perplexity",
+            showlegend=False,
+            margin=dict(r=150) # Margem lateral para acomodar os rótulos estatísticos
+        )
+
+        fig.write_html(save_path)
+        print(f"Macro violin comparison chart successfully saved to: {save_path}")
+        return fig
+    

llm_pig-0.1.0/src/llm_pig/plots.py

@@ -0,0 +1,631 @@
+import plotly.express as px
+from .parser import PerplexityParser
+
+class PerplexityVisualizer:
+    def __init__(self, parser: PerplexityParser):
+        self.df = parser.get_dataframe()
+
+    def plot_token_curve(self, save_path: str = "perplexity_curve.html", x_axis: str = "index", tick_angle: int = 0):
+        """
+        Generates an interactive line chart displaying token-by-token perplexity along a prompt or document,
+        facilitating the identification of uncertainty spikes.
+
+        Parameters:
+        - save_path (str, optional): File path to save the generated HTML file. Default: "perplexity_curve.html".
+        - x_axis (str, optional): Defines the X-axis representation ('index' or 'token'). Default: "index".
+        - tick_angle (int, optional): Rotation angle for X-axis labels (e.g., 0 for normal, 90 for vertical). Default: 0.
+
+        Example Usage:
+        --------------
+        visualizer.plot_token_curve(
+            save_path="perplexity_curve.html",
+            x_axis="token",
+            tick_angle=45
+        )
+        """
+        if x_axis not in ["index", "token"]:
+            raise ValueError("O parâmetro 'x_axis' deve ser 'index' ou 'token'.")
+
+        x_data = self.df.index if x_axis == "index" else self.df["token"]
+
+        fig = px.line(
+            self.df,
+            x=x_data,
+            y="perplexity",
+            hover_data=["token"],
+            markers=True,
+            title="LLM Perplexity Curve by Token",
+            labels={"x": "Token Position" if x_axis == "index" else "Token", "perplexity": "Perplexity"}
+        )
+        
+        fig.update_traces(
+            hovertemplate="<b>Token:</b> %{customdata[0]}<br><b>Perplexity:</b> %{y:.2f}<extra></extra>"
+        )
+        
+        fig.update_layout(xaxis=dict(tickangle=tick_angle))
+        
+        fig.write_html(save_path)
+        print(f"Interactive chart successfully saved to: {save_path}")
+        return fig
+
+    def plot_token_bars(self, save_path: str = "perplexity_bars.html", top_n: int = None, cascade: bool = True):
+        """
+        Generates a horizontal bar chart displaying tokens on the Y-axis and perplexity values on the X-axis,
+        allowing clear visualization and ranking of token uncertainties.
+
+        Parameters:
+        - save_path (str, optional): File path to save the generated HTML file. Default: "perplexity_bars.html".
+        - top_n (int, optional): Limits the number of displayed tokens. Default: None (displays all tokens).
+        - cascade (bool, optional): If True, sorts tokens by perplexity value (highest on top). Default: True.
+
+        Example Usage:
+        --------------
+        visualizer.plot_token_bars(
+            save_path="perplexity_bars.html",
+            top_n=10,
+            cascade=True
+        )
+        """
+        df_plot = self.df.copy()
+
+        if cascade:
+            df_plot = df_plot.sort_values(by="perplexity", ascending=True)
+        
+        if top_n is not None:
+            if cascade:
+                df_plot = df_plot.tail(top_n)
+            else:
+                df_plot = df_plot.head(top_n)
+
+        fig = px.bar(
+            df_plot,
+            x="perplexity",
+            y="token",
+            orientation="h",
+            text="perplexity", # Define a coluna que terá o valor exibido na barra
+            title="LLM Perplexity by Token (Bar Chart)",
+            labels={"perplexity": "Perplexity", "token": "Token"}
+        )
+
+        # Formata o texto para exibir duas casas decimais e posiciona o texto dentro/ao lado da barra
+        fig.update_traces(
+            texttemplate='%{text:.2f}',
+            textposition='inside',
+            hovertemplate="<b>Token:</b> %{y}<br><b>Perplexity:</b> %{x:.2f}<extra></extra>"
+        )
+
+        fig.write_html(save_path)
+        print(f"Interactive bar chart successfully saved to: {save_path}")
+        return fig
+
+    def perplexity_text(self, save_path: str = "perplexity_text.html", top_n: int = None):
+        """
+        Generates an individual SHAP-style highlighted text visualization where token background colors 
+        and legend gradients are dynamically calculated based on token perplexity scores.
+
+        Parameters:
+        - save_path (str, optional): File path to save the generated HTML file. Default: "perplexity_text.html".
+        - top_n (int, optional): Limits highlighting to the top N tokens by perplexity score. Default: None (highlights all).
+
+        Example Usage:
+        --------------
+        visualizer.perplexity_text(
+            save_path="perplexity_text.html",
+            top_n=5
+        )
+        """
+        df = self.df.copy()
+        
+        # Identifica os tokens que entram no top_n
+        if top_n is not None and top_n < len(df):
+            df_filtered = df.nlargest(top_n, "perplexity")
+            top_indices = df_filtered.index
+        else:
+            df_filtered = df
+            top_indices = df.index
+
+        # Recalcula min e max baseados estritamente nos itens que receberão o destaque
+        min_p = df_filtered["perplexity"].min()
+        max_p = df_filtered["perplexity"].max()
+
+        def get_color_and_text_color(val, is_highlighted):
+            if not is_highlighted:
+                return "transparent", "#333333", False
+                
+            if max_p == min_p:
+                norm_val = 0.5
+            else:
+                # Normaliza usando o novo limite inferior do filtro
+                norm_val = (val - min_p) / (max_p - min_p)
+
+            r = int(255 - norm_val * (255 - 128))
+            g = int(192 - norm_val * 192)
+            b = int(203 - norm_val * (203 - 32))
+            alpha = 0.3 + (norm_val * 0.7)
+            bg_color = f"rgba({r}, {g}, {b}, {alpha})"
+            text_color = "#ffffff" if norm_val > 0.5 else "#333333"
+            
+            return bg_color, text_color, True
+
+        spans = []
+        for idx, row in df.iterrows():
+            token = row["token"]
+            p_val = row["perplexity"]
+            is_hl = idx in top_indices
+            
+            bg_color, text_color, highlighted = get_color_and_text_color(p_val, is_hl)
+            safe_token = token.replace("\n", "<br>")
+            
+            if highlighted:
+                span_html = (
+                    f'<span style="background-color: {bg_color}; color: {text_color}; '
+                    f'padding: 3px 6px; margin: 2px; border-radius: 4px; display: inline-block; '
+                    f'font-weight: 500;" title="Perplexity: {p_val:.2f}">{safe_token}</span>'
+                )
+            else:
+                span_html = (
+                    f'<span style="background-color: transparent; color: {text_color}; '
+                    f'padding: 3px 6px; margin: 2px; display: inline-block;" '
+                    f'title="Perplexity: {p_val:.2f} (Not in Top {top_n})">{safe_token}</span>'
+                )
+            spans.append(span_html)
+
+        legend_start = "rgba(255, 192, 203, 0.3)"
+        legend_end = "rgba(128, 0, 32, 1.0)"
+
+        html_content = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="utf-8">
+            <title>LLM Perplexity Text Highlight</title>
+            <style>
+                body {{
+                    font-family: Arial, sans-serif;
+                    margin: 40px;
+                    background-color: #f9f9f9;
+                    color: #333;
+                }}
+                .container {{
+                    background: #fff;
+                    padding: 25px;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+                    line-height: 2.5;
+                    font-size: 18px;
+                }}
+                h2 {{
+                    margin-bottom: 20px;
+                }}
+                .legend-container {{
+                    margin-top: 25px;
+                    display: flex;
+                    align-items: center;
+                    gap: 15px;
+                    font-size: 14px;
+                    color: #555;
+                }}
+                .legend-bar {{
+                    width: 200px;
+                    height: 14px;
+                    border-radius: 4px;
+                    background: linear-gradient(to right, {legend_start}, {legend_end});
+                    border: 1px solid #ddd;
+                }}
+            </style>
+        </head>
+        <body>
+            <h2>LLM Perplexity Text Highlight (Top {top_n if top_n else 'All'} Tokens)</h2>
+            <div class="container">
+                {"".join(spans)}
+                
+                <div class="legend-container">
+                    <span>Low ({min_p:.2f})</span>
+                    <div class="legend-bar"></div>
+                    <span>High ({max_p:.2f})</span>
+                </div>
+            </div>
+        </body>
+        </html>
+        """
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            f.write(html_content)
+
+        print(f"Text highlight visualization with recalculated legend successfully saved to: {save_path}")
+
+    def compare_perplexity_texts(
+        self, 
+        save_path: str = "perplexity_comparison.html", 
+        tokens: list[list[str]] = None, 
+        perplexities: list[list[float]] = None, 
+        labels: list[str] = None, 
+        top_n: int = None
+    ):
+        """
+        Generates a comparative multi-model SHAP-style text visualization using a unified global 
+        color scale gradient and a single consolidated legend in the footer.
+
+        Parameters:
+        - save_path (str, optional): File path to save the generated HTML file. Default: "perplexity_comparison.html".
+        - tokens (list of list of str, required): List containing token lists for each model. Default: None.
+        - perplexities (list of list of float, required): List containing perplexity score lists for each model. Default: None.
+        - labels (list of str, optional): Model identifiers or aliases. Default: None (auto-generated).
+        - top_n (int, optional): Limits highlighting to the top N tokens per model. Default: None.
+
+        Example Usage:
+        --------------
+        visualizer.compare_perplexity_texts(
+            save_path="perplexity_comparison.html",
+            tokens=[["O", " modelo"], ["A", " resposta"]],
+            perplexities=[[1.1, 2.3], [2.0, 3.5]],
+            labels=["Gemini", "GPT-4"],
+            top_n=2
+        )
+        """
+        if not tokens or not perplexities or len(tokens) != len(perplexities):
+            raise ValueError("As listas 'tokens' e 'perplexities' devem ser fornecidas e ter o mesmo comprimento.")
+
+        if labels is None:
+            labels = [f"Model {i+1}" for i in range(len(tokens))]
+
+        if len(tokens) != len(labels):
+            raise ValueError("A quantidade de listas de tokens deve ser igual à quantidade de 'labels'.")
+
+        import pandas as pd
+
+        models_dfs = []
+        all_highlighted_perplexities = []
+
+        # Passo 1: Processa cada modelo e coleta os valores destacados globalmente
+        for model_tokens, model_perps, label in zip(tokens, perplexities, labels):
+            if len(model_tokens) != len(model_perps):
+                raise ValueError(f"As listas de tokens e perplexidades do modelo '{label}' devem ter o mesmo tamanho.")
+
+            df = pd.DataFrame({"token": model_tokens, "perplexity": model_perps})
+            
+            if top_n is not None and top_n < len(df):
+                df_filtered = df.nlargest(top_n, "perplexity")
+                top_indices = set(df_filtered.index)
+            else:
+                top_indices = set(df.index)
+                df_filtered = df
+
+            models_dfs.append({"df": df, "top_indices": top_indices, "label": label})
+            
+            if not df_filtered.empty:
+                all_highlighted_perplexities.extend(df_filtered["perplexity"].tolist())
+
+        # Passo 2: Determina o Mínimo e Máximo global entre todos os tokens destacados
+        if all_highlighted_perplexities:
+            global_min_p = min(all_highlighted_perplexities)
+            global_max_p = max(all_highlighted_perplexities)
+        else:
+            global_min_p = 0.0
+            global_max_p = 1.0
+
+        def get_color_and_text_color(val, is_highlighted):
+            if not is_highlighted:
+                return "transparent", "#333333", False
+                
+            if global_max_p == global_min_p:
+                norm_val = 0.5
+            else:
+                norm_val = (val - global_min_p) / (global_max_p - global_min_p)
+                norm_val = max(0.0, min(1.0, norm_val))
+
+            r = int(255 - norm_val * (255 - 128))
+            g = int(192 - norm_val * 192)
+            b = int(203 - norm_val * (203 - 32))
+            alpha = 0.3 + (norm_val * 0.7)
+            bg_color = f"rgba({r}, {g}, {b}, {alpha})"
+            text_color = "#ffffff" if norm_val > 0.5 else "#333333"
+            
+            return bg_color, text_color, True
+
+        sections_html = []
+
+        # Passo 3: Constrói o HTML de cada seção de texto
+        for item in models_dfs:
+            df = item["df"]
+            top_indices = item["top_indices"]
+            label = item["label"]
+
+            spans = []
+            for idx, row in df.iterrows():
+                token = row["token"]
+                p_val = row["perplexity"]
+                is_hl = idx in top_indices
+                
+                bg_color, text_color, highlighted = get_color_and_text_color(p_val, is_hl)
+                safe_token = token.replace("\n", "<br>")
+                
+                if highlighted:
+                    span_html = (
+                        f'<span style="background-color: {bg_color}; color: {text_color}; '
+                        f'padding: 3px 6px; margin: 2px; border-radius: 4px; display: inline-block; '
+                        f'font-weight: 500;" title="Perplexity: {p_val:.2f}">{safe_token}</span>'
+                    )
+                else:
+                    span_html = (
+                        f'<span style="background-color: transparent; color: {text_color}; '
+                        f'padding: 3px 6px; margin: 2px; display: inline-block;" '
+                        f'title="Perplexity: {p_val:.2f} (Not in Top {top_n})">{safe_token}</span>'
+                    )
+                spans.append(span_html)
+
+            section_content = f"""
+            <div class="model-section">
+                <h3>{label}</h3>
+                <div class="text-container">
+                    {"".join(spans)}
+                </div>
+            </div>
+            """
+            sections_html.append(section_content)
+
+        legend_start = "rgba(255, 192, 203, 0.3)"
+        legend_end = "rgba(128, 0, 32, 1.0)"
+
+        html_content = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="utf-8">
+            <title>LLM Perplexity Comparison</title>
+            <style>
+                body {{
+                    font-family: Arial, sans-serif;
+                    margin: 40px;
+                    background-color: #f9f9f9;
+                    color: #333;
+                }}
+                .model-section {{
+                    margin-bottom: 25px;
+                }}
+                h3 {{
+                    margin-bottom: 8px;
+                    color: #444;
+                }}
+                .text-container {{
+                    background: #fff;
+                    padding: 20px;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+                    line-height: 2.5;
+                    font-size: 18px;
+                }}
+                h2 {{
+                    margin-bottom: 30px;
+                }}
+                .global-legend-container {{
+                    margin-top: 35px;
+                    background: #fff;
+                    padding: 20px;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+                    display: flex;
+                    align-items: center;
+                    justify-content: center;
+                    gap: 20px;
+                    font-size: 15px;
+                    color: #555;
+                }}
+                .legend-bar {{
+                    width: 300px;
+                    height: 16px;
+                    border-radius: 4px;
+                    background: linear-gradient(to right, {legend_start}, {legend_end});
+                    border: 1px solid #ddd;
+                }}
+            </style>
+        </head>
+        <body>
+            <h2>LLM Perplexity Text Comparison (Top {top_n if top_n else 'All'} Tokens)</h2>
+            {"".join(sections_html)}
+            
+            <div class="global-legend-container">
+                <span>Low ({global_min_p:.2f})</span>
+                <div class="legend-bar"></div>
+                <span>High ({global_max_p:.2f})</span>
+            </div>
+        </body>
+        </html>
+        """
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            f.write(html_content)
+
+        print(f"Global comparison visualization successfully saved to: {save_path}")
+
+    def plot_macro_comparison(
+        self, 
+        macro_data: dict[str, list[float]], 
+        save_path: str = "macro_perplexity_comparison.html",
+        show_values: bool = False
+    ):
+        """
+        Generates an interactive Boxplot for macro-level comparison of perplexity distributions across multiple models,
+        showing statistical metrics (Min, Q1, Median, Q3, Max) with model-aligned colors.
+
+        Parameters:
+        - macro_data (dict, required): Dictionary mapping model names to lists of perplexity floats. Default: None (positional).
+        - save_path (str, optional): File path to save the generated HTML file. Default: "macro_perplexity_comparison.html".
+        - show_values (bool, optional): If True, displays key statistical values on the right side. Default: False.
+
+        Example Usage:
+        --------------
+        macro_data = {
+            "Gemini": [1.25, 1.30, 1.45],
+            "GPT-4": [1.10, 1.15, 1.25]
+        }
+        visualizer.plot_macro_comparison(
+            macro_data=macro_data,
+            save_path="macro_boxplot.html",
+            show_values=True
+        )
+        """
+        import pandas as pd
+        import numpy as np
+        import plotly.graph_objects as go
+
+        rows = []
+        for model_name, values in macro_data.items():
+            for val in values:
+                rows.append({"Model": model_name, "Perplexity": val})
+        
+        df_long = pd.DataFrame(rows)
+
+        fig = go.Figure()
+        colors = px.colors.qualitative.Plotly[:len(macro_data)]
+        models = list(macro_data.items())
+
+        for i, (model_name, values) in enumerate(models):
+            df_model = df_long[df_long["Model"] == model_name]
+            color = colors[i % len(colors)]
+
+            fig.add_trace(go.Box(
+                y=df_model["Perplexity"],
+                name=model_name,
+                boxpoints=False,
+                marker_color=color
+            ))
+
+            if show_values:
+                arr = np.array(values)
+                q1 = np.percentile(arr, 25)
+                median = np.median(arr)
+                q3 = np.percentile(arr, 75)
+                minimum = np.min(arr)
+                maximum = np.max(arr)
+
+                stat_y = [minimum, q1, median, q3, maximum]
+                stat_labels = [
+                    f"Min: {minimum:.2f}",
+                    f"Q1: {q1:.2f}",
+                    f"Median: {median:.2f}",
+                    f"Q3: {q3:.2f}",
+                    f"Max: {maximum:.2f}"
+                ]
+
+                fig.add_trace(go.Scatter(
+                    x=[model_name] * len(stat_y),
+                    y=stat_y,
+                    mode="markers+text",
+                    text=stat_labels,
+                    textposition="top right",
+                    textfont=dict(size=11, color=color, family="Arial Black"),
+                    marker=dict(color=color, size=6, symbol="circle"),
+                    showlegend=False,
+                    hovertemplate="Model: " + model_name + "<br>%{text}<extra></extra>"
+                ))
+
+        fig.update_layout(
+            title="Macro Comparison: Statistical Distribution Summary",
+            xaxis_title="Models",
+            yaxis_title="Perplexity",
+            showlegend=False,
+            margin=dict(r=150)
+        )
+
+        fig.write_html(save_path)
+        print(f"Macro comparison statistical chart successfully saved to: {save_path}")
+        return fig
+
+    def plot_macro_violin(
+        self, 
+        macro_data: dict[str, list[float]], 
+        save_path: str = "macro_violin_comparison.html",
+        show_values: bool = False
+    ):
+        """
+        Generates an interactive Violin Plot for macro-level analysis of perplexity distributions,
+        displaying probability density, internal box stats, and optional key statistical markers.
+
+        Parameters:
+        - macro_data (dict, required): Dictionary mapping model names to lists of perplexity floats. Default: None (positional).
+        - save_path (str, optional): File path to save the generated HTML file. Default: "macro_violin_comparison.html".
+        - show_values (bool, optional): If True, displays statistical values (Min, Q1, Median, Q3, Max). Default: False.
+
+        Example Usage:
+        --------------
+        macro_data = {
+            "Gemini": [1.25, 1.30, 1.45],
+            "GPT-4": [1.10, 1.15, 1.25]
+        }
+        visualizer.plot_macro_violin(
+            macro_data=macro_data,
+            save_path="macro_violin.html",
+            show_values=True
+        )
+        """
+        import pandas as pd
+        import numpy as np
+        import plotly.graph_objects as go
+
+        rows = []
+        for model_name, values in macro_data.items():
+            for val in values:
+                rows.append({"Model": model_name, "Perplexity": val})
+        
+        df_long = pd.DataFrame(rows)
+
+        fig = go.Figure()
+        colors = px.colors.qualitative.Plotly[:len(macro_data)]
+        models = list(macro_data.items())
+
+        for i, (model_name, values) in enumerate(models):
+            df_model = df_long[df_long["Model"] == model_name]
+            color = colors[i % len(colors)]
+
+            # Adiciona o Violin Plot com caixa interna (box) embutida
+            fig.add_trace(go.Violin(
+                y=df_model["Perplexity"],
+                name=model_name,
+                box_visible=True,        # Mostra o boxplot interno embutido no violino
+                meanline_visible=True,   # Mostra a linha da média
+                fillcolor=color,
+                opacity=0.6,
+                line_color=color
+            ))
+
+            if show_values:
+                arr = np.array(values)
+                q1 = np.percentile(arr, 25)
+                median = np.median(arr)
+                q3 = np.percentile(arr, 75)
+                minimum = np.min(arr)
+                maximum = np.max(arr)
+
+                stat_y = [minimum, q1, median, q3, maximum]
+                stat_labels = [
+                    f"Min: {minimum:.2f}",
+                    f"Q1: {q1:.2f}",
+                    f"Median: {median:.2f}",
+                    f"Q3: {q3:.2f}",
+                    f"Max: {maximum:.2f}"
+                ]
+
+                fig.add_trace(go.Scatter(
+                    x=[model_name] * len(stat_y),
+                    y=stat_y,
+                    mode="markers+text",
+                    text=stat_labels,
+                    textposition="top right",
+                    textfont=dict(size=11, color=color, family="Arial Black"),
+                    marker=dict(color=color, size=6, symbol="circle"),
+                    showlegend=False,
+                    hovertemplate="Model: " + model_name + "<br>%{text}<extra></extra>"
+                ))
+
+        fig.update_layout(
+            title="Macro Comparison: Violin Distribution Summary",
+            xaxis_title="Models",
+            yaxis_title="Perplexity",
+            showlegend=False,
+            margin=dict(r=150) # Margem lateral para acomodar os rótulos estatísticos
+        )
+
+        fig.write_html(save_path)
+        print(f"Macro violin comparison chart successfully saved to: {save_path}")
+        return fig