Preparar MarkAPI para procesamiento asistido por IA con LLaMA/Gemini y utilidades compartidas

[eduranm]

Descripción de funcionalidad

Integrar una nueva capa compartida de utilidades, modelos de dominio y servicios de IA dentro de MarkAPI, para soportar el procesamiento asistido por LLaMA/Gemini, centralizar componentes reutilizables en core, modernizar la configuración base del proyecto y adaptar el módulo reference al nuevo flujo de inferencia y procesamiento.

Criterios de aceptación

• La configuración base del proyecto en config/settings/base.py debe:

  • definir LLAMA_MODEL_DIR apuntando a ROOT_DIR / "model_ai/download";
  • registrar la app model_ai en LOCAL_APPS;
  • actualizar WAGTAIL_SITE_NAME a SciELO XML Tools;
  • definir LLAMA_ENABLED = env.bool("LLAMA_ENABLED", default=True);
  • conservar MODEL_LLAMA = "llama-3.2-3b-instruct-q4_k_m.gguf";
  • definir DATA_UPLOAD_MAX_NUMBER_FIELDS = 10000.

• El enrutamiento en config/urls.py debe:

  • incluir config.api_router en api/v1/;
  • mantener admin/autocomplete/ dentro de i18n_patterns;
  • reemplazar el include específico anterior de mix_citation por el enrutador unificado.

• Deben eliminarse artefactos heredados de la configuración antigua de LLaMA:

  • compose/local/django/Dockerfile.llama;
  • llama.local.yml;
  • llama3/generic_llama.py.

• Debe migrarse la inicialización del paquete antiguo llama3 al nuevo paquete model_ai, incluyendo el nuevo model_ai/__init__.py.

• requirements/base.txt debe incorporar las dependencias necesarias para el nuevo flujo:

  • langid;
  • google-generativeai;
  • python-docx;
  • huggingface_hub;
  • llama-cpp-python.

• Debe existir core/choices.py con constantes centralizadas de dominio:

  • LANGUAGE;
  • ROLE;
  • MONTHS;
  • LICENSE_TYPES;
  • GENDER_CHOICES.

• Los textos traducibles en ROLE, MONTHS, LICENSE_TYPES y GENDER_CHOICES deben estar envueltos con gettext_lazy.

• Debe existir core/utils/utils.py con utilidades reutilizables:

  • language_iso(code);
  • RetryableError;
  • NonRetryableError;
  • fetch_data(url, ...);
  • _get_user(request, username=None, user_id=None).

• fetch_data(url, ...) debe:

  • usar reintentos automáticos con backoff exponencial;
  • reintentar errores de red y HTTP 5xx;
  • no reintentar errores HTTP 4xx;
  • registrar errores de red en logs.

• core/models.py debe incorporar modelos y mixins compartidos reutilizables:

  • Gender;
  • Language;
  • TextWithLang;
  • TextLanguageMixin;
  • RichTextWithLanguage;
  • FlexibleDate;
  • License;
  • LicenseStatement;
  • FileWithLang;
  • LanguageFallbackManager.

• Debe existir la migración core/migrations/0001_initial.py para los modelos concretos de core.

• Los modelos abstractos de core no deben generar tablas propias.

• Debe existir la app model_ai con los siguientes componentes:

  • apps.py;
  • exceptions.py;
  • llama.py;
  • messages.py;
  • models.py;
  • tasks.py;
  • wagtail_hooks.py;
  • migrations/0001_initial.py;
  • migrations/0002_alter_llamamodel_download_status.py.

• model_ai/models.py debe definir el modelo LlamaModel con:

  • name_model;
  • name_file;
  • hf_token;
  • download_status;
  • api_url;
  • api_key_gemini;
  • validación para permitir una sola instancia;
  • widgets enmascarados para credenciales;
  • integración con CoreAdminModelForm.

• model_ai/models.py debe definir DownloadStatus como IntegerChoices con estados:

  • NO_MODEL;
  • DOWNLOADING;
  • DOWNLOADED;
  • ERROR.

• model_ai/tasks.py debe implementar la descarga del modelo desde Hugging Face, actualizar download_status y persistir el resultado.

• model_ai/llama.py debe exponer un servicio de inferencia reutilizable que:

  • inicialice y reutilice una instancia cacheada de LLaMA;
  • valide si LLaMA está habilitado;
  • valide la existencia de un modelo configurado;
  • valide la existencia física del archivo del modelo;
  • permita ejecución en modo chat y prompt;
  • soporte uso de Gemini cuando haya api_key_gemini;
  • reutilice mensajes y formatos desde model_ai/messages.py.

• model_ai/messages.py debe contener prompts y formatos de salida JSON para extracción de:

  • DOI y sección;
  • títulos;
  • autores;
  • afiliaciones;
  • referencias;
  • y primer bloque de metadatos.

• model_ai/wagtail_hooks.py debe registrar la administración de LlamaModel en Wagtail y permitir disparar la descarga del modelo desde el admin.

• reference/api/v1/views.py debe dejar de importar get_reference desde reference.tasks y usar reference.data_utils.

• reference/api/v1/views.py y reference/models.py deben adoptar ReferenceStatus en lugar de valores enteros hardcodeados.

• reference/config.py debe:

  • serializar ejemplos de respuesta como JSON válido;
  • incorporar full_text en los ejemplos;
  • ampliar tipos soportados, incluyendo confproc;
  • ajustar campos como source, location, fpage, lpage y otros equivalentes.

• Debe existir reference/config_gemini.py para configurar prompts y soporte de Gemini en el procesamiento de referencias.

• Debe existir reference/data_utils.py como reemplazo de reference/tasks.py.

• reference/marker.py debe dejar de depender de llama3.generic_llama y usar la nueva implementación en model_ai.llama.

• reference/wagtail_hooks.py debe ajustarse al nuevo flujo de snippets y a la integración con tareas/modelos de IA.

• Las migraciones de reference deben quedar actualizadas:

  • 0001_initial.py;
  • 0002_alter_elementcitation_score.py;
  • 0003_elementcitation_marked_xml.py.

• Los catálogos de traducción deben actualizarse en:

  • locale/en/LC_MESSAGES/django.po;
  • locale/es/LC_MESSAGES/django.po;
  • locale/pt_BR/LC_MESSAGES/django.po;
    para incluir las nuevas cadenas introducidas por core y model_ai.

• Todos los archivos nuevos o modificados deben finalizar con salto de línea (\n) cuando corresponda.

Anexos

• Archivos modificados o agregados en este alcance:

  • Configuración e infraestructura:

    • config/settings/base.py
    • config/urls.py
    • local.yml
    • requirements/base.txt
    • compose/local/django/Dockerfile.llama
    • llama.local.yml

  • Dominio compartido:

    • core/choices.py
    • core/models.py
    • core/utils/utils.py
    • core/migrations/0001_initial.py

  • Nueva app de IA:

    • model_ai/__init__.py
    • model_ai/apps.py
    • model_ai/exceptions.py
    • model_ai/llama.py
    • model_ai/messages.py
    • model_ai/models.py
    • model_ai/tasks.py
    • model_ai/wagtail_hooks.py
    • model_ai/migrations/0001_initial.py
    • model_ai/migrations/0002_alter_llamamodel_download_status.py
    • model_ai/migrations/__init__.py

  • Refactor de referencias:

    • reference/api/v1/views.py
    • reference/config.py
    • reference/config_gemini.py
    • reference/data_utils.py
    • reference/marker.py
    • reference/models.py
    • reference/wagtail_hooks.py
    • reference/migrations/0001_initial.py
    • reference/migrations/0002_alter_elementcitation_score.py
    • reference/migrations/0003_elementcitation_marked_xml.py

  • Limpieza de implementación anterior:

    • llama3/generic_llama.py

  • Internacionalización:

    • locale/en/LC_MESSAGES/django.po
    • locale/es/LC_MESSAGES/django.po
    • locale/pt_BR/LC_MESSAGES/django.po

Referencias

• Django settings
• Django migrations
• Django i18n
• Wagtail snippets y admin hooks
• Hugging Face Hub
• llama-cpp-python
• Google Generative AI
• python-docx