Adicionar app `ia`

[gitnnolabs]

Descrição da tarefa

Adicionar o app Django ia (renomeado do original ai no singular).

A aplicação de IA deve ser auto-suficiente, possuir banco de dados próprio (migrations própria), suas próprias telas no Wagtail, suas próprias APIs, e ser estruturada de forma que possa ser reutilizada em outro projeto sem dependências do restante do ecossistema do scielo-tools.

Âmbito:

Módulo	Responsabilidade
ia/models.py	Modelos de configuração dos provedores: HuggingFaceModel, OllamaModel, GeminiModel.
ia/service.py	Serviço de orquestração de LLM (LLMService).
ia/providers/	Provedores de LLM: gemini.py, local.py (Llama via llama-cpp), ollama.py.
ia/wagtail_hooks.py	Telas administrativas (snippets/panels) no Wagtail para gerenciar os modelos de IA e buscar tags/informações do Ollama via AJAX.
ia/exceptions.py	Exceções customizadas de domínio (LlamaDisabledError, LlamaModelNotFoundError, etc.).
ia/utils/	Utilitários de manipulação de prompts, blocos, JSON, visão e normalizadores (normalizers.py).
ia/tasks.py	Tarefas Celery associadas (ex: download de modelos do HuggingFace).
ia/templates/	Templates personalizados do Wagtail admin para as telas da IA.
ia/apps.py	Configuração do Django App (IAConfig).

Decisões de Design para Reusabilidade (Auto-suficiência):

1. Desacoplamento do core.models e core.forms:
   • No repositório de referência, os modelos herdam de core.models.CommonControlField e usam core.forms.CoreAdminModelForm (que gerenciam campos como creator e updated_by). Como o core/models.py no projeto atual está vazio, a aplicação ia deve implementar sua própria classe base abstrata (ex: IAMetadataModel) e seu próprio WagtailAdminModelForm (ex: IAAdminModelForm em ia/forms.py) para evitar qualquer ImportError e garantir reusabilidade de código.
2. Migrations e Isolamento de Banco de Dados:
   • O app gerará suas próprias migrações em ia/migrations/.
   • Adicionaremos a possibilidade de configurar o app para usar um banco de dados dedicado via roteador Django (ia_db / IADatabaseRouter), caso o deploy final exija separação física das tabelas do Wagtail/Django core.

---

Pré-requisitos (blockers)

Pré-requisito	Consumido por	Notas
google-generativeai	ia/providers/gemini.py	SDK de integração com o Gemini da Google.
requests	ia/wagtail_hooks.py	Requisições HTTP para consultar APIs do Ollama.
django-celery-results	ia/tasks.py	Necessário se for utilizar o download assíncrono de modelos.
llama-cpp-python (opcional/condicional)	ia/providers/local.py	Execução local de GGUF. Deve falhar graciosamente via exceção de import se não estiver instalado.

---

Subtarefas

• Criar a pasta do app ia/ na raiz do projeto
• Renomear todas as referências internas de ai para ia (ex: imports, namespaces, nome da app).
• Criar ia/forms.py contendo o IAAdminModelForm (migrado do CoreAdminModelForm do initial) para registrar quem criou/alterou o registro.
• Alterar ia/models.py para:
  • Definir uma classe abstrata IAMetadataModel (com campos created, updated, creator e updated_by) em vez de herdar do core.models.CommonControlField.
  • Atualizar os modelos para herdarem de IAMetadataModel e apontarem para ia.forms.IAAdminModelForm no atributo base_form_class.
• Criar ia/db_router.py contendo o IADatabaseRouter para direcionar opcionalmente leituras, escritas e migrações do app ia para um banco de dados específico ia_db.
• Registrar "ia" na lista LOCAL_APPS em config/settings/base.py.
• Adicionar dependências necessárias em requirements/base.txt:
  • google-generativeai
  • requests
• Rodar o comando de geração das migrações iniciais específicas do app:

  python manage.py makemigrations ia

• Executar as migrações no banco local:

  python manage.py migrate

• Registrar as URLs de API AJAX do Wagtail de Ollama (ollama_tags e ollama_model_info) no arquivo config/urls.py de forma desacoplada ou através do ia/urls.py.
• Garantir que o painel administrativo do Wagtail exiba as telas de configuração dos modelos (Gemini, Ollama, HuggingFace) no menu lateral de forma independente.
• Realizar smoke test no shell Django:

  python manage.py shell

  from ia.service import LLMService
  # Garantir que importa sem erros de dependência circular ou imports perdidos do core

---

API pública a preservar / expor

Contratos consumidos externamente pelas demais aplicações (como referencia e futuramente manuscripts):

ia.service

• LLMService(messages, response_format, ...): classe para instanciar a chamada ao provedor de IA configurado como ativo.
• LLMService.run(user_input, response_format=None): executa o prompt/chat e retorna a resposta bruta da IA.

ia.references

• mark_reference(reference_text): gerador que retorna as marcações sugeridas pela IA para um texto de citação.
• mark_references(reference_block): processa em lote as linhas de referências.

ia.utils.normalizers

• stz_norm(value): normalização padrão de strings para geração estável de checksums.

---

Critérios de aceite

• O comando python manage.py check executa limpo sem erros de importação ou relacionamentos.
• Não existem imports direcionados para core.models ou core.forms a partir de ia/.
• As telas de gerenciamento do snippet de IA (Gemini, Ollama, HuggingFace) estão ativas e funcionando perfeitamente no painel do Wagtail.
• As migrations do app ia são executadas e criam as tabelas com sucesso (tabelas prefixadas com ia_).
• O app ia é totalmente portável para outra instalação Django contendo apenas Wagtail configurado.

---

Como testar manualmente

1. Subir o ambiente local (make build && make up).
2. Executar as migrações com sucesso.
3. Acessar o painel Wagtail do Django local (http://localhost:8009/admin/) e configurar um provedor (ex: Ollama ou Gemini).
4. No console Django (python manage.py shell), testar a geração com um prompt simples:

   from ia.service import LLMService
   service = LLMService(messages=[{"role": "system", "content": "You are a helpful assistant."}])
   print(service.run("Hello, this is a test."))

5. Confirmar que a resposta é processada sem depender de tabelas globais do core.