docs: estrutura Wiki de tutoriais e configuração de APIs de IA by Rossi-Luciano · Pull Request #36 · scieloorg/markapi

Rossi-Luciano · 2025-10-28T14:25:06Z

O que esse PR faz?

Este PR implementa melhorias em documentação e configuração do sistema:

Documentação estruturada via Wiki:
- Adiciona página principal com visão geral do sistema e público-alvo
- Cria fluxograma visual do processo com legenda explicativa
- Estrutura tutoriais organizados (Instalação, Processamento, Validação)
- Padroniza terminologia ("conversão" → "processamento")
Configuração de APIs de IA:
- Adiciona suporte a Hugging Face (HF_TOKEN)
- Habilita integração com Llama (LLAMA_ENABLED)
- Configura Google Gemini API (GEMINI_API_KEY)
Padronização de código:
- Ajusta formatação PEP8 em xml_manager/models.py
- Corrige quebras de linha em ForeignKeys
- Remove espaços em branco desnecessários

Onde a revisão poderia começar?

Documentação Wiki:

Página principal (Home)
Fluxograma do processo (verificar renderização Mermaid)
Links entre páginas de tutoriais
Consistência terminológica em todas as páginas

Arquivos de código:

/.envs/.local/.django
- Validar se as chaves de API devem estar versionadas (considerar usar secrets)
- Verificar configuração padrão LLAMA_ENABLED=True
/xml_manager/models.py
- Classes XMLDocument, XMLDocumentPDF, XMLDocumentHTML
- Métodos create() reformatados

Como este poderia ser testado manualmente?

Documentação:

Acessar Wiki do repositório
Navegar pela estrutura de páginas
Testar todos os links internos
Verificar renderização do fluxograma Mermaid

Código:

Verificar carregamento das variáveis de ambiente:

   python manage.py shell
   >>> from django.conf import settings
   >>> print(settings.HF_TOKEN)
   >>> print(settings.LLAMA_ENABLED)
   >>> print(settings.GEMINI_API_KEY)

Executar testes existentes:

   python manage.py test xml_manager

Algum cenário de contexto que queira dar?

Documentação:

Desenvolvida para público-alvo com diferentes níveis técnicos
Estrutura segue fluxo natural: Instalação → Processamento → Validação
Terminologia padronizada para facilitar compreensão

Quais são tickets relevantes?

NA

Referências

… principales

… de nuevas apps y aumento del límite de campos

…s, textos con idioma y manejo flexible de fechas

…ón de referencias

…s y ampliación de tipos soportados (confproc, full_text, etc.)

…e model_ai

… model_ai)

…rga de modelos

…ai y python-docx

…istas de búsqueda, utilidades y hooks de Wagtail

…o, utilidades y hooks de Wagtail

…ones OMML a MathML

…es de inferencia, tareas y hooks de Wagtail

…s de procesamiento de datos

…ial.py y eliminación de migraciones intermedias

…n de Django y traducción de verbose_name a inglés

Corrige el tipo de excepción para responder 404 cuando el registro no existe.

…nlaces Reduce ruido en logs y mantiene la función enfocada a su retorno.

Mejora legibilidad y buenas prácticas de manejo de errores.

…a prompt de referencias Se agregan comillas a campos textuales y se corrigen comas/keys para evitar errores de parseo del prompt.

Permite traducción de 'Mixed Citation' y 'Rating from 1 to 10'.

…en save()

…eference status' (incluye migraciones)

- function_llama passou a ser LlamaInputSettings em llama.py - generic_llama passou a ser llama.py com LlamaService

Copilot

Pull Request Overview

This pull request introduces a comprehensive document markup and XML generation system for processing DOCX files and managing references. The PR adds new applications (markup_doc and model_ai) with AI-powered metadata extraction, reference parsing, and XML/HTML generation capabilities. Key changes include renaming menu identifiers from xml_manager to xml_files and xml_manager admin group consolidation, adding new dependencies for AI processing (Google Generative AI, python-docx, langid), and implementing a complete workflow for converting DOCX documents to SciELO-compliant XML.

Key Changes

Added markup_doc app with DOCX processing, AI-based labeling, XML generation, and SciELO package creation
Added model_ai app for managing LLM models (Llama/Gemini) with download capabilities
Renamed XML manager menu from xml_manager to xml_files and consolidated menu structure
Added new package dependencies: google-generativeai, python-docx, and langid

Reviewed Changes

Copilot reviewed 59 out of 70 changed files in this pull request and generated 91 comments.

Show a summary per file

File	Description
requirements/base.txt	Added AI processing dependencies (google-generativeai, langid, python-docx)
xml_manager/wagtail_hooks.py	Renamed menu identifiers and consolidated menu structure for XML management
reference/wagtail_hooks.py	Refactored import statements and renamed admin class with menu order adjustment
reference/models.py	Added ReferenceStatus enum and replaced `estatus` with `status` field
reference/marker.py	Updated imports to use new `model_ai.llama` module
reference/data_utils.py	Enhanced error handling and updated to use ReferenceStatus enum
model_ai/*	New app for managing AI models with Llama/Gemini integration
markup_doc/*	New app for DOCX processing, metadata extraction, and XML generation
markuplib/*	New library for DOCX processing and OMML to MathML conversion

Comments suppressed due to low confidence (1)

markup_doc/sync_api.py:108

Except block directly handles BaseException.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-30T11:48:05Z

reference/config.py

-                'uri': {'type': 'string'},
-                'access_date': {'type': 'string'},
-                'version': {'type': 'string'},
+                "full_text": {"type": "integer"},


The type for 'full_text' should be 'string', not 'integer'. This field contains textual reference content, not numeric data.

Copilot · 2025-10-30T11:48:05Z

model_ai/llama.py

+      # FIXME: Hardcoded model name
+      model = genai.GenerativeModel('models/gemini-2.0-flash')


The Gemini model name is hardcoded. Consider making this configurable through the LlamaModel database entry or environment variable to support different model versions and avoid requiring code changes for model updates.

Copilot · 2025-10-30T11:48:06Z

markup_doc/sync_api.py

+            except:
+                print('**ERROR url')
+                print(url)
+                url = None


Bare except clause catches all exceptions including SystemExit and KeyboardInterrupt. Use except Exception: instead and consider logging the actual exception for debugging.

Trocar print por logging e inserir uma mensagem mais descritiva do error.

Copilot · 2025-10-30T11:48:06Z

markup_doc/views.py

+        except Exception:
+            # si no hay match, dejarlo como está
+            pass


Silent exception handling without logging makes debugging difficult. Consider logging the exception to help diagnose image lookup failures.

Copilot · 2025-10-30T11:48:06Z

markup_doc/static/js/xref-button.js

+});
+
+document.addEventListener("DOMContentLoaded", function () {
+    const journalInput = document.querySelector("#id_journal");


Unused variable journalInput.

Copilot · 2025-10-30T11:48:30Z

markup_doc/tasks.py

+                }
+                stream_data.append(obj.copy())
+
+            for i, auth in enumerate(output['authors']):


Nested for statement uses loop variable 'i' of enclosing for statement.

Copilot · 2025-10-30T11:48:30Z

markup_doc/tasks.py

+                }
+                stream_data.append(obj.copy())
+
+            for i, aff in enumerate(output['affiliations']):


Nested for statement uses loop variable 'i' of enclosing for statement.

Copilot · 2025-10-30T11:48:31Z

markup_doc/xml.py

+                else:
+                    break
+
+        for i, val in enumerate(vals[1:], start=1):


Nested for statement uses loop variable 'i' of enclosing for statement.

Copilot · 2025-10-30T11:48:31Z

markup_doc/xml.py

+            and b.value.get('label') == '<kwd-group>'
+            ]
+
+        for i, val in enumerate(vals):


Nested for statement uses loop variable 'i' of enclosing for statement.

Copilot · 2025-10-30T11:48:31Z

markup_doc/views.py

+    )
+
+    # Respuesta HTTP
+    with open(zip_path, "rb") as fp:


File may not be closed if an exception is raised.

- Adiciona scielo_xml_tools.yml com novos caminhos de volume - Move volumes para estrutura ../markup_data/ - Corrige nomes de containers no Makefile (markapi_local_*) - Adiciona .ipython/ ao .dockerignore - Adiciona huggingface-hub ao requirements/local.txt - Atualiza .gitignore para ignorar backups e arquivos temporários

eduranm and others added 30 commits September 26, 2025 10:15

Integración de ArticleViewSet en el enrutador y actualización de URLs…

e34f8a5

… principales

Actualización de settings: cambio en directorio de modelos, inclusión…

ab31a5e

… de nuevas apps y aumento del límite de campos

Ampliación de core.models: nuevos modelos de género, idioma, licencia…

b2e9538

…s, textos con idioma y manejo flexible de fechas

Actualización en Reference: uso de ReferenceStatus y ajuste en creaci…

d7395d9

…ón de referencias

Refactor en reference.config: serialización de ejemplos con json.dump…

02654a5

…s y ampliación de tipos soportados (confproc, full_text, etc.)

Refactor en marker: actualización de importación de GenericLlama desd…

e40b6be

…e model_ai

Eliminación de reference.tasks (responsabilidad movida a data_utils y…

d88c9c5

… model_ai)

Refactor en wagtail_hooks: uso de SnippetViewSet y soporte para desca…

3159c3b

…rga de modelos

Actualización de dependencias: inclusión de langid, google-generative…

8746d02

…ai y python-docx

Creación y ampliación de la app core: modelos comunes, formularios, v…

a9305e6

…istas de búsqueda, utilidades y hooks de Wagtail

Nueva app markup_doc: modelos ArticleDocx, API REST, tareas de marcad…

95a8153

…o, utilidades y hooks de Wagtail

Nueva librería markuplib: funciones para procesar DOCX y transformaci…

58cc438

…ones OMML a MathML

Nueva app model_ai: integración de LLaMA, funciones genéricas, mensaj…

4944e3b

…es de inferencia, tareas y hooks de Wagtail

Módulos adicionales en reference: configuración de Gemini y utilidade…

4ecb50a

…s de procesamiento de datos

Consolidación de migraciones en reference: actualización de 0001_init…

2ab9bd9

…ial.py y eliminación de migraciones intermedias

Actualización de migración inicial en core_settings: cambio de versió…

3024568

…n de Django y traducción de verbose_name a inglés

Creación de migración inicial en core

1e31de7

Eliminación de la app llama3: funcionalidades migradas a model_ai

826800b

fix(markup_doc): capturar ArticleDocxMarkup.DoesNotExist en generate_xml

76258cd

Corrige el tipo de excepción para responder 404 cuando el registro no existe.

refactor(markuplib): eliminar prints de depuración en extracción de e…

aff3a39

…nlaces Reduce ruido en logs y mantiene la función enfocada a su retorno.

style(model_ai): reemplazar bare except por Exception en download_model

6dd1ae2

Mejora legibilidad y buenas prácticas de manejo de errores.

fix(reference): corregir literales y separadores en config_gemini par…

5842054

…a prompt de referencias Se agregan comillas a campos textuales y se corrigen comas/keys para evitar errores de parseo del prompt.

i18n(reference): envolver labels y help_text con gettext_lazy

6a09911

Permite traducción de 'Mixed Citation' y 'Rating from 1 to 10'.

model_ai: corrige etiqueta de i18n y refuerza unicidad de LlamaModel …

95e6d31

…en save()

reference: renombra campo 'estatus' a 'status' y ajusta etiqueta a 'R…

192403d

…eference status' (incluye migraciones)

reference: elimina import no utilizado en wagtail_hooks.py

22fe3d1

remove antigo app llama3 e resolve conflito em base.py

abe54e2

adiciona instruções para fazer build com suporte a Llama

e000258

melhora imports

cbc8509

Apaga modulo legado llama3

2c32138

pitangainnovare and others added 19 commits October 20, 2025 17:13

Resolve conflitos em generic_llama e aplica correções estruturais:

aa9c6a3

- function_llama passou a ser LlamaInputSettings em llama.py - generic_llama passou a ser llama.py com LlamaService

Cria input settings para references

dc61b24

Padroniza deps

e2e696a

Padroniza imports em geral (além de adequar à nova nomenclatura)

3e712af

Adiciona método faltante em marker (por causa de merge)

dd94a35

Remove linhas comentadas

3ed8e58

Inclui AI Model na interace, para poder registrar modelos

1fbd7d1

Adequa uso do serviço Llama em tasks

e22bc7c

Adiciona migrações

79245bd

Corrige nome de parâmetro type (deve ser mode)

5740120

Flexibiliza attrs de LlamaService

a830fb5

Adiciona alguns FIXME

3bf5c7c

Melhora imports

f501379

Padroniza nome de metodo que obtem tipo de IA (LLAMA ou GEMINI)

cb739b4

Corrige o nome do site

08f465e

Atualiza os conteúdos de 'locale'

bb461e0

Correções em 'wagtail_hooks'

4fa1b11

Corrige atributo

acb914a

Corrige 'data_utils'

f218c87

Rossi-Luciano requested review from eduranm, pitangainnovare, robertatakenaka and samuelveigarangel October 28, 2025 14:25

robertatakenaka requested a review from Copilot October 30, 2025 11:37

Copilot AI reviewed Oct 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: estrutura Wiki de tutoriais e configuração de APIs de IA#36

docs: estrutura Wiki de tutoriais e configuração de APIs de IA#36
Rossi-Luciano wants to merge 50 commits intoscieloorg:mainfrom
Rossi-Luciano:pr-35

Rossi-Luciano commented Oct 28, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

samuelveigarangel Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		# FIXME: Hardcoded model name
		model = genai.GenerativeModel('models/gemini-2.0-flash')

Conversation

Rossi-Luciano commented Oct 28, 2025

O que esse PR faz?

Onde a revisão poderia começar?

Como este poderia ser testado manualmente?

Algum cenário de contexto que queira dar?

Quais são tickets relevantes?

Referências

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

samuelveigarangel Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants