Tornar instalação e uso da app ia opcional

[gitnnolabs]

Descrição da tarefa

Eu, como administrador de implantação do SciELO Tools, gostaria que a aplicação de IA (ia) pudesse ser instalada e ativada opcionalmente, para que instalações que usam apenas validação SPS, gestão de XML e Wagtail não carreguem dependências pesadas de LLM, migrações do app ia nem menus administrativos de IA.

Hoje o app ia está sempre em LOCAL_APPS, as URLs admin/ia/ estão sempre registradas e google-generativeai / huggingface_hub estão em requirements/base.txt, obrigando todas as instalações a incluir IA mesmo quando não será usada.

A solução deve combinar dois níveis independentes:

1. Instalação opcional (dependências) — ficheiros requirements separados para o perfil com IA.
2. Ativação opcional (runtime Django/Wagtail) — variável IA_ENABLED controlando INSTALLED_APPS, URLs, router de banco e integrações futuras.

O toggle existente LLAMA_ENABLED permanece responsável apenas pelo provider local (GGUF via llama-cpp-python), não pelo app inteiro.

Fora do âmbito desta tarefa:

• Publicar o app ia como pacote pip independente (scielo-ia).
• Integrar xml_manager ou outros apps com chamadas a ia.references (preparar o padrão apps.is_installed("ia"), mas não implementar fluxos editoriais).
• Alterar comportamento dos providers Gemini, Ollama ou HuggingFace quando IA estiver ativa.

---

Estado atual (ponto de partida)

Elemento	Comportamento atual
config/settings/base.py	"ia" fixo em LOCAL_APPS; LLAMA_MODEL_DIR sempre definido
config/urls.py	path("admin/ia/", include("ia.urls")) sempre presente
requirements/base.txt	google-generativeai e huggingface_hub no core
LLAMA_ENABLED	Desliga só o provider local em ia/providers/local.py
llama-cpp-python	Não listado em requirements; import lazy com exceção de domínio
Outros apps	Sem import direto de ia (acoplamento ainda baixo)

---

Decisões de design

1. Ativação em runtime — IA_ENABLED

Introduzir IA_ENABLED = env.bool("IA_ENABLED", default=False) em config/settings/base.py (ou perfil local.py com default True apenas em dev, se a equipa preferir).

Quando IA_ENABLED for False:

• "ia" não entra em LOCAL_APPS / INSTALLED_APPS.
• DATABASE_ROUTERS não inclui ia.db_router.IADatabaseRouter.
• LLAMA_MODEL_DIR só é definido se IA estiver ativa.
• config/urls.py não registra admin/ia/.
• Hooks Wagtail de ia/wagtail_hooks.py não são carregados (descoberta automática só com app instalado).
• Tarefas Celery de ia/tasks.py não são autodescobertas.

Quando IA_ENABLED for True:

• Comportamento equivalente ao atual (app completo, migrações, admin, URLs).

Padrão para consumo futuro por outros apps:

from django.apps import apps

if apps.is_installed("ia"):
    from ia.references import mark_reference

Preferir apps.is_installed("ia") em vez de checar só IA_ENABLED, para refletir o que o Django realmente carregou.

2. Dependências — ficheiros requirements separados

Ficheiro	Conteúdo
requirements/base.txt	Remover google-generativeai e huggingface_hub
requirements/ia.txt	google-generativeai, huggingface_hub
requirements/ia-local.txt	llama-cpp-python (opcional; pesado e dependente de SO/toolchain)
requirements/local-ia.txt	-r local.txt + -r ia.txt
requirements/production-ia.txt	-r production.txt + -r ia.txt

requests permanece em base.txt (já usado por packtools e Ollama).

3. Perfis de instalação documentados

Perfil	IA_ENABLED	Requirements	Uso típico
core	false	local.txt / production.txt	Validação SPS, XML, Wagtail sem LLM
ia	true	local-ia.txt / production-ia.txt	Marcação assistida, providers configurados
ia + local GGUF	true + LLAMA_ENABLED=true	perfil ia + ia-local.txt	Inferência local com GGUF

4. Testes e CI

• Marcador pytest ia para testes que exigem app e dependências de IA.
• Job CI core: IA_ENABLED=false, pytest excluindo ia/.
• Job CI ia: IA_ENABLED=true, pip install -r requirements/ia.txt, pytest ia/tests.

---

Subtarefas

• Remover google-generativeai e huggingface_hub de requirements/base.txt.
• Criar requirements/ia.txt com dependências de IA (Gemini + HuggingFace hub).
• Criar requirements/ia-local.txt com llama-cpp-python (documentar requisitos de compilação).
• Criar requirements/local-ia.txt e requirements/production-ia.txt agregando os ficheiros acima.
• Adicionar IA_ENABLED em config/settings/base.py com default False.
• Montar LOCAL_APPS condicionalmente ("ia" só se IA_ENABLED).
• Montar DATABASE_ROUTERS condicionalmente (IADatabaseRouter só se IA_ENABLED).
• Definir LLAMA_MODEL_DIR apenas quando IA_ENABLED for True.
• Condicionar path("admin/ia/", ...) em config/urls.py a IA_ENABLED.
• Avaliar lazy import em ia/tasks.py para huggingface_hub (evitar falha se módulo importado com deps ausentes em cenários de teste).
• Adicionar marcador ia em pytest.ini (ou pyproject.toml se existir).
• Atualizar Makefile com alvos opcionais (install-ia, migrate-ia ou equivalente).
• Documentar perfis core vs ia em README ou docs/ (comandos pip install e variáveis de ambiente).
• Atualizar .env.example (se existir) com IA_ENABLED, LLAMA_ENABLED e notas sobre requirements.
• Ajustar setup.cfg / cobertura para refletir que ia é opcional no perfil core (sem obrigar cobertura de ia no job core).

---

Critérios de aceite

• Com IA_ENABLED=false e pip install -r requirements/local.txt, python manage.py check passa sem erros e sem ia em INSTALLED_APPS.
• Com IA_ENABLED=false, /admin/ não exibe grupo ou entradas de IA Models.
• Com IA_ENABLED=false, python manage.py migrate não aplica migrações do app ia.
• Com IA_ENABLED=true, pip install -r requirements/local-ia.txt e migrações, o admin Wagtail de IA funciona como hoje (Gemini, Ollama, HuggingFace).
• google-generativeai e huggingface_hub não estão em requirements/base.txt.
• llama-cpp-python não está em requirements/ia.txt (permanece em ficheiro à parte).
• LLAMA_ENABLED=false com IA ativa continua a impedir uso do provider local sem desativar Gemini/Ollama.
• Documentação descreve claramente os dois perfis de instalação e as variáveis de ambiente.
• CI (ou plano documentado) cobre execução com e sem IA.

---

Como testar manualmente

Perfil core (sem IA)

1. pip install -r requirements/local.txt
2. Garantir IA_ENABLED=false (ou ausente) no ambiente.
3. python manage.py check
4. python manage.py migrate
5. Acessar /admin/ e confirmar ausência de IA Models.
6. Confirmar que python -c "import google.generativeai" falha (deps não instaladas).

Perfil ia

1. pip install -r requirements/local-ia.txt
2. IA_ENABLED=true python manage.py migrate
3. IA_ENABLED=true python manage.py check
4. Acessar /admin/ e configurar um provider (ex.: Ollama em http://localhost:11434).
5. No shell: from ia.service import LLMService — import sem erro.
6. Opcional: pip install -r requirements/ia-local.txt, ativar modelo HuggingFace e validar provider local com LLAMA_ENABLED=true.

Regressão

1. Com IA ativa, repetir fluxos do PR docs/pr/2026-07-02-adicionar-app-ia.md (download HF, fetch Ollama, pytest ia/tests).

---

Referências

• Django settings — conditional INSTALLED_APPS
• Wagtail hooks — auto-discovery via installed apps