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.