Generación del diccionario de datos para archivos de Excel utilizando agentes OpenPyXL y AI

Todas las empresas para la que trabajé hasta hoy, allí estaba: la Resiliente MS Excel.

Excel se lanzó por primera vez en 1985 y se ha mantenido fuerte hasta hoy. Ha sobrevivido al surgimiento de bases de datos relacionales, la evolución de muchos lenguajes de programación, Internet con su infinito número de aplicaciones en línea y, finalmente, también está sobreviviendo a la era de la IA.

¡Uf!

¿Tiene alguna duda sobre cuán resiliente es Excel? No.

Creo que la razón de eso es su practicidad para comenzar y manipular un documento rápidamente. Piense en esta situación: estamos en el trabajo, en una reunión, y de repente el liderazgo comparte un archivo CSV y solicita un cálculo rápido o algunos números calculados. Ahora, las opciones son:

1. Abra un IDE (o un cuaderno) y comience a codificar como una locura para generar un gráfico de matlotlib simple;

2. Open Power BI, importe los datos y comience a crear un informe con gráficos dinámicos.

3. Abra el CSV en Excel, escriba un par de fórmulas y cree un gráfico.

No puedo hablar por ti, pero muchas veces voy por la opción 3. Especialmente porque los archivos de Excel son compatibles con todo, fácilmente compartibles y amigables para los principiantes.

Estoy diciendo todo esto como una introducción para expresar mi punto de que no creo que los archivos de Excel desaparezcan pronto, incluso con el rápido desarrollo de la IA. A muchos les encantará eso, muchos odiarán eso.

Entonces, mi acción aquí fue aprovechar la IA para hacer que los archivos de Excel sean mejor documentados. Una de las principales quejas de los equipos de datos sobre Excel es la falta de mejores prácticas y reproducibilidad, dado que los nombres de las columnas pueden tener cualquier nombre y tipo de datos, pero cero documentación.

Entonces, he creado un agente de IA que lee el archivo de Excel y crea esta pequeña documentación. Así es como funciona:

El archivo de Excel se convierte en CSV y se alimenta al modelo de idioma grande (LLM).

El agente de IA genera el diccionario de datos con información de columna (nombre de variable, tipo de datos, descripción).

El diccionario de datos se agrega como comentarios al encabezado del archivo de Excel.

Archivo de salida guardado con comentarios.

De acuerdo. AHORA AHORA. Hagamos eso en este tutorial.

Código

¡Codifiquemos! | Imagen generada por AI. Meta Llama, 2025. Https://meta.ai

Comenzaremos configurando un entorno virtual. Crear un venv Con la herramienta de su elección, como poesía, Python Venv, Anaconda o UV. Realmente me gusta UV, ya que es el más rápido y el más simple, en mi opinión. Si tiene instalado UV [5]abra una terminal y cree su venv.

uv init data-docs
cd data-docs
uv venv
uv add streamlit openpyxl pandas agno mcp google-genai

Ahora, importemos los módulos necesarios. Este proyecto fue creado con Python 3.12.1, pero creo que Python 3.9 o superior ya podría hacer el truco. Usaremos:

Agno: para la gestión del agente de IA
OpenPyxl: para la manipulación de archivos de Excel
Racionalizar: para la interfaz front-end.
Pandas, OS, JSON, Dedent y Google Genai como módulos de soporte.

# Imports
import os
import json
import streamlit as st
from textwrap import dedent

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.file import FileTools

from openpyxl import load_workbook
from openpyxl.comments import Comment
import pandas as pd

Excelente. El siguiente paso es crear las funciones que necesitaremos para manejar los archivos de Excel y crear el agente AI.

Observe que todas las funciones tienen detalladas cajas. Esto es intencional porque los LLM usan documentos para saber qué hace una función determinada y decidir si usarla o no como una herramienta.

Entonces, si está utilizando las funciones de Python como herramientas para un agente de IA, asegúrese de usar documentos detallados. Hoy en día, con copilotos gratuitos como Windsurf [6] Es aún más fácil crearlos.

Convertir el archivo a CSV

Esta función:

Tome el archivo de Excel y lea solo las primeras 10 filas. Esto es suficiente para enviar a la LLM. Al hacer eso, también estamos evitando enviar demasiados tokens como entrada y hacer que este agente sea demasiado costoso.
Guarde el archivo como CSV para usar como entrada para el agente AI. El formato CSV es más fácil para el modelo, ya que es un montón de texto separado por comas. Y sabemos que LLMS brilla trabajando con texto.

Aquí está la función.

def convert_to_csv(file_path:str):
   """
    Use this tool to convert the excel file to CSV.

    * file_path: Path to the Excel file to be converted
    """
   # Load the file  
   df = pd.read_excel(file_path).head(10)

   # Convert to CSV
   st.write("Converting to CSV... :leftwards_arrow_with_hook:")
   return df.to_csv('temp.csv', index=False)

Sigamos adelante.

Creando el agente

La siguiente función crea el agente AI. Estoy usando Agno [1]ya que es muy versátil y fácil de usar. También elegí el modelo Gemini 2.0 Flash. Durante la fase de prueba, este fue el modelo de mejor rendimiento que generó los documentos de datos. Para usarlo, necesitará una clave API de Google. No olvides conseguir uno aquí [7].

La función:

Recibe la salida CSV de la función anterior.
Pasa a través del agente AI, que genera el diccionario de datos con el nombre de la columna, la descripción y el tipo de datos.
Observe que el description El argumento es el aviso para el agente. Hazlo detallado y preciso.
El diccionario de datos se guardará como un JSON Archivo utilizando una herramienta llamada FileTools que pueden leer y escribir archivos.
He configurado retries=2 Entonces podemos transmitir cualquier error en un primer intento.

def create_agent(apy_key):
    agent = Agent(
        model=Gemini(id="gemini-2.0-flash", api_key=apy_key),
        description= dedent("""\
                            You are an agent that reads the temp.csv dataset presented to you and 
                            based on the name and data type of each column header, determine the following information:
                            - The data types of each column
                            - The description of each column
                            - The first column numer is 0

                            Using the FileTools provided, create a data dictionary in JSON format that includes the below information:
                            {<ColNumber>: {ColName: <ColName>, DataType: <DataType>, Description: <Description>}}

                            If you are unable to determine the data type or description of a column, return 'N/A' for that column for the missing values.
                            \
                            """),
        tools=[ FileTools(read_files=True, save_files=True) ],
        retries=2,
        show_tool_calls=True
        )

    return agent

De acuerdo. Ahora necesitamos otra función para guardar el diccionario de datos en el archivo.

Agregar diccionario de datos al encabezado del archivo

Esta es la última función que se creará. Va a:

Obtenga el diccionario de datos json Desde el paso anterior y el archivo de Excel original.
Agregue el diccionario de datos al encabezado del archivo como comentarios.
Guarde el archivo de salida.
Una vez que se guarda el archivo, muestra un botón de descarga para que el usuario obtenga el archivo modificado.

def add_comments_to_header(file_path:str, data_dict:dict="data_dict.json"):
    """
    Use this tool to add the data dictionary {data_dict.json} as comments to the header of an Excel file and save the output file.

    The function takes the Excel file path as argument and adds the {data_dict.json} as comments to each cell
    Start counting from column 0
    in the first row of the Excel file, using the following format:    
        * Column Number: <column_number>
        * Column Name: <column_name>
        * Data Type: <data_type>
        * Description: <description>

    Parameters
    ----------
    * file_path : str
        The path to the Excel file to be processed
    * data_dict : dict
        The data dictionary containing the column number, column name, data type, description, and number of null values

    """
    
    # Load the data dictionary
    data_dict = json.load(open(data_dict))

    # Load the workbook
    wb = load_workbook(file_path)

    # Get the active worksheet
    ws = wb.active

    # Iterate over each column in the first row (header)
    for n, col in enumerate(ws.iter_cols(min_row=1, max_row=1)):
        for header_cell in col:
            header_cell.comment = Comment(dedent(f"""\
                              ColName: {data_dict[str(n)]['ColName']}, 
                              DataType: {data_dict[str(n)]['DataType']},
                              Description: {data_dict[str(n)]['Description']}\
    """),'AI Agent')

    # Save the workbook
    st.write("Saving File... :floppy_disk:")
    wb.save('output.xlsx')

    # Create a download button
    with open('output.xlsx', 'rb') as f:
        st.download_button(
            label="Download output.xlsx",
            data=f,
            file_name='output.xlsx',
            mime='application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
        )

De acuerdo. El siguiente paso es pegar todo esto en un script frontal a pie.

Front-end

En este paso, podría haber creado un archivo diferente para el front-end e importado las funciones allí. Pero decidí usar el mismo archivo, así que comencemos con lo famoso:

if __name__ == "__main__":

Primero, un par de líneas para configurar la página y los mensajes que se muestran en la aplicación web. Usaremos el contenido centered en la página, y hay información sobre cómo funciona la aplicación.

# Config page Streamlit
    st.set_page_config(layout="centered", 
                       page_title="Data Docs", 
                       page_icon=":paperclip:",
                       initial_sidebar_state="expanded")
    
    # Title
    st.title("Data Docs :paperclip:")
    st.subheader("Generate a data dictionary for your Excel file.")
    st.caption("1. Enter your Gemini API key and the path of the Excel file on the sidebar.")
    st.caption("2. Run the agent.")
    st.caption("3. The agent will generate a data dictionary and add it as comments to the header of the Excel file.")
    st.caption("ColName: <ColName> | DataType: <DataType> | Description: <Description>")
    
    st.divider()

A continuación, configuraremos la barra lateral, donde el usuario puede ingresar su tecla API desde Google y seleccionar un .xlsx archivo para ser modificado.

Hay un botón para ejecutar la aplicación, otra para restablecer el estado de la aplicación y una barra de progreso. Nada demasiado elegante.

with st.sidebar:
        # Enter your API key
        st.caption("Enter your API key and the path of the Excel file.")
        api_key = st.text_input("API key: ", placeholder="Google Gemini API key", type="password")
        
        # Upload file
        input_file = st.file_uploader("File upload", 
                                       type='xlsx')
        

        # Run the agent
        agent_run = st.button("Run")

        # progress bar
        progress_bar = st.empty()
        progress_bar.progress(0, text="Initializing...")

        st.divider()

        # Reset session state
        if st.button("Reset Session"):
            st.session_state.clear()
            st.rerun()

Una vez que el correr Se hace clic en el botón, desencadena el resto del código para ejecutar el agente. Aquí está la secuencia de pasos realizados:

Se llama a la primera función para transformar el archivo en CSV
El progreso está registrado en la barra de progreso.
Se crea el agente.
Barra de progreso actualizada.
Un aviso se alimenta al agente para leer el temp.csv Archivo, cree el diccionario de datos y guarde la salida para data_dictionary.json.
El diccionario de datos se imprime en la pantalla, por lo que el usuario puede ver lo que se generó mientras se guarda en el archivo de Excel.
El archivo de Excel se modifica y se guarda.

# Create the agent
    if agent_run:
        # Convert Excel file to CSV
        convert_to_csv(input_file)

        # Register progress
        progress_bar.progress(15, text="Processing CSV...")

        # Create the agent
        agent = create_agent(api_key)

        # Start the script
        st.write("Running Agent... :runner:")

        # Register progress
        progress_bar.progress(50, text="AI Agent is running...")

        # Run the agent    
        agent.print_response(dedent(f"""\
                                1. Use FileTools to read the temp.csv as input to create the data dictionary for the columns in the dataset. 
                                2. Using the FileTools tool, save the data dictionary to a file named 'data_dict.json'.
                                \
                                """),
                        markdown=True)

        # Print the data dictionary
        st.write("Generating Data Dictionary... :page_facing_up:")
        with open('data_dict.json', 'r') as f:
            data_dict = json.load(f)
            st.json(data_dict, expanded=False)

        # Add comments to header
        add_comments_to_header(input_file, 'data_dict.json')

        # Remove temporary files
        st.write("Removing temporary files... :wastebasket:")
        os.remove('temp.csv')
        os.remove('data_dict.json')    
    
    # If file exists, show success message
    if os.path.exists('output.xlsx'):
        st.success("Done! :white_check_mark:")
        os.remove('output.xlsx')

    # Progress bar end
    progress_bar.progress(100, text="Done!")

Eso es todo. Aquí hay una demostración del agente en acción.

Documentos de datos agregados a su archivo de Excel. Imagen del autor.

¡Hermoso resultado!

Probar

Puede probar la aplicación implementada aquí: https://excel-datadocs.streamlit.app/

Antes de que te vayas

En mi humilde opinión, los archivos de Excel no desaparecerán pronto. Amarlos o odiarlos, tendremos que seguir con ellos por un tiempo.

Los archivos de Excel son versátiles, fáciles de manejar y compartir, por lo que todavía son muy útiles para la rutina ad-hoc tareas en el trabajo.

Sin embargo, ahora podemos aprovechar la IA para ayudarnos a manejar esos archivos y mejorarlos. Inteligencia artificial está tocando tantos puntos de nuestras vidas. La rutina y las herramientas en el trabajo son solo otra.

¡Aprovechemos la IA y trabajemos más inteligente todos los días!

Si te gustó este contenido, encuentre más de mi trabajo en mi sitio web y GitHub, compartido a continuación.