Skip to content

Adiciona API REST e app body para marcação SPS do corpo - #42

Open
gitnnolabs wants to merge 2 commits into
scieloorg:qafrom
gitnnolabs:chore/scielo-tools-41
Open

Adiciona API REST e app body para marcação SPS do corpo#42
gitnnolabs wants to merge 2 commits into
scieloorg:qafrom
gitnnolabs:chore/scielo-tools-41

Conversation

@gitnnolabs

@gitnnolabs gitnnolabs commented Sep 14, 2026

Copy link
Copy Markdown
Collaborator

O que esse PR faz?

Introduz o app Django body, terceira peça da pipeline de marcação SPS (após reference e front), responsável pelo corpo do artigo (<body>).

Entregas principais:

  • API REST autenticada (JWT):
    • POST /api/v1/body/ — marcação a partir de texto plano
    • POST /api/v1/body/docx/ — extração do corpo a partir de .docx (Introduction → acknowledgments/references) e marcação, incluindo metadados de tabelas e figuras
  • Cache por checksum SHA256 do texto normalizado (Body), evitando reprocessamento pelo Llama quando a entrada é idêntica
  • Geração de JSON estruturado e XML JATS (<body> com secções, parágrafos, figuras e tabelas) via body/data_utils.py
  • Integração Llama local via HTTP (Ollama-compatible), configurável por BODY_* em settings
  • Marcação em chunks para textos longos (BODY_CHUNK_CHARS)
  • Comando de gestão remove_all_body e target make remove_all_body para limpar o cache
  • Cobertura de testes (API, DOCX, XML, provider, marking, comando)

O padrão arquitetural replica o já adotado em front/ e reference/: ViewSet DRF → resolve_body_result → provider HTTP → persistência + resposta JSON ou XML.

Onde a revisão poderia começar?

  1. body/api/v1/views.py — endpoints e fluxo de marcação
  2. body/data_utils.py — resolução, pós-processamento e get_body_xml
  3. body/utils.py — extração DOCX e normalização do texto
  4. body/providers/http.py — cliente Llama
  5. config/settings/base.py — variáveis BODY_* e registo do app
  6. body/tests/test_api.py e body/tests/test_xml.py — comportamento esperado

Como este poderia ser testado manualmente?

  1. Configurar Llama local nos envs (ex.: .envs/.local/.django):
    • BODY_ENABLED=true
    • BODY_URL=http://host.docker.internal:11434
    • BODY_MODEL=llama3.2:3b
  2. Subir o stack e aplicar migrações: 
    docker compose -f local.yml up -d
docker compose -f local.yml run --rm django python manage.py migrate body
  3. Obter token JWT: 
    curl -X POST http://localhost:8000/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<pass>"}'
  4. Marcar corpo por texto: 
    curl -X POST http://localhost:8000/api/v1/body/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"body": "<texto do corpo>", "type": "json"}'
  5. Marcar corpo por DOCX: 
    curl -X POST http://localhost:8000/api/v1/body/docx/ \
  -H "Authorization: Bearer <token>" \
  -F "file=@artigo.docx" \
  -F "type=xml"
  6. Repetir a mesma requisição e confirmar resposta imediata (cache por checksum).
  7. Limpar cache: 
    make remove_all_body
  8. Testes automatizados: 
    docker compose -f local.yml run --rm django pytest --reuse-db -m "not llama" body/tests/
  9. (Opcional) Teste de acurácia com fixture: 
    export JWT_USERNAME=<user> JWT_PASSWORD=<pass>
python -m scripts.accuracy body \
  --package bn-2025-1870 \
  --base-url http://localhost:8000 \
  --timeout 1800

Algum cenário de contexto que queira dar?

  • Complementa o PR Adiciona marcação assistida do front do artigo (API REST e XML SPS) #38 (front) e fecha a tríade front / body / back necessária para montagem do XML SPS completo (<article>).
  • A extração DOCX identifica o corpo entre cabeçalhos de introdução e acknowledgments/referências; tabelas e figuras são extraídas como metadados auxiliares para enriquecer a marcação.
  • O corpo tende a ser o trecho mais longo do artigo; BODY_CHUNK_CHARS (default 8000) e BODY_NUM_CTX (default 32768) existem para acomodar textos extensos sem estourar o contexto do modelo local.
  • Marcação usa somente modelo local (sem APIs de IA externas), alinhado às regras do projeto.
  • Limitações conhecidas fora deste PR: equações, imagens do pacote SPS e tradução de artigos permanecem em follow-up.

Screenshots

N/A — PR de API/backend, sem alterações de interface Wagtail.

Quais são tickets relevantes?

SciELO Tools #41 (chore/scielo-tools-41)

Referências

  • Critérios SciELO Brasil / SPS para marcação de <body>
  • RCT SciELO Tools v4.0 — pipeline DOCX → XML SPS

@gitnnolabs
Realiza ajustes no front.
ceb33b2
@gitnnolabs
Adiciona API REST e app body para marcação SPS do corpo
1deb69c 
Expõe POST /api/v1/body/ e /api/v1/body/docx/ com cache por checksum,
geração de XML JATS e integração Llama local via HTTP (BODY_*).
Inclui comando remove_all_body e variáveis de ambiente de exemplo.
@gitnnolabs gitnnolabs self-assigned this Sep 14, 2026
@gitnnolabs gitnnolabs added the enhancement New feature or request label Sep 14, 2026
@gitnnolabs
gitnnolabs marked this pull request as ready for review September 14, 2026 11:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@robertatakenaka robertatakenaka Awaiting requested review from robertatakenaka

Assignees

@gitnnolabs gitnnolabs

Labels

enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@gitnnolabs