Construir un chatbot que responda preguntas sobre la documentación de Hugging Face requiere preparar el entorno, descargar datos y estructurar el proyecto antes de escribir lógica conversacional. Aquí verás cómo inicializar Hasira, el proyecto base que vamos a evolucionar a lo largo del curso usando Langchain, Python y fuentes públicas en formato Markdown.

¿Qué necesitas para inicializar el proyecto Hasira?

Lo primero es clonar el repositorio desde GitHub e instalar dependencias. Tienes tres caminos: Poetry, pip con requirements.txt o conda. Usa el que mejor se adapte a tu flujo.

Si eliges Poetry, el proceso es directo:

1. Clona el repositorio localmente.
2. Ejecuta poetry install para instalar todo el entorno.
3. Corre el chatbot con poetry run python hasira ai_conversation.py.

¿Qué es Poetry y por qué usarlo aquí? Es una herramienta de gestión de dependencias para Python que crea un entorno aislado y reproducible a partir del archivo pyproject.toml. Te evita conflictos de versiones entre librerías.

¿Qué dependencias incluye el pyproject.toml?

El archivo pyproject.toml lista todo lo que vamos a instalar. Estas son las piezas centrales del stack:

• Langchain para orquestar la lógica del chatbot.
• PyTorch y Transformers para modelos de Hugging Face.
• ChromaDB como base de datos vectorial.
• OpenAI para interactuar con sus modelos.
• Requests para llamadas HTTP a las APIs de GitHub.

¿Para qué sirve el archivo utils.py en el proyecto?

Dentro del directorio hasira vas a encontrar utils.py, una librería interna de funciones de utilidad. Es el pegamento que mantiene el código limpio mientras extraes datos y construyes el chatbot.

Estas son las funciones que vale la pena conocer desde el inicio:

• DocsJsonLoader: clase que carga un JSONL (JSON Lines) y lo convierte en documents de Langchain.
• load_config: lee el archivo config.yaml con la configuración global del proyecto.
• get_openai_api_key: verifica que tengas la variable de entorno OPENAI_API_KEY y avisa si falta.
• get_file_path: obtiene la ruta donde se guardan los archivos JSONL.
• get_query_from_user: captura la pregunta del usuario para el chatbot.
• create_dir y remove_existing_file: gestionan directorios y archivos previos.

¿Qué es un archivo JSONL? Es un formato donde cada línea del archivo es un objeto JSON independiente. Permite procesar grandes volúmenes de documentos línea por línea sin cargar todo en memoria.

¿Cómo extraer la documentación de Hugging Face en formato JSONL?

La configuración vive en config.yaml. Ahí defines de qué repositorios de GitHub quieres obtener documentación. En este proyecto extraemos información de cuatro fuentes principales de Hugging Face.

¿Qué fuentes vamos a indexar?

El config.yaml apunta a estos recursos, todos del owner huggingface:

• La librería Transformers, en docs/source/en.
• La librería PEFT.
• La librería Accelerate.
• El blog de Hugging Face, una fuente clave con artículos técnicos.

No estás limitado a estos. Puedes agregar la documentación de PyTorch, TensorFlow o cualquier repo público, siempre que los archivos estén en formato Markdown (.md) o MDX (.mdx). El proyecto ignora código fuente y solo descarga texto editorial.

¿Cómo funciona el script text_extractor?

El script text_extractor procesa el texto y lo deja listo para el chatbot. Cada función tiene un rol claro:

• pre_process_text: limpia el contenido recibido. Por ejemplo, elimina emojis y elementos que no aportan al modelo.
• download_file: recibe una URL, descarga el archivo y lo guarda en JSONL con metadatos como título, owner del repo, nombre del repo y texto.
• process_directory: recorre un directorio completo y decide qué archivos descargar. Solo acepta .md y .mdx.
• main: orquesta todo, valida el token de GitHub y ejecuta las llamadas con requests.

Para ejecutar la extracción, una vez instaladas las dependencias, corre en terminal:

bash poetry run python hasira text_extractor

El script empieza a recorrer carpeta por carpeta y guarda todo en un JSONL fechado dentro del directorio data. Así puedes mantener versiones actualizadas sin sobrescribir descargas anteriores.

¿Cómo lucen los datos descargados y qué hacer con ellos?

Dentro de data vas a ver el JSONL generado con la fecha de descarga. Cada fila es un JSON independiente con campos como título, owner, repositorio de origen y el texto completo del documento.

En una corrida típica el script extrae más de 500 archivos entre documentación y entradas del blog. Vas a ver, por ejemplo, una fila con el README del repo de Hugging Face y otra con un artículo de blog sobre Accelerate y DeepSeek.

¿Puedes usar tus propios datos en lugar de la documentación pública?

Sí, y aquí está lo interesante: el proyecto no te encierra en Hugging Face. Puedes alimentar el chatbot con tus propios textos. Piensa en qué fuentes te servirían para hacerle preguntas: notas internas, manuales, transcripciones.

El pipeline acepta varios formatos:

• Archivos Markdown y MDX desde repositorios públicos.
• Documentos PDF.
• Documentos Word.
• Otros formatos textuales que puedas convertir a JSONL.

Con los datos descargados y el entorno listo, el siguiente paso es transformar estos textos en documents de Langchain para que el modelo pueda consultarlos. ¿Qué fuentes vas a indexar tú en tu versión del proyecto? Cuéntalo en los comentarios.