🇪🇸 Castellano | 🇺🇸 English

SmartMule es un servicio automatizado de organización y seguridad diseñado para transformar el caos de las descargas P2P (eMule, aMule, etc.) en una biblioteca perfectamente estructurada. Utiliza vigilancia del sistema de archivos, hashing criptográfico (ED2K) e Inteligencia Artificial para clasificar, limpiar y proteger tu equipo de amenazas camufladas.

Por defecto, eMule deposita todas las descargas finalizadas en una única carpeta Incoming. Con el tiempo, este directorio se convierte en un caos de películas, software, música y archivos con nombres crípticos.

SmartMule soluciona este problema identificando, limpiando y moviendo cada archivo a su categoría temática correspondiente de forma automática, manteniendo tu biblioteca organizada sin esfuerzo manual.

• Vigilancia Activa (Watchdog): Detecta archivos nuevos en tu carpeta Incoming al instante.

• Doble Capa de Verificación: Identifica archivos por su nombre (IA) y por su contenido (Hash ED2K / Fingerprint).

• Soporte de Directorios (Folder Grouping): SmartMule detecta si una descarga es una carpeta (ej: película con subtítulos). Identifica el archivo principal para el hashing y los metadatos, pero mueve y renombra toda la carpeta como una única unidad funcional.

• Antimalware Semántico (Triaje de Élite): Inspección profunda de archivos sin extracción usando VirusTotal. SmartMule no se fía de nadie:

  • Análisis de Macros: Detecta documentos de Office con macros (.xlsm, .docm, etc.) y formatos antiguos (.doc, .xls) tratándolos como ejecutables.
  • Vigilancia de PDF: Escaneo automático de archivos PDF ante scripts maliciosos.
  • Inspección de Contenedores: El ArchiveInspector analiza archivos .zip, .rar y .7z buscando inconsistencias (ej: un .exe disfrazado de película) y mostrando el contenido sospechoso en los logs.
  • Puntuaciones Críticas: Si un archivo tiene más de 5 detecciones en VT (priorizando motores TOP como Microsoft o Kaspersky), lo mueve a Review para evitar riesgos.

• Desempate Inteligente (Tie-Breaking): Usa el año de estreno para distinguir entre películas homónimas (ej: Solaris 1972 vs Solaris 2002).

• Triaje Automático:

  • MALICIOUS: Borrado automático destructivo.
  • SUSPICIOUS: Cuarentena para revisión manual.
  • SAFE: Organización temática automatizada.

  

• Privacidad: Compatible con modelos locales (LM Studio) para procesar nombres sin subirlos a la nube.

• Gasto de recursos muy bajo: SmartMule está diseñado para ejecutarse en segundo plano sin interferir con el uso normal del PC. Para ello, establece una prioridad de I/O (IOPRIO_VERYLOW) y CPU (IDLE_PRIORITY_CLASS) mínimas, de forma que el SO solo asigna recursos al proceso cuando no hay otras aplicaciones demandándolos.

SmartMule permite elegir cómo se gestionan los archivos físicamente mediante la variable ORGANIZER_MODE en el archivo .env:

Instala las librerías necesarias con:

pip install -r requirements.txt

Para el análisis de archivos y desempate de películas, SmartMule requiere:

• FFmpeg (ffprobe): Necesario para extraer la resolución y metadatos técnicos de los videos.

  • Windows: Descarga de ffmpeg.org, extrae el .zip y añade la carpeta bin al PATH de tu sistema.
  • Linux: sudo apt install ffmpeg

• 7-Zip / Patool: Necesario para inspeccionar archivos comprimidos.

  • Windows: Instala 7-Zip y asegúrate de que esté en el PATH.
  • Linux: sudo apt install p7zip-full

1. Monitorización: El Watcher detecta el archivo e inicia una espera de desbloqueo (I/O unlock).

2. Caché Inteligente: Se calcula una "Fingerprint" rápida. Si el archivo ya existe y el mtime (modification time) no ha cambiado, se reutilizan los metadatos para ahorrar APIs.

3. Análisis Semántico: Si es un contenedor, el ArchiveInspector busca amenazas antes de que el usuario lo abra.

4. Capa IA (LLM): Limpia el nombre "sucio" de la Scene y detecta el tipo de medio (Cine, Música, Libros, Software, etc.).

5. Enriquecimiento (API): Consulta TMDB u OpenLibrary usando el año y metadatos técnicos para un emparejamiento preciso.

6. Organización: El LibraryOrganizer mueve el archivo a su destino final (ej: /Library/Movies_and_Series/Matrix (1999).mkv).

SmartMule está diseñado para ejecutarse una sola vez y quedarse vigilando permanentemente de forma completamente invisible.

• Arrancar (Modo Invisible):

  • Windows: Haz doble clic en el archivo smartmule_launcher.vbs. Recomiendo colocar un acceso directo en tu carpeta de Autoinicio (shell:startup).

  • Linux: Ejecuta ./smartmule_launcher.sh. Este script usa nohup para que el proceso siga vivo aunque cierres la terminal.

• Detener: Ejecuta python3 main.py stop. SmartMule detectará el proceso oculto y lo cerrará limpiamente.

  

• Auditoría: Toda la actividad silenciosa quedará registrada en el archivo smartmule.log. Puedes ver las últimas líneas rápidamente con:

  python main.py --log      # Muestra las últimas 30 líneas (por defecto)
  python main.py --log 100  # Muestra las últimas 100 líneas

  O seguirlo en tiempo real en Windows:

  Get-Content smartmule.log -Wait -Encoding UTF8

  

• Inventario y Estadísticas: Para ver rápidamente qué archivos están registrados en la biblioteca, el desglose por categorías (Películas, Libros, etc.) y el tamaño total ocupado, usa el flag --stats. Para verificar el estado de salud y dependencias del sistema, usa --status. Si quieres verificar qué rutas y APIs tienes activas, usa --config:

  python main.py --stats     # Ver estadísticas
  python main.py --status    # Chequear salud del sistema
  python main.py --config    # Ver configuración activa

  

Para evitar escribir la ruta del entorno virtual cada vez que quieras usar la CLI, puedes crear un alias en tu terminal:

1. Abre tu configuración: nano ~/.bashrc

2. Pega esta línea al final (ajusta la ruta si es necesario):

   alias smartmule='/home/user/SmartMule/venv/bin/python3 /home/user/SmartMule/main.py'

3. Recarga la configuración: source ~/.bashrc

Si quieres que el comando smartmule funcione tanto en PowerShell como en CMD:

1. Crea un archivo llamado smartmule.bat en una carpeta que esté en tu PATH (ej: C:\Windows).

2. Pega este contenido dentro (ajusta las rutas a tu instalación):

   @echo off
   C:\SmartMule\venv\Scripts\python.exe C:\SmartMule\main.py %*

3. ¡Listo! Ahora puedes usar los comandos simplificados desde cualquier terminal.

Una vez configurado el alias, podrás usar desde cualquier terminal:

• smartmule start (Arranca el motor de SmartMule)
• smartmule stop (Detiene el servicio)
• smartmule --stats (Ver inventario y estadísticas de almacenamiento)
• smartmule --status (Ver salud y dependencias del sistema)
• smartmule --config (Ver rutas y configuración de APIs activas)
• smartmule --purge "Nombre" (Borrar archivos)
• smartmule --debug (Arranca con logs detallados de IA)
• smartmule --pid (Muestra el PID del proceso activo)

Cuando usas el modo hardlink (predeterminado), borrar un archivo de tu biblioteca no lo borra físicamente del disco si aún existe en la carpeta Incoming (y viceversa). Esto es necesario para seguir compartiendo como cliente eMule (y ganar créditos en la red), pero puede ser tedioso de limpiar.

Para facilitar la limpieza total, SmartMule incluye un comando de purga/eliminación de archivos:

• Purga Selectiva: Busca archivos por nombre, comodines (Wildcards) o expresiones regulares (Regex).

  python main.py --purge "nombre*"  # Encuentra archivos que empiecen por "nombre"
  python main.py --purge ".*\.mkv$" # Encuentra todos los archivos con extensión .mkv

• Explorador Interactivo: Si ejecutas el comando sin términos de búsqueda, SmartMule te mostrará la lista completa de tu biblioteca para que elijas qué eliminar.

  python main.py --purge

Ejemplo de uso:

• Modo Destructivo (Limpieza Total): ⚠️⚠️ Borra absolutamente todos los archivos registrados en la base de datos de un solo golpe.

  python main.py --purge --all --no-preserve

  Nota: Este comando requiere una confirmación de texto (escribir "BORRAR TODO") por seguridad.

Para mayor comodidad, SmartMule despliega automáticamente herramientas de acceso directo dentro de tu carpeta de biblioteca (LIBRARY_PATH):

• Windows: Usa Purga_Interactiva.bat.
• Linux: Usa purga_interactiva.sh.

Solo tienes que ejecutar el archivo correspondiente para buscar y eliminar archivos sin tener que recordar comandos complejos:

Para no perder visibilidad en la red ni dejar de ganar créditos tras la organización de tus archivos, sigue estos pasos:

1. Compartir Biblioteca: Ve a eMule > Opciones > Directorios y marca la carpeta Library como directorio compartido (asegúrate de incluir sus subcarpetas).

2. Privacidad: No compartas la carpeta raíz de SmartMule, solo la carpeta Library. SmartMule guarda su base de datos en una carpeta oculta (.data) para que eMule no la indexe.

3. Mantener Créditos: Tus créditos están asociados a tu User Identification (Hash), no a los nombres de los archivos. Al compartir la Library con los archivos ya limpios y renombrados, eMule reconocerá que tienes el mismo contenido (mismo Hash ED2K) y seguirás sumando prioridad de subida.

SmartMule es totalmente compatible con gestores de descargas Torrent. Debido a que las redes Torrent detienen el seeding (compartir) si cambias el archivo de sitio, SmartMule usa por defecto la creación de Hardlinks para los archivos de estas redes, asegurando que puedas seguir compartiendo (Seeding) los archivos sin interrupciones.

1. Ajustes de Extensiones (Crucial): Para prevenir que SmartMule procese archivos sin terminar, es obligatorio que actives la opción de de tu cliente de Torrent para agregar una extensión a las descargas incompletas. (Ej. Append .!ut to incomplete files en uTorrent o Añadir !qB a descargas incompletas en qBittorrent).

   

2. Mismo Disco: Los Hardlinks exigen que la carpeta Incoming y la Library estén en la misma partición del sistema o disco duro.

3. Configuración de Modo: Puedes alterar el comportamiento modificando la variable ORGANIZER_MODE en tu .env (hardlink por defecto, pudiendo elegir copy o move).

SmartMule cuenta con una suite de pruebas para garantizar la estabilidad:

pytest -v --tb=short

SmartMule incluye un motor de hashing ED2K de alto rendimiento diseñado para no saturar tu sistema, que reduce el tiempo de cálculo del hash de forma exponencial:

• Arquitectura Híbrida: Lectura secuencial de disco (IOPRIO_VERYLOW) combinada con cálculo paralelo mediante hilos (multi-threading)

• Control de RAM: Sistema de Backpressure que garantiza un consumo de memoria mínimo y constante (~55MB), sin importar si procesas un archivo de 1GB o una ISO de 200GB.

• Cortesía con el SO: Ajusta automáticamente la prioridad de la CPU (IDLE) y limita el uso al 50% de tus núcleos, asegurando que el sistema sea totalmente fluido incluso durante tareas intensivas.