docs: adicionar proposta do projeto MarkAPI (Markdown)

[Copilot]

Não havia documentação de proposta descrevendo o propósito do MarkAPI, seus modos de instalação e suas funcionalidades. Esta PR adiciona um documento proposta.md em docs/, redigido em português (Markdown, renderizado pelo Sphinx via myst-parser), alinhado ao código do branch main, à dependência packtools e aos módulos existentes (xml_manager, reference, model_ai, docx_layouts).

O que esse PR faz?

• Adiciona docs/proposta.md com a proposta do projeto, cobrindo:
  • Visão geral do MarkAPI no contexto do fluxo editorial SciELO.
  • Modos de instalação: desktop monousuário, servidor em intranet e servidor na internet (todos via Docker, com Compose para desenvolvimento — local.yml — e production.yml previsto/em construção, além dos manifestos Kubernetes em kubernetes/ para ambientes maiores), incluindo subseção Requisitos de hardware e opções de LLM (GPU para melhor desempenho, modelo LLM pequeno em ambiente sem GPU, e possibilidade de configurar uma API externa de LLM contratada com custo e responsabilidade do usuário/instituição).
  • Funcionalidades: conversão DOCX → XML SPS, empacotamento .zip SPS (XML, PDFs por idioma, imagens e ativos digitais nomeados conforme SPS), validação de XML e geração de PDFs via packtools, marcação automática de referências bibliográficas (serviço dedicado exposto via API REST), marcação automatizada por LLM configurável e ajustes manuais pelo usuário.
  • Arquitetura em alto nível detalhando:
    • Stack tecnológica com versões e propósito de cada dependência: Python 3, Django 5, Wagtail 6 (+ wagtail-modeladmin, wagtailmenus, wagtail-localize, wagtail-autocomplete, wagtail-django-recaptcha), Django REST Framework 3.15 + djangorestframework-simplejwt, PostgreSQL (psycopg2-binary), Celery 5 + Redis 6 + Kombu, django-celery-beat / django_celery_results, Flower, Gunicorn/gevent, lxml, python-docx, packtools 4.12.6, langdetect/langid, tenacity, llama-cpp-python, huggingface-hub, google-generativeai, MailHog / django-anymail, Sentry / Elastic APM, django-environ, django-compressor, whitenoise, Docker Compose (local.yml, production.yml previsto) e Kubernetes (kubernetes/), além de flake8/isort.
    • Organização do código mapeando os apps registrados em INSTALLED_APPS (config, core, core_settings, users, xml_manager, reference, model_ai, docx_layouts, tracker, django_celery_beat) para arquivos concretos do repositório.
    • Fluxo de execução típico descrevendo o pipeline DOCX → tarefa Celery → marcação de referências (LLM local ou Gemini) → validação e geração de PDFs via packtools → empacotamento .zip SPS → eventos no tracker e monitoramento via Flower.
  • Requisitos não funcionais: portabilidade de instalação, reprodutibilidade do ambiente, internacionalização/localização, escalabilidade horizontal, resiliência e tolerância a falhas (Celery + tenacity), observabilidade (tracker, Flower, Sentry, Elastic APM), segurança (JWT, CSRF, reCAPTCHA, segredos via django-environ), privacidade dos dados (LLM local on-premise vs. API contratada), desempenho (GPU, processamento assíncrono, reuso de marcações), conformidade com o SPS via packtools, manutenibilidade (flake8/isort), auditabilidade e compatibilidade com navegadores modernos.
  • Perspectivas (funcionalidades futuras): suporte a novos provedores de LLM (OpenAI, Anthropic, Mistral, Azure OpenAI, Ollama/vLLM), expansão da marcação assistida para outros elementos do SPS (afiliações, autores, financiamento, figuras), editor visual de XML SPS no navegador, importação a partir de outros formatos (ODT, RTF, LaTeX, PDF/OCR), validação incremental com diagnósticos amigáveis, enriquecimento via Crossref/PubMed/DOI/ORCID/ROR, ingestão automatizada em sistemas downstream, integração com OJS/ScholarOne, versionamento e auditoria de marcações, painéis e métricas, fine-tuning do LLM local, API pública versionada (OpenAPI/Swagger), SSO (SAML/OIDC, ORCID), modo offline desktop all-in-one, acessibilidade (WCAG) e telemetria opt-in anonimizada.
  • Público-alvo (marcadores autônomos em desktop monousuário, equipes editoriais em intranet, instituições com publicação distribuída em servidor de internet, editores de DOCX que precisam publicar no formato SPS) e referências (SPS, packtools, wiki do projeto).
• Habilita Markdown no Sphinx: adiciona myst_parser em docs/conf.py (com source_suffix mapeando .rst e .md) e myst-parser em requirements/local.txt.
• Mantém proposta no toctree de docs/index.rst, agora resolvido para docs/proposta.md.
• Documenta o serviço de marcação automática de referências bibliográficas, descrevendo:
  • entrada (mixed-citation em texto livre) e saída (<element-citation> no padrão SPS, ou estrutura intermediária);
  • exposição via API REST (ReferenceViewSet em reference/api/v1/views.py);
  • processamento com LlamaService (model_ai) usando prompts e response_format definidos em reference/config.py (e alternativa Google Gemini via reference/config_gemini.py);
  • conversão para XML SPS via reference/data_utils.get_xml;
  • persistência e reuso através dos modelos Reference/ElementCitation controlados por ReferenceStatus;
  • observabilidade de erros do LLM via tracker.GeneralEvent;
  • revisão manual pelo usuário antes do empacotamento final.

Onde a revisão poderia começar?

docs/proposta.md — verificar se o conteúdo reflete fielmente o escopo desejado da aplicação, em especial as seções Modos de Instalação (com a subseção Requisitos de hardware e opções de LLM), Marcação automática de referências bibliográficas, Arquitetura em alto nível (stack tecnológica, organização do código e fluxo de execução típico), Requisitos não funcionais, Perspectivas (funcionalidades futuras) e Público-alvo. Em seguida, docs/conf.py (extensão myst_parser e source_suffix), requirements/local.txt (dependência myst-parser) e docs/index.rst para conferir a inclusão no toctree.

Como este poderia ser testado manualmente?

1. Subir o serviço de docs: docker-compose -f local.yml up docs.
2. Abrir a documentação no navegador e confirmar que o item Proposta do Projeto MarkAPI aparece no índice.
3. Acessar a página e validar a renderização das seções (incluindo Modos de Instalação com a subseção Requisitos de hardware e opções de LLM, Marcação automática de referências bibliográficas, Arquitetura em alto nível com Stack tecnológica, Organização do código e Fluxo de execução típico, Requisitos não funcionais, Perspectivas (funcionalidades futuras) e Público-alvo) e dos links externos (SPS, packtools, wiki, Django, Wagtail, Celery, Redis, lxml, llama-cpp-python, etc.).

Algum cenário de contexto que queira dar?

A proposta foi redigida a partir do código do main e da descrição do issue, descrevendo a aplicação como ferramenta de marcação assistida por LLM (opcional) com revisão manual obrigatória para a equipe editorial. A subseção sobre marcação automática de referências, a expansão das seções de Modos de Instalação (com requisitos de hardware/opções de LLM) e Público-alvo, a seção detalhada de Arquitetura em alto nível (stack tecnológica completa, organização do código e fluxo de execução) e as novas seções Requisitos não funcionais e Perspectivas (funcionalidades futuras) foram adicionadas em resposta ao feedback do mantenedor, refletindo os serviços já implementados nos módulos reference e model_ai, os cenários reais de instalação (desktop monousuário, servidor em intranet, servidor na internet, com ou sem GPU, e a opção de API externa de LLM contratada) e as dependências reais de requirements/base.txt e requirements/production.txt. Como o sistema ainda está em construção, production.yml é citado como artefato previsto/em construção, ao lado de local.yml (existente) e dos manifestos Kubernetes em kubernetes/. Em resposta a um pedido posterior do mantenedor, o documento foi convertido de reStructuredText para Markdown (docs/proposta.md), passando o Sphinx a renderizá-lo via myst-parser (configuração ajustada em docs/conf.py e dependência adicionada em requirements/local.txt), permitindo que próximos documentos da pasta docs/ também possam ser escritos em Markdown.

Screenshots

Não aplicável — alteração apenas de documentação textual.

Referências

• SciELO Publishing Schema
• packtools
• Wiki: Guia rápido do modelo do MarkAPI
• MyST Parser (suporte a Markdown no Sphinx)
• requirements/base.txt e requirements/production.txt (Django, Wagtail, DRF + SimpleJWT, Celery, Redis, Kombu, django-celery-beat, Flower, Gunicorn/gevent, lxml, python-docx, packtools, langdetect/langid, tenacity, llama-cpp-python, huggingface-hub, google-generativeai, MailHog/django-anymail, Sentry, Elastic APM) e módulos xml_manager, reference (incluindo reference/api/v1/views.py, reference/marker.py, reference/data_utils.py, reference/config.py, reference/config_gemini.py), model_ai (com llama.py/LlamaService e exceptions.py), tracker, core, core_settings, users, config (incluindo config/celery_app.py e config/api_router.py) e os manifestos em kubernetes/ do próprio repositório.

[robertatakenaka]

@copilot também há o serviço de marcação automática das referências, elabore a documentação sobre isso

[Copilot]

@copilot também há o serviço de marcação automática das referências, elabore a documentação sobre isso

Adicionada na seção "Funcionalidades" uma subseção dedicada à Marcação automática de referências bibliográficas, descrevendo entrada/saída, exposição via API REST (ReferenceViewSet), uso do LlamaService com prompts em reference/config.py, geração do <element-citation> no padrão SPS via reference/data_utils.get_xml, persistência em Reference/ElementCitation com reuso, observabilidade via tracker.GeneralEvent e revisão manual pelo usuário. Commit: 0f79deb.

[robertatakenaka]

@copilot informação relevante o público-alvo e forma de instalação. Apesar de ser uma aplicação Web, pode ser instalada como uma ferramenta Desktop para monousuário em um computador ou em um servidor em intranet ou ainda um servidor para internet. Em servidor com GPU funcionará melhor. Na ausência de GPU , usa-se um modelo LLM pequeno. Há a possibilidade de contratar API de LLM, mas o custo e a LLM que se responsabiliza é o usuário ou sua empresa.

[Copilot]

@copilot informação relevante o público-alvo e forma de instalação. Apesar de ser uma aplicação Web, pode ser instalada como uma ferramenta Desktop para monousuário em um computador ou em um s...

Atualizei docs/proposta.rst (commit cc14d9a):

• Modos de Instalação agora distingue desktop monousuário, servidor em intranet e servidor na internet, mantendo a distribuição via Docker.
• Nova subseção Requisitos de hardware e opções de LLM: melhor desempenho em servidor com GPU; em ambiente sem GPU, uso de modelo LLM pequeno; e possibilidade de configurar uma API externa de LLM contratada, com custo e responsabilidade pelo modelo a cargo do usuário/instituição.
• Público-alvo reescrito para refletir esses três cenários e as opções de LLM.

[robertatakenaka]

@copilot adicione info da stack, wagtail, celery, etc, o máximo de detalhes técnicos possível

[Copilot]

@copilot adicione info da stack, wagtail, celery, etc, o máximo de detalhes técnicos possível

Expandi a seção Arquitetura em alto nível em docs/proposta.rst (commit f4d3cb6) com três blocos:

• Stack tecnológica: Python 3, Django 5, Wagtail 6 (+ wagtail-modeladmin, wagtailmenus, wagtail-localize, wagtail-autocomplete, wagtail-django-recaptcha), DRF 3.15 + SimpleJWT, PostgreSQL (psycopg2), Celery 5 + Redis 6 + Kombu, django-celery-beat / django_celery_results, Flower, Gunicorn/gevent, lxml, python-docx, packtools 4.12.6, langdetect/langid, tenacity, llama-cpp-python, huggingface-hub, google-generativeai, MailHog / django-anymail, Sentry / Elastic APM, django-environ, django-compressor, whitenoise, Docker Compose (local.yml) e Kubernetes (kubernetes/), além de flake8/isort.
• Organização do código: apps registrados em INSTALLED_APPS (config, core, core_settings, users, xml_manager, reference com api/v1/views.py, marker.py, data_utils.py, config.py, config_gemini.py, models.py; model_ai com llama.py/LlamaService e exceções; docx_layouts, tracker, django_celery_beat).
• Fluxo de execução típico: upload DOCX → tarefa Celery → marcação de referências (LLM local ou Gemini) → validação/geração de PDFs via packtools → empacotamento .zip SPS → eventos no tracker e monitoramento via Flower.

Também corrigi a menção a production.yml (inexistente) — a produção é descrita via os manifestos em kubernetes/.

[robertatakenaka]

@copilot o sistema ainda está em construção, o production.yml deveria existir. Inclusive se tiver algumas sugestões de funcionalidades (perspectivas) e requisitos não funcionais, por favor, acrescente no documento.

[Copilot]

@copilot o sistema ainda está em construção, o production.yml deveria existir. Inclusive se tiver algumas sugestões de funcionalidades (perspectivas) e requisitos não funcionais, por favor, acres...

Atualizado em docs/proposta.rst (commit bc5b461):

• Em Modos de Instalação, production.yml voltou a ser citado, agora como artefato previsto/em construção, ao lado de local.yml e dos manifestos Kubernetes.
• Nova seção Requisitos não funcionais: portabilidade de instalação, reprodutibilidade, i18n/l10n, escalabilidade horizontal, resiliência (Celery/tenacity), observabilidade (tracker, Flower, Sentry, Elastic APM), segurança (JWT, CSRF, reCAPTCHA, segredos via env), privacidade (LLM local vs API contratada), desempenho (GPU, async, reuso de marcações), conformidade SPS (packtools), manutenibilidade (flake8/isort), auditabilidade e compatibilidade com navegadores.
• Nova seção Perspectivas (funcionalidades futuras) com sugestões: novos provedores de LLM (OpenAI, Anthropic, Mistral, Azure, Ollama/vLLM), marcação assistida de outros elementos do SPS (afiliações, autores, financiamento, figuras), editor visual de XML no navegador, suporte a outros formatos de entrada (ODT, RTF, LaTeX, PDF/OCR), validação incremental, enriquecimento via Crossref/PubMed/DOI/ORCID/ROR, ingestão automatizada em sistemas downstream, integração com OJS/ScholarOne, versionamento/auditoria, dashboards e métricas, fine-tuning do LLM local, API pública versionada (OpenAPI), SSO (SAML/OIDC, ORCID), modo offline desktop all-in-one, acessibilidade (WCAG) e telemetria opt-in.

[robertatakenaka]

@copilot converta a documentação para markdown

[Copilot]

@copilot converta a documentação para markdown

Convertido em 725e824:

• docs/proposta.rst → docs/proposta.md (mesmo conteúdo, agora em Markdown).
• docs/conf.py: adicionado myst_parser às extensions e configurado source_suffix para reconhecer .rst e .md.
• requirements/local.txt: adicionada a dependência myst-parser para que o Sphinx renderize Markdown.
• docs/index.rst: o toctree continua referenciando proposta (sem extensão), agora resolvido para proposta.md.

Build do Sphinx validada localmente sem erros.