Investidor-V2/docs/investmoz/ai/README.md

Assistência InvestMoz — entrega incremental

Implementada uma base interna, lexical e determinística, com gateway Laravel, React, fontes, revisão e suspensão. Não é ainda a plataforma generativa/RAG híbrida completa solicitada. Nenhum modelo, embedding ou reranker está activo, e não há selecção final de fornecedor baseada em benchmark generativo local.

Execução local confirmada — 26/09/2026

• Migration 2026_09_26_120000_investmoz_ai_foundation aplicada à base local após backup, restauro isolado e reconciliação de 69 tabelas existentes.
• INVESTMOZ_AI_ENABLED=true confirmado no ambiente local; acesso a /management/ai limitado aos gestores já autorizados. Oito endpoints REST internos registados, além das rotas Inertia.
• Suite PHP completa: 118 testes, 1.080 verificações aprovadas. Inclui nove testes dedicados à base assistiva/fusão. PHPStan, Pint, TypeScript e build aprovados.
• Benchmark FTS: oito casos sintéticos PT/EN, todos com resultado esperado. Medianas por caso entre 1,091 e 1,604 ms; estes números não são latência de geração nem SLA.
• Backup e manifesto: storage/app/private/ai-backup-20260926-155758/. A configuração anterior foi conservada nesse directório privado; não o publicar.
• Nenhum documento institucional foi inventado ou carregado na base local; os dados de teste foram usados apenas na base isolada e revertidos. Corpus autorizado deve ser fornecido pelos responsáveis.
• Sem benchmark Mistral/Qwen/BGE, integração SuiteCRM real ou teste visual em navegador. Produção continua não aprovada.

Utilização

Após migrations e activação local INVESTMOZ_AI_ENABLED=true, aceder a /management/ai com conta gestora e email verificado. A página não concede novos privilégios a utilizadores registados.

1. Carregar um .txt UTF-8 autorizado, com até 195 KiB, ou seleccionar um documento activo do cadastro existente. A classificação gravada é interna; não importar documentos confidenciais/restritos nesta fase.
2. Registar fonte HTTPS, proprietário, evidência de autorização, idioma, natureza declarada e validade. Não se faz download do URL; é uma referência, não um mecanismo de importação remota.
3. Outra pessoa gestora confirma a autorização. Só depois a fonte entra na pesquisa. A autorização interna não valida juridicamente a fonte nem torna oficial o seu conteúdo.
4. Consultar excertos, comparar oportunidades por filtros ou executar regras de qualidade/prazos. Consulta sem evidência não produz uma conclusão.
5. Pedir revisão, dar feedback ou suspender capacidades. Feedback unsafe suspende a capacidade; o controlo de emergência não partilha o limite de consultas.

Os resultados são guardados encriptados com a chave Laravel. A auditoria contém identificadores, versões, modo e latência, sem pergunta ou texto dos fragmentos. Revogar uma fonte ou alterar a sua versão/checksum/classificação impede consultas e oculta resultados anteriores que dela dependam. A triagem exige consentimento específico existente em consents, com subject_ref igual à referência do pedido e purpose=ai_assistance; consentimento de contacto não é reutilizado como consentimento de IA.

Artefactos

• Arquitectura e limites
• Modelos, licenças e recursos
• Benchmark lexical sintético executado
• Cobertura funcional e pipeline
• Contrato dos endpoints
• Esquema vectorial proposto, não executado

Validação e operação

Com uma base PostgreSQL isolada terminada em _test, migrations aplicadas e APP_ENV=testing:

php artisan ai:benchmark
php vendor/bin/phpunit --filter 'AiGateway|AiHybrid' --do-not-cache-result

O benchmark usa oito casos sintéticos PT/EN, cinco repetições por caso, e reverte os dados numa transacção. Não mede qualidade gerativa, PT-MZ validado por especialistas, carga, concorrência, recall sobre corpus real ou custo total de operação.

Migrations aplicacionais não instalam pgvector nem modelos. Fazer backup/restauro antes da activação no ambiente de destino. Para suspensão global, definir INVESTMOZ_AI_ENABLED=false e limpar cache de configuração; preservar fontes, documentos e revisões. O rollback das tabelas com dados é recusado.

Não activar em produção antes de validar corpus, mandatos, retenção, privacidade, acessibilidade, carga, recuperação, revisão por pares e fornecedor. Não houve envio a SuiteCRM, treino, fine-tuning ou chamadas pagas de modelos.