datanarrator 0.1.0__tar.gz

datanarrator-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: datanarrator
+Version: 0.1.0
+Summary: Convierte cualquier DataFrame de pandas en un análisis en lenguaje natural
+Author-email: Tu Nombre <tu@email.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ikernavarro4/data-narrator
+Project-URL: Repository, https://github.com/ikernavarro4/data-narrator
+Keywords: data science,eda,nlg,pandas,analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: numpy>=1.23.0

datanarrator-0.1.0/datanarrator/__init__.py

@@ -0,0 +1,9 @@
+from datanarrator.narrator import Narrator
+
+__version__ = "0.1.0"
+__all__ = ["Narrator"]
+
+from datanarrator.narrator import Narrator
+
+__version__ = "0.1.0"
+__all__ = ["Narrator"]

datanarrator-0.1.0/datanarrator/analyzer.py

@@ -0,0 +1,182 @@
+import pandas as pd
+import numpy as np
+
+
+class DataAnalyzer:
+    """Analiza un DataFrame y extrae estadísticas relevantes."""
+
+    def __init__(self, df: pd.DataFrame):
+        if not isinstance(df, pd.DataFrame):
+            raise TypeError("El input debe ser un DataFrame de pandas.")
+        if df.empty:
+            raise ValueError("El DataFrame no puede estar vacío.")
+        self.df = df
+        self._results = None
+
+    def analyze(self) -> dict:
+        """Corre el análisis completo y devuelve un diccionario con los resultados."""
+        self._results = {
+            "overview": self._overview(),
+            "numeric": self._analyze_numeric(),
+            "categorical": self._analyze_categorical(),
+            "datetime": self._analyze_datetime(),
+            "correlations": self._correlations(),
+            "alerts": self._alerts(),
+        }
+        return self._results
+
+    def _overview(self) -> dict:
+        df = self.df
+        numeric_cols = df.select_dtypes(include="number").columns.tolist()
+        categorical_cols = df.select_dtypes(include=["str", "category"]).columns.tolist()
+        datetime_cols = df.select_dtypes(include=["datetime"]).columns.tolist()
+
+        # Intentar detectar fechas en columnas string
+        for col in categorical_cols.copy():
+            try:
+                pd.to_datetime(df[col], infer_datetime_format=True)
+                datetime_cols.append(col)
+                categorical_cols.remove(col)
+            except Exception:
+                pass
+
+        total_nulls = df.isnull().sum().sum()
+        total_cells = df.shape[0] * df.shape[1]
+
+        return {
+            "rows": df.shape[0],
+            "cols": df.shape[1],
+            "numeric_cols": numeric_cols,
+            "categorical_cols": categorical_cols,
+            "datetime_cols": datetime_cols,
+            "total_nulls": int(total_nulls),
+            "null_pct": round(total_nulls / total_cells * 100, 2),
+            "duplicates": int(df.duplicated().sum()),
+            "memory_kb": round(df.memory_usage(deep=True).sum() / 1024, 1),
+        }
+
+    def _analyze_numeric(self) -> list:
+        results = []
+        numeric_cols = self.df.select_dtypes(include="number").columns
+        for col in numeric_cols:
+            series = self.df[col].dropna()
+            if len(series) == 0:
+                continue
+            q1 = series.quantile(0.25)
+            q3 = series.quantile(0.75)
+            iqr = q3 - q1
+            outliers = series[(series < q1 - 1.5 * iqr) | (series > q3 + 1.5 * iqr)]
+            results.append({
+                "col": col,
+                "mean": round(series.mean(), 2),
+                "median": round(series.median(), 2),
+                "std": round(series.std(), 2),
+                "min": round(series.min(), 2),
+                "max": round(series.max(), 2),
+                "nulls": int(self.df[col].isnull().sum()),
+                "null_pct": round(self.df[col].isnull().sum() / len(self.df) * 100, 1),
+                "skew": round(float(series.skew()), 2),
+                "outlier_count": len(outliers),
+            })
+        return results
+
+    def _analyze_categorical(self) -> list:
+        results = []
+        cat_cols = self.df.select_dtypes(include=["str", "category"]).columns
+        for col in cat_cols:
+            series = self.df[col].dropna()
+            value_counts = series.value_counts()
+            results.append({
+                "col": col,
+                "unique": int(series.nunique()),
+                "top_value": str(value_counts.index[0]) if len(value_counts) > 0 else None,
+                "top_freq": int(value_counts.iloc[0]) if len(value_counts) > 0 else 0,
+                "top_pct": round(value_counts.iloc[0] / len(series) * 100, 1) if len(value_counts) > 0 else 0,
+                "nulls": int(self.df[col].isnull().sum()),
+                "null_pct": round(self.df[col].isnull().sum() / len(self.df) * 100, 1),
+                "high_cardinality": series.nunique() > 20,
+            })
+        return results
+
+    def _analyze_datetime(self) -> list:
+        results = []
+        dt_cols = self.df.select_dtypes(include=["datetime"]).columns
+        for col in dt_cols:
+            series = pd.to_datetime(self.df[col], errors="coerce").dropna()
+            if len(series) == 0:
+                continue
+            results.append({
+                "col": col,
+                "min_date": str(series.min().date()),
+                "max_date": str(series.max().date()),
+                "range_days": (series.max() - series.min()).days,
+                "nulls": int(self.df[col].isnull().sum()),
+            })
+        return results
+
+    def _correlations(self) -> list:
+        numeric = self.df.select_dtypes(include="number")
+        if numeric.shape[1] < 2:
+            return []
+        corr_matrix = numeric.corr()
+        pairs = []
+        cols = corr_matrix.columns.tolist()
+        for i in range(len(cols)):
+            for j in range(i + 1, len(cols)):
+                val = corr_matrix.iloc[i, j]
+                if not np.isnan(val) and abs(val) >= 0.5:
+                    pairs.append({
+                        "col_a": cols[i],
+                        "col_b": cols[j],
+                        "correlation": round(val, 2),
+                        "strength": "alta" if abs(val) >= 0.75 else "moderada",
+                        "direction": "positiva" if val > 0 else "negativa",
+                    })
+        pairs.sort(key=lambda x: abs(x["correlation"]), reverse=True)
+        return pairs
+
+    def _alerts(self) -> list:
+        alerts = []
+        df = self.df
+
+        # Duplicados
+        dups = df.duplicated().sum()
+        if dups > 0:
+            alerts.append({
+                "type": "duplicates",
+                "message": f"{dups} registros duplicados detectados.",
+                "suggestion": "Considera eliminarlos antes de modelar.",
+            })
+
+        # Columnas con muchos nulos
+        for col in df.columns:
+            null_pct = df[col].isnull().sum() / len(df) * 100
+            if null_pct >= 20:
+                alerts.append({
+                    "type": "high_nulls",
+                    "col": col,
+                    "message": f"'{col}' tiene {null_pct:.1f}% de valores nulos.",
+                    "suggestion": "Considera imputar o eliminar esta columna.",
+                })
+
+        # Alta cardinalidad
+        for col in df.select_dtypes(include=["str", "category"]).columns:
+            if df[col].nunique() > 50:
+                alerts.append({
+                    "type": "high_cardinality",
+                    "col": col,
+                    "message": f"'{col}' tiene {df[col].nunique()} valores únicos.",
+                    "suggestion": "Evita label encoding directo. Considera target encoding.",
+                })
+
+        # Columnas con un solo valor
+        for col in df.columns:
+            if df[col].nunique() == 1:
+                alerts.append({
+                    "type": "constant_column",
+                    "col": col,
+                    "message": f"'{col}' tiene un solo valor único.",
+                    "suggestion": "Esta columna no aporta información. Considera eliminarla.",
+                })
+
+        return alerts

datanarrator-0.1.0/datanarrator/narrator.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+import pandas as pd
+from datanarrator.analyzer import DataAnalyzer
+
+
+class Narrator:
+    """
+    Convierte un DataFrame de pandas en un análisis en lenguaje natural.
+
+    Ejemplo:
+        >>> from datanarrator import Narrator
+        >>> import pandas as pd
+        >>> df = pd.read_csv("titanic.csv")
+        >>> n = Narrator(df, lang="es")
+        >>> print(n.describe())
+    """
+
+    SUPPORTED_LANGS = ("es", "en")
+
+    def __init__(self, df: pd.DataFrame, lang: str = "es"):
+        if lang not in self.SUPPORTED_LANGS:
+            raise ValueError(f"Idioma '{lang}' no soportado. Usa: {self.SUPPORTED_LANGS}")
+        self.df = df
+        self.lang = lang
+        self._analyzer = DataAnalyzer(df)
+        self._data = self._analyzer.analyze()
+
+    # ------------------------------------------------------------------
+    # API pública
+    # ------------------------------------------------------------------
+
+    def describe(self) -> str:
+        """Genera el análisis completo en lenguaje natural."""
+        sections = [
+            self._section_overview(),
+            self._section_numeric(),
+            self._section_categorical(),
+            self._section_correlations(),
+            self._section_alerts(),
+        ]
+        return "\n\n".join(s for s in sections if s)
+
+    def executive_summary(self) -> str:
+        """Resumen ejecutivo de 2-3 oraciones."""
+        ov = self._data["overview"]
+        parts = []
+
+        if self.lang == "es":
+            parts.append(
+                f"El dataset contiene {ov['rows']:,} registros y {ov['cols']} columnas "
+                f"({len(ov['numeric_cols'])} numéricas, {len(ov['categorical_cols'])} categóricas)."
+            )
+            if ov["null_pct"] > 0:
+                parts.append(f"Presenta un {ov['null_pct']}% de valores nulos en total.")
+            corrs = self._data["correlations"]
+            if corrs:
+                top = corrs[0]
+                parts.append(
+                    f"La correlación más fuerte es entre '{top['col_a']}' y '{top['col_b']}' ({top['correlation']})."
+                )
+        else:
+            parts.append(
+                f"The dataset has {ov['rows']:,} rows and {ov['cols']} columns "
+                f"({len(ov['numeric_cols'])} numeric, {len(ov['categorical_cols'])} categorical)."
+            )
+            if ov["null_pct"] > 0:
+                parts.append(f"Overall null rate is {ov['null_pct']}%.")
+            corrs = self._data["correlations"]
+            if corrs:
+                top = corrs[0]
+                parts.append(
+                    f"Strongest correlation: '{top['col_a']}' and '{top['col_b']}' ({top['correlation']})."
+                )
+
+        return " ".join(parts)
+
+    def alerts_only(self) -> str:
+        """Devuelve solo las alertas y recomendaciones detectadas."""
+        alerts = self._data["alerts"]
+        if not alerts:
+            if self.lang == "es":
+                return "No se detectaron alertas en este dataset."
+            return "No alerts detected in this dataset."
+
+        lines = []
+        header = "Alertas detectadas:" if self.lang == "es" else "Alerts detected:"
+        lines.append(header)
+        for a in alerts:
+            lines.append(f"  → {a['message']} {a['suggestion']}")
+        return "\n".join(lines)
+
+    def export(self, filepath: str) -> None:
+        """Exporta el análisis completo a un archivo .txt o .md."""
+        content = self.describe()
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(content)
+        print(f"Análisis exportado a: {filepath}")
+
+    def compare(self, df2):
+        if not isinstance(df2, __import__('pandas').DataFrame):
+            raise TypeError("El input debe ser un DataFrame de pandas.")
+        if df2.empty:
+            raise ValueError("El segundo DataFrame no puede estar vacío.")
+        df1 = self.df
+        out = []
+        if self.lang == "es":
+            out.append("--- Comparación de datasets ---")
+            diff = df2.shape[0] - df1.shape[0]
+            if diff > 0:
+                out.append(f"El segundo dataset tiene {diff} registros más.")
+            elif diff < 0:
+                out.append(f"El segundo dataset tiene {abs(diff)} registros menos.")
+            else:
+                out.append("Ambos datasets tienen el mismo número de registros.")
+            cols1, cols2 = set(df1.columns), set(df2.columns)
+            if cols1 - cols2:
+                out.append(f"Columnas solo en el primero: {', '.join(cols1 - cols2)}.")
+            if cols2 - cols1:
+                out.append(f"Columnas solo en el segundo: {', '.join(cols2 - cols1)}.")
+            common = [c for c in df1.select_dtypes(include="number").columns if c in df2.select_dtypes(include="number").columns]
+            for col in common:
+                m1, m2 = df1[col].mean(), df2[col].mean()
+                if m1 == 0:
+                    continue
+                pct = round((m2 - m1) / abs(m1) * 100, 1)
+                if abs(pct) >= 10:
+                    d = "subió" if pct > 0 else "bajó"
+                    out.append(f"'{col}': media {d} de {round(m1,2)} a {round(m2,2)} ({pct:+.1f}%).")
+            n1 = df1.isnull().sum().sum() / (df1.shape[0] * df1.shape[1]) * 100
+            n2 = df2.isnull().sum().sum() / (df2.shape[0] * df2.shape[1]) * 100
+            dn = round(n2 - n1, 1)
+            if abs(dn) >= 5:
+                d = "más" if dn > 0 else "menos"
+                out.append(f"⚠  El segundo dataset tiene {abs(dn)}% {d} valores nulos.")
+                out.append("     → Posible degradación en calidad de datos.")
+            drift = []
+            for col in common:
+                s1, s2 = df1[col].std(), df2[col].std()
+                if s1 == 0:
+                    continue
+                if abs(s2 - s1) / s1 * 100 >= 30:
+                    drift.append(col)
+            if drift:
+                out.append(f"⚠  Posible data drift en: {', '.join(drift)}.")
+                out.append("     → Dispersión cambió más del 30%. Revisa antes de producción.")
+        else:
+            out.append("--- Dataset comparison ---")
+            diff = df2.shape[0] - df1.shape[0]
+            if diff > 0:
+                out.append(f"The second dataset has {diff} more rows.")
+            elif diff < 0:
+                out.append(f"The second dataset has {abs(diff)} fewer rows.")
+            else:
+                out.append("Both datasets have the same number of rows.")
+            cols1, cols2 = set(df1.columns), set(df2.columns)
+            if cols1 - cols2:
+                out.append(f"Columns only in first: {', '.join(cols1 - cols2)}.")
+            if cols2 - cols1:
+                out.append(f"Columns only in second: {', '.join(cols2 - cols1)}.")
+            common = [c for c in df1.select_dtypes(include="number").columns if c in df2.select_dtypes(include="number").columns]
+            for col in common:
+                m1, m2 = df1[col].mean(), df2[col].mean()
+                if m1 == 0:
+                    continue
+                pct = round((m2 - m1) / abs(m1) * 100, 1)
+                if abs(pct) >= 10:
+                    d = "increased" if pct > 0 else "decreased"
+                    out.append(f"'{col}': mean {d} from {round(m1,2)} to {round(m2,2)} ({pct:+.1f}%).")
+            n1 = df1.isnull().sum().sum() / (df1.shape[0] * df1.shape[1]) * 100
+            n2 = df2.isnull().sum().sum() / (df2.shape[0] * df2.shape[1]) * 100
+            dn = round(n2 - n1, 1)
+            if abs(dn) >= 5:
+                d = "more" if dn > 0 else "fewer"
+                out.append(f"⚠  Second dataset has {abs(dn)}% {d} null values.")
+                out.append("     → Possible data quality degradation.")
+            drift = []
+            for col in common:
+                s1, s2 = df1[col].std(), df2[col].std()
+                if s1 == 0:
+                    continue
+                if abs(s2 - s1) / s1 * 100 >= 30:
+                    drift.append(col)
+            if drift:
+                out.append(f"⚠  Possible data drift in: {', '.join(drift)}.")
+                out.append("     → Dispersion changed over 30%. Review before production.")
+        return "\n".join(out)
+
+    # ------------------------------------------------------------------
+    # Secciones internas
+    # ------------------------------------------------------------------
+
+    def _section_overview(self) -> str:
+        ov = self._data["overview"]
+        if self.lang == "es":
+            lines = [
+                "--- Resumen general ---",
+                f"El dataset contiene {ov['rows']:,} registros con {ov['cols']} columnas: "
+                f"{len(ov['numeric_cols'])} numéricas, {len(ov['categorical_cols'])} categóricas"
+                + (f" y {len(ov['datetime_cols'])} de fecha." if ov["datetime_cols"] else "."),
+            ]
+            if ov["total_nulls"] > 0:
+                lines.append(f"Valores nulos: {ov['total_nulls']:,} ({ov['null_pct']}% del total).")
+            else:
+                lines.append("No se encontraron valores nulos.")
+            if ov["duplicates"] > 0:
+                lines.append(f"Se detectaron {ov['duplicates']} registros duplicados.")
+            lines.append(f"Memoria utilizada: {ov['memory_kb']} KB.")
+        else:
+            lines = [
+                "--- Overview ---",
+                f"The dataset has {ov['rows']:,} rows and {ov['cols']} columns: "
+                f"{len(ov['numeric_cols'])} numeric, {len(ov['categorical_cols'])} categorical"
+                + (f", and {len(ov['datetime_cols'])} datetime." if ov["datetime_cols"] else "."),
+            ]
+            if ov["total_nulls"] > 0:
+                lines.append(f"Null values: {ov['total_nulls']:,} ({ov['null_pct']}% of all cells).")
+            else:
+                lines.append("No null values found.")
+            if ov["duplicates"] > 0:
+                lines.append(f"{ov['duplicates']} duplicate rows detected.")
+            lines.append(f"Memory usage: {ov['memory_kb']} KB.")
+        return "\n".join(lines)
+
+    def _section_numeric(self) -> str:
+        cols = self._data["numeric"]
+        if not cols:
+            return ""
+        header = "--- Columnas numéricas ---" if self.lang == "es" else "--- Numeric columns ---"
+        lines = [header]
+        for c in cols:
+            if self.lang == "es":
+                line = (
+                    f"{c['col']}: media={c['mean']}, mediana={c['median']}, "
+                    f"std={c['std']}, rango=[{c['min']} – {c['max']}]"
+                )
+                if c["nulls"] > 0:
+                    line += f", nulos={c['nulls']} ({c['null_pct']}%)"
+                if c["outlier_count"] > 0:
+                    line += f". Se detectaron {c['outlier_count']} posibles outliers (IQR)."
+                if abs(c["skew"]) > 1:
+                    direction = "positivo" if c["skew"] > 0 else "negativo"
+                    line += f" Distribución con sesgo {direction} ({c['skew']})."
+            else:
+                line = (
+                    f"{c['col']}: mean={c['mean']}, median={c['median']}, "
+                    f"std={c['std']}, range=[{c['min']} – {c['max']}]"
+                )
+                if c["nulls"] > 0:
+                    line += f", nulls={c['nulls']} ({c['null_pct']}%)"
+                if c["outlier_count"] > 0:
+                    line += f". {c['outlier_count']} potential outliers detected (IQR)."
+                if abs(c["skew"]) > 1:
+                    direction = "positive" if c["skew"] > 0 else "negative"
+                    line += f" {direction.capitalize()} skew ({c['skew']})."
+            lines.append(f"  {line}")
+        return "\n".join(lines)
+
+    def _section_categorical(self) -> str:
+        cols = self._data["categorical"]
+        if not cols:
+            return ""
+        header = "--- Columnas categóricas ---" if self.lang == "es" else "--- Categorical columns ---"
+        lines = [header]
+        for c in cols:
+            if self.lang == "es":
+                line = (
+                    f"{c['col']}: {c['unique']} valores únicos. "
+                    f"El más frecuente es '{c['top_value']}' ({c['top_pct']}% de los registros)."
+                )
+                if c["nulls"] > 0:
+                    line += f" Nulos: {c['null_pct']}%."
+            else:
+                line = (
+                    f"{c['col']}: {c['unique']} unique values. "
+                    f"Most frequent: '{c['top_value']}' ({c['top_pct']}% of records)."
+                )
+                if c["nulls"] > 0:
+                    line += f" Nulls: {c['null_pct']}%."
+            lines.append(f"  {line}")
+        return "\n".join(lines)
+
+    def _section_correlations(self) -> str:
+        corrs = self._data["correlations"]
+        if not corrs:
+            return ""
+        header = "--- Correlaciones relevantes ---" if self.lang == "es" else "--- Relevant correlations ---"
+        lines = [header]
+        for c in corrs:
+            if self.lang == "es":
+                lines.append(
+                    f"  {c['col_a']} ↔ {c['col_b']}: correlación {c['strength']} {c['direction']} ({c['correlation']})"
+                )
+            else:
+                lines.append(
+                    f"  {c['col_a']} ↔ {c['col_b']}: {c['strength']} {c['direction']} correlation ({c['correlation']})"
+                )
+        return "\n".join(lines)
+
+    def _section_alerts(self) -> str:
+        alerts = self._data["alerts"]
+        if not alerts:
+            return ""
+        header = "--- Alertas y recomendaciones ---" if self.lang == "es" else "--- Alerts & recommendations ---"
+        lines = [header]
+        for a in alerts:
+            lines.append(f"  ⚠  {a['message']}")
+            lines.append(f"     → {a['suggestion']}")
+        return "\n".join(lines)

datanarrator-0.1.0/datanarrator.egg-info/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: datanarrator
+Version: 0.1.0
+Summary: Convierte cualquier DataFrame de pandas en un análisis en lenguaje natural
+Author-email: Tu Nombre <tu@email.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ikernavarro4/data-narrator
+Project-URL: Repository, https://github.com/ikernavarro4/data-narrator
+Keywords: data science,eda,nlg,pandas,analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: numpy>=1.23.0

datanarrator-0.1.0/datanarrator.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+datanarrator/__init__.py
+datanarrator/analyzer.py
+datanarrator/narrator.py
+datanarrator.egg-info/PKG-INFO
+datanarrator.egg-info/SOURCES.txt
+datanarrator.egg-info/dependency_links.txt
+datanarrator.egg-info/requires.txt
+datanarrator.egg-info/top_level.txt
+tests/test_narrator.py

datanarrator-0.1.0/datanarrator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

datanarrator-0.1.0/datanarrator.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pandas>=1.5.0
+numpy>=1.23.0

datanarrator-0.1.0/datanarrator.egg-info/top_level.txt

@@ -0,0 +1 @@
+datanarrator

datanarrator-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "datanarrator"
+version = "0.1.0"
+description = "Convierte cualquier DataFrame de pandas en un análisis en lenguaje natural"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Tu Nombre", email = "tu@email.com" }
+]
+keywords = ["data science", "eda", "nlg", "pandas", "analysis"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "pandas>=1.5.0",
+  "numpy>=1.23.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ikernavarro4/data-narrator"
+Repository = "https://github.com/ikernavarro4/data-narrator"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["datanarrator*"]

datanarrator-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

datanarrator-0.1.0/tests/test_narrator.py

@@ -0,0 +1,250 @@
+import pytest
+import pandas as pd
+import numpy as np
+from datanarrator import Narrator
+from datanarrator.analyzer import DataAnalyzer
+
+
+# ------------------------------------------------------------------
+# Fixtures — datasets reutilizables en todos los tests
+# ------------------------------------------------------------------
+
+@pytest.fixture
+def df_basic():
+    """Dataset básico con columnas numéricas y categóricas."""
+    return pd.DataFrame({
+        "edad": [25, 30, 35, 40, 45, 200],
+        "salario": [30000, 45000, 50000, 60000, 70000, 80000],
+        "ciudad": ["cdmx", "cdmx", "monterrey", "guadalajara", "cdmx", "monterrey"],
+        "activo": ["si", "no", "si", "si", "no", "si"],
+    })
+
+
+@pytest.fixture
+def df_with_nulls():
+    """Dataset con valores nulos."""
+    return pd.DataFrame({
+        "edad": [25, None, 35, None, 45],
+        "nombre": ["Ana", "Luis", None, "María", "Pedro"],
+        "salario": [30000, 45000, 50000, None, 70000],
+    })
+
+
+@pytest.fixture
+def df_numeric_only():
+    """Dataset solo con columnas numéricas."""
+    return pd.DataFrame({
+        "a": [1, 2, 3, 4, 5],
+        "b": [10, 20, 30, 40, 50],
+        "c": [100, 200, 300, 400, 500],
+    })
+
+
+@pytest.fixture
+def df_categorical_only():
+    """Dataset solo con columnas categóricas."""
+    return pd.DataFrame({
+        "color": ["rojo", "azul", "rojo", "verde", "azul"],
+        "talla": ["s", "m", "l", "m", "s"],
+    })
+
+
+# ------------------------------------------------------------------
+# Tests de inicialización
+# ------------------------------------------------------------------
+
+def test_narrator_init_valid(df_basic):
+    n = Narrator(df_basic)
+    assert n is not None
+
+
+def test_narrator_default_lang(df_basic):
+    n = Narrator(df_basic)
+    assert n.lang == "es"
+
+
+def test_narrator_english_lang(df_basic):
+    n = Narrator(df_basic, lang="en")
+    assert n.lang == "en"
+
+
+def test_narrator_invalid_lang(df_basic):
+    with pytest.raises(ValueError):
+        Narrator(df_basic, lang="fr")
+
+
+def test_narrator_invalid_input():
+    with pytest.raises(TypeError):
+        Narrator("no soy un dataframe")
+
+
+def test_narrator_empty_dataframe():
+    with pytest.raises(ValueError):
+        Narrator(pd.DataFrame())
+
+
+# ------------------------------------------------------------------
+# Tests de describe()
+# ------------------------------------------------------------------
+
+def test_describe_returns_string(df_basic):
+    n = Narrator(df_basic)
+    result = n.describe()
+    assert isinstance(result, str)
+
+
+def test_describe_not_empty(df_basic):
+    n = Narrator(df_basic)
+    result = n.describe()
+    assert len(result) > 0
+
+
+def test_describe_contains_resumen(df_basic):
+    n = Narrator(df_basic, lang="es")
+    result = n.describe()
+    assert "Resumen general" in result
+
+
+def test_describe_english(df_basic):
+    n = Narrator(df_basic, lang="en")
+    result = n.describe()
+    assert "Overview" in result
+
+
+def test_describe_numeric_only(df_numeric_only):
+    n = Narrator(df_numeric_only)
+    result = n.describe()
+    assert isinstance(result, str)
+    assert len(result) > 0
+
+
+def test_describe_categorical_only(df_categorical_only):
+    n = Narrator(df_categorical_only)
+    result = n.describe()
+    assert isinstance(result, str)
+    assert len(result) > 0
+
+
+# ------------------------------------------------------------------
+# Tests de executive_summary()
+# ------------------------------------------------------------------
+
+def test_executive_summary_returns_string(df_basic):
+    n = Narrator(df_basic)
+    result = n.executive_summary()
+    assert isinstance(result, str)
+
+
+def test_executive_summary_not_empty(df_basic):
+    n = Narrator(df_basic)
+    result = n.executive_summary()
+    assert len(result) > 0
+
+
+def test_executive_summary_english(df_basic):
+    n = Narrator(df_basic, lang="en")
+    result = n.executive_summary()
+    assert isinstance(result, str)
+
+
+# ------------------------------------------------------------------
+# Tests de alerts_only()
+# ------------------------------------------------------------------
+
+def test_alerts_only_returns_string(df_basic):
+    n = Narrator(df_basic)
+    result = n.alerts_only()
+    assert isinstance(result, str)
+
+
+def test_alerts_with_nulls(df_with_nulls):
+    n = Narrator(df_with_nulls)
+    result = n.alerts_only()
+    assert isinstance(result, str)
+
+
+def test_no_alerts_clean_dataset(df_numeric_only):
+    n = Narrator(df_numeric_only)
+    result = n.alerts_only()
+    assert "No se detectaron alertas" in result
+
+
+# ------------------------------------------------------------------
+# Tests de export()
+# ------------------------------------------------------------------
+
+def test_export_creates_file(df_basic, tmp_path):
+    n = Narrator(df_basic)
+    filepath = tmp_path / "reporte.txt"
+    n.export(str(filepath))
+    assert filepath.exists()
+
+
+def test_export_file_not_empty(df_basic, tmp_path):
+    n = Narrator(df_basic)
+    filepath = tmp_path / "reporte.md"
+    n.export(str(filepath))
+    assert filepath.stat().st_size > 0
+
+
+# ------------------------------------------------------------------
+# Tests del analyzer
+# ------------------------------------------------------------------
+
+def test_analyzer_overview_rows(df_basic):
+    analyzer = DataAnalyzer(df_basic)
+    result = analyzer.analyze()
+    assert result["overview"]["rows"] == 6
+
+
+def test_analyzer_overview_cols(df_basic):
+    analyzer = DataAnalyzer(df_basic)
+    result = analyzer.analyze()
+    assert result["overview"]["cols"] == 4
+
+
+def test_analyzer_detects_nulls(df_with_nulls):
+    analyzer = DataAnalyzer(df_with_nulls)
+    result = analyzer.analyze()
+    assert result["overview"]["total_nulls"] > 0
+
+
+def test_analyzer_correlations(df_numeric_only):
+    analyzer = DataAnalyzer(df_numeric_only)
+    result = analyzer.analyze()
+    assert isinstance(result["correlations"], list)
+
+
+def test_analyzer_alerts_high_nulls(df_with_nulls):
+    analyzer = DataAnalyzer(df_with_nulls)
+    result = analyzer.analyze()
+    alert_types = [a["type"] for a in result["alerts"]]
+    assert "high_nulls" in alert_types
+
+
+# ------------------------------------------------------------------
+# Tests de compare()
+# ------------------------------------------------------------------
+
+def test_compare_returns_string(df_basic):
+    df2 = df_basic.copy()
+    df2["edad"] = df2["edad"] * 2
+    n = Narrator(df_basic)
+    result = n.compare(df2)
+    assert isinstance(result, str)
+
+def test_compare_invalid_input(df_basic):
+    n = Narrator(df_basic)
+    with pytest.raises(TypeError):
+        n.compare("no soy un dataframe")
+
+def test_compare_empty_dataframe(df_basic):
+    n = Narrator(df_basic)
+    with pytest.raises(ValueError):
+        n.compare(pd.DataFrame())
+
+def test_compare_english(df_basic):
+    df2 = df_basic.copy()
+    n = Narrator(df_basic, lang="en")
+    result = n.compare(df2)
+    assert "comparison" in result