Wizard404

Wizard404 centraliza la busqueda y gestion de documentos (PDF, texto, Office, imagenes, audio, video): escanear directorios, buscar por contenido, organizar y hasta limpiar el equipo de archivos

Comment

Inspiración

Las herramientas que usamos a diario, como mole o los gestores de archivos clásicos, no ofrecen una forma satisfactoria de explorar directorios a fondo, y mucho menos de organizarlos. Durante mucho tiempo, la única opción era la terminal: ls, cd y find; potentes, pero no diseñadas para "encontrar este documento por lo que dice" o "ver lo desordenada que está esta carpeta". Queríamos un único lugar para escanear carpetas, buscar por contenido (no solo por nombre de archivo), organizar por tipo o fecha, y limpiar cachés y registros, tanto desde la terminal como desde el navegador. Aquí es donde entra en juego Wizard404.

Qué hace

Wizard404 te permite escanear los directorios de tu equipo, ver estadísticas por tipo y tamaño de archivo, y obtener un resumen de entropía (qué tan desordenada está una carpeta). Los directorios que ya están organizados no necesitan Wizard404; los que están desordenados reciben un mensaje claro y se desglosan por extensión o directorio.

Puedes importar documentos a un índice (PDF, texto, Office, imágenes y más). Una vez indexados, puedes buscar por palabras clave, con una búsqueda semántica opcional (incrustaciones) para que "contrato" coincida con "acuerdo" en el contenido. Los resultados muestran metadatos (título, autor, tipo, tamaño, fecha) y puedes abrir el documento y leer un resumen automático.

Organizar mueve archivos a carpetas por tipo, fecha o tamaño (p. ej., "colocar todos los PDF con la palabra 'factura' en el nombre en una carpeta llamada Importante"). Limpiar encuentra directorios de caché, archivos de registro, archivos pequeños y duplicados (excepto código/configuración) y te permite revisar y eliminar solo lo que elijas.

Hay una CLI (w404) para usuarios avanzados (menús TUI y comandos directos) y una aplicación web con estilo pixel art de 16 bits y un asistente virtual (el Asistente) que comenta los resultados del análisis y el estado de tus archivos, con algún comentario informal.

Cómo lo creamos

  • Backend: Python 3.10+, FastAPI, SQLAlchemy, SQLite (predeterminado) o PostgreSQL. Un núcleo reutilizable (wizard404_core) gestiona el descubrimiento, la extracción (PDF, Office, texto, imágenes), la búsqueda, la búsqueda semántica (transformadores de oraciones/all-MiniLM-L6-v2) y los resúmenes. Sin dependencia del framework en el núcleo.
  • API: Puntos finales REST para autenticación, documentos (lista, búsqueda, importación, carga, detalle, resumen, reindexación de incrustaciones) y escaneo (estadísticas de directorio, archivos por extensión). Autenticación JWT; documentos con alcance de usuario.
  • CLI: Python, Typer, Rich, Simple Term Menu. Comandos: escaneo, importación, búsqueda, exploración, organización, limpieza. Interfaz de usuario interactiva con estados de carga y lanzador de backend opcional.
  • Frontend: React 19, Vite 7, Tailwind 4. Cliente API único (services/api.js), autenticación mediante token en localStorage, escaneo/importación/búsqueda/exploración/detalle del documento. Interfaz de usuario pixel art, fondo con paralaje, interruptor de superposición CRT, Mage (Asistente) fijo en la esquina inferior derecha. Desplazamiento solo en páginas con mucho contenido (escaneo, exploración, resultados de búsqueda, detalle del documento).

Mantuvimos el núcleo independiente para que la misma lógica se ejecute en la API y la CLI, y pueda reutilizarse como biblioteca.

Desafíos encontrados

  • La búsqueda semántica siempre devuelve los mismos resultados: Inicialmente, solo se devolvían documentos con incrustaciones, y muchos documentos tenían incrustaciones similares (p. ej., tmp*.md). Lo solucionamos (1) usando texto más enriquecido para las incrustaciones (título, nombre, vista previa, prefijo del contenido completo), (2) incluyendo documentos sin incrustaciones en los resultados (después de aquellos con incrustaciones) y (3) añadiendo la acción "Reindexar incrustaciones" para que los documentos existentes obtengan nuevos vectores.
  • Ruido en la terminal: Bibliotecas como Pillow/libtiff escribieron "Ignorando objeto apuntando erróneo" y PIL "Advertencia de metadatos, etiqueta 33723" en la salida estándar. Los eliminamos redirigiendo fd 2 a devnull durante el escaneo/importación y registrando filtros de advertencia globales para PIL en el extractor de imágenes.
  • Superposición CRT que afecta los clics y el diseño: Aplicar un filtro CSS al contenido principal hizo que position: fixed (por ejemplo, Mage) se comportara en relación con el contenedor filtrado e interrumpió las pruebas de aciertos. Trasladamos Mage fuera del contenedor filtrado y añadimos una capa de reenvío de eventos con mapeo de barril inverso para que los clics se ubiquen donde el usuario ve el botón.
  • Manteniendo los servicios y la interfaz de usuario separados: Refactorizamos el frontend para que todo el HTTP resida en services/api.js y los componentes solo consuman esa API, con una clara separación entre servicios y componentes de presentación.

Logros de los que nos sentimos orgullosos

  • Una base de código, dos interfaces: La misma API respalda la CLI y la aplicación web; puedes escanear, importar, buscar y explorar desde la terminal o el navegador.
  • Búsqueda semántica que varía con la consulta: Con incrustaciones y reindexación, al cambiar la frase de búsqueda, se modifica el orden y la relevancia de los resultados.
  • Entropía y desglose: El resumen del escaneo indica el grado de desorden de un directorio y permite explorar por extensión o por directorio, con anidación.

Built With

Share this project:

Updates