A Central de IA é um pequeno intermediário BYOK (traga sua própria chave) para o Moodle. Ela permite que os plugins da própria instituição gerem texto através de chaves de API de IA compartilhadas, sem que cada plugin reimplemente o transporte HTTP, o guard de SSRF, a escada de provedores ou um armazenamento de chaves.

👈 Use a barra lateral para pular direto a qualquer seção desta página.

✨ Funcionalidades

• 🔑 Armazenamento BYOK: chaves de site (admin) e chaves pessoais opcionais (por usuário, opt-in) para Gemini, Groq, DeepSeek e qualquer endpoint compatível com OpenAI.
• 🪜 Resolução pessoal → site: o hub tenta a chave do próprio usuário primeiro, depois a de site, expondo um único resultado ao chamador.
• 🧩 Fachada de uma chamada: \local_aihub\ai::generate_text() e is_available() — consumidas pelos plugins irmãos por dependência soft (class_exists), sem dependência dura.
• 🚫 Não embrulha o core_ai: cada consumidor mantém o próprio fallback para core_ai, então um site que já tem core_ai configurado não precisa de nada extra — o hub continua opcional.
• 👁️ Chaves pessoais write-only: uma vez salva, a chave pessoal nunca é devolvida ao navegador — a página mostra só o status configurada / não configurada, fechando a leitura via Entrar como.
• 🧑‍💻 Página self-service: Minhas chaves de IA (nas preferências do usuário) para adicionar/substituir/remover chaves pessoais e revisar o próprio uso recente.
• 📊 Relatório de uso para o admin: todas as chamadas a provedores atendidas pelas chaves do site, de todos os usuários, com filtros de somente falhas e somente sucessos e download CSV / Excel — protegido por local/aihub:viewusage.
• 🛡️ Guard SSRF: o endpoint compatível com OpenAI configurável é forçado a HTTPS, com bloqueio de loopback / link-local / faixas privadas e anti-rebinding de DNS A/AAAA.
• 🧾 Log de uso + task de retenção: uma linha por chamada a provedor, não por requisição (usuário, componente solicitante, o que foi gerado, provedor, modelo, tier da chave, situação e — quando falhou — o motivo dado pelo próprio provedor), e uma task agendada que limpa logs além de uma retenção configurável. Uma requisição que cai para outro provedor deixa portanto uma linha para cada um, de modo que uma chave que nunca funciona não consegue se esconder atrás daquela que respondeu.
• 🔒 Privacidade completa: Privacy provider completo para o log de uso e as preferências pessoais, com os destinos externos declarados.

🧩 Como os consumidores usam

Um plugin irmão consome o hub através de um guard em runtime e mantém o próprio fallback para core_ai:

// Disponibilidade: chaves do hub primeiro, depois o fallback core_ai do consumidor.
public static function has_ai(): bool {
    if (class_exists(\local_aihub\ai::class) && \local_aihub\ai::is_available()) {
        return true;                       // BYOK via hub
    }
    return self::has_core_ai();            // funciona sem o hub
}

// Geração.
$result = \local_aihub\ai::generate_text(
    '',                    // prompt de sistema (opcional)
    $prompt,               // prompt do usuário
    false,                 // modo JSON
    'your_frankenstyle',   // 4º arg: componente chamador, para o log de uso
    'Rótulo curto'         // 5º arg: o que está sendo gerado, exibido no relatório de admin
);
if ($result['success']) {
    // $result['data'] é texto CRU e não-confiável — valide e passe por format_text().
}

O texto devolvido é cru e não-confiável: valide sua estrutura e passe por format_text() antes de exibir ou persistir.

Duas observações sobre o retorno. O texto gerado fica em data, e o motivo da falha em message — ler o array como objeto devolve null sem erro nenhum, o que transforma todo sucesso num fallback silencioso. E uma chamada pode gerar várias linhas de log: o hub registra cada provedor que tentou, sob o componente e o rótulo que você passou, então uma requisição que caiu para um segundo provedor aparece duas vezes no relatório, uma com falha e outra com sucesso.

🔗 Resolução de chave (escada BYOK)

O hub resolve a chave tier por tier e para no primeiro tier que tiver uma chave:

Dentro do tier escolhido, os provedores são tentados na ordem Gemini → Groq → DeepSeek → compatível com OpenAI (a primeira chave encontrada é usada; se a chamada falhar, o próximo provedor do mesmo tier é tentado). Quando nenhum tier tem chave, generate_text() retorna success = false — o hub nunca cai para o core_ai; essa decisão é do consumidor.

📦 Requisitos

Nenhuma biblioteca de terceiros empacotada. Os provedores de IA são serviços externos, declarados no Privacy provider — não em thirdpartylibs.xml.

🛠️ Instalação e Configuração

1. Baixe o arquivo .zip ou clone este repositório.
2. Extraia a pasta para o diretório local/ do seu Moodle.
3. Renomeie a pasta para aihub (se necessário). Caminho final: seu-moodle/local/aihub/
4. Acesse Administração do site → Notificações para concluir a instalação.

Configurar uma chave de provedor é opcional — o plugin instala e funciona sem nenhuma. Veja Como Usar logo abaixo para definir chaves de site e habilitar chaves pessoais.

📖 Como Usar

1. Configurar chaves de site (admin): Administração do site → Plugins → Plugins locais → Central de IA → Configurações. Defina qualquer uma das chaves Gemini, Groq, DeepSeek ou compatível com OpenAI e, opcionalmente, habilite as chaves de API pessoais.
2. Adicionar uma chave pessoal (usuário): usuários com a capability local/aihub:usepersonalkey ganham uma entrada Minhas chaves de IA nas preferências, onde guardam a própria chave (write-only) e veem o uso recente.
3. Revisar o uso das chaves de site (admin): o Relatório de uso de IA do site (sob a categoria Central de IA, capability local/aihub:viewusage) lista todas as chamadas a provedores atendidas pelas chaves do site, de todos os usuários, com download CSV e Excel. Cada tentativa aparece em sua própria linha, com a situação e o motivo da falha quando houver, e filtros de somente falhas ou somente sucessos para checar se algum provedor parou de responder, ou para reduzir a lista de volta ao que foi de fato gerado.
4. Consumir de um plugin (desenvolvedor): chame \local_aihub\ai::generate_text() atrás de um guard class_exists(), mantendo o próprio fallback para core_ai (ver Como os consumidores usam).

🧪 Testes Automatizados

O hub vem com uma suíte PHPUnit e Behat; todo push de CI roda contra a matriz (Moodle 4.5 → 5.x, PostgreSQL & MariaDB).

PHPUnit — Testes Unitários e de Integração

vendor/bin/phpunit --testsuite local_aihub

Cobertura de linhas por classe (PHPUnit + Xdebug):

A camada de transporte ficava fora da suíte, sob o argumento de que faz chamadas HTTP reais. Esse argumento cobria mais terreno do que devia: montar uma requisição e interpretar uma resposta não são operações de rede, e deixá-las para o dublê significava que a parte do plugin que conversa com os provedores — inclusive o código que transforma uma recusa da API na frase que o administrador lê — era a única que nada verificava. Duas fixtures alcançam isso agora: recording_client roda os call_* reais e captura o que eles montaram, e stub_transport_client responde a partir de um transporte simulado, para o parsing rodar de verdade, através de uma única costura (make_curl()).

O que continua descoberto está genuinamente fora do alcance de um teste unitário:

• local\export — download() e download_site() repassam para a API de dataformat e então chamam die(). As linhas que eles carregam estão cobertas; a resposta em si é coberta pelo Behat abaixo.
• local\client — resolve_dns() faz uma consulta DNS real, e make_curl() existe para ser substituído. A decisão que depende da consulta, incluindo o branch de DNS rebinding, está totalmente coberta via dns_stub_client.
• ai — uma linha: a guarda que recusa set_client_for_testing() fora de um teste, que por definição não pode rodar dentro de um.

Behat — Testes de Aceitação

php admin/tool/behat/cli/init.php
vendor/bin/behat --tags=@local_aihub --profile=chrome

🔐 Segurança e Conformidade

• Chaves pessoais protegidas por capability e opt-in (local/aihub:usepersonalkey e o toggle de site).
• Chaves pessoais write-only — nunca devolvidas à página após salvas, mesmo sob Entrar como.
• Chaves de site guardadas com admin_setting_configpasswordunmask; o guard SSRF protege o endpoint configurável.
• require_sesskey() no formulário de chaves; capability local/aihub:viewusage no relatório de uso.
• Cobertura completa da Privacy API (export/delete do log de uso e das preferências pessoais) com os destinos externos declarados.

🔎 Divulgação de Serviço de Terceiros

O hub transmite o texto do prompt a um provedor de IA de terceiros apenas quando uma chave está configurada e uma geração é solicitada.

Uma chave de API é obrigatória?

Não. O plugin instala e funciona sem nenhuma chave — apenas informa que não há fonte disponível, e os consumidores caem para a própria integração com core_ai. Nenhuma requisição externa é feita até que uma chave de site ou pessoal seja definida.

Provedores suportados

• Google Gemini — https://ai.google.dev/ — modelo: gemini-flash-latest (alias rolante, sempre a versão Flash atual do Google; fixo, não configurável)
• Groq — https://console.groq.com/ — modelo: openai/gpt-oss-120b (fixo, não configurável; ver Escolha do modelo Groq abaixo)
• DeepSeek — https://deepseek.com/ — modelo: deepseek-flash (fixo, não configurável)
• APIs compatíveis com OpenAI — qualquer provedor que siga o formato da API OpenAI (OpenRouter, modelos auto-hospedados via LM Studio, um proxy Ollama, etc.) — modelo: configurável por chave (config de site / chave pessoal), padrão gpt-4o-mini quando vazio

Esses serviços operam sob seus próprios termos de serviço e políticas de privacidade.

Escolha do modelo Groq

O slot da Groq chama um único modelo fixo, openai/gpt-oss-120b. A Groq descontinua periodicamente IDs de modelo específicos (ex.: llama-3.3-70b-versatile, descomissionado em 16/08/2026) e espera migração para um substituto nomeado. Entre as opções gratuitas recomendadas pela Groq para essa migração, o openai/gpt-oss-120b foi escolhido em vez do qwen/qwen3.6-27b por seguir instruções melhor e ser mais confiável em modo JSON entre os prompts variados enviados pelos diferentes plugins consumidores.

Como obter uma chave de API

As chaves de API são criadas diretamente no site oficial do provedor. Gemini, Groq e DeepSeek atualmente oferecem camadas de uso gratuitas ou créditos de teste (as políticas de preço podem mudar). O hub não fornece chaves de API.

Onde as chaves são configuradas

1. Chave pessoal — definida por cada usuário em Minhas chaves de IA (preferências), quando as chaves pessoais estão habilitadas e o usuário tem a capability.
2. Chave de site — definida pelo admin em Administração do site → Plugins → Plugins locais → Central de IA.

Transmissão de Dados

Quando uma chave é resolvida para um provedor, o texto do prompt é transmitido à API desse provedor para gerar a resposta:

• Google Gemini — generativelanguage.googleapis.com
• Groq — api.groq.com
• DeepSeek — api.deepseek.com
• Compatível com OpenAI — o endpoint configurado pelo admin ou usuário (padrão api.openai.com)

O hub guarda um log de uso (quem solicitou, qual componente, um rótulo curto do que foi gerado, provedor, modelo, tier da chave e horário), mas não guarda prompts nem respostas da IA. Todos os destinos externos estão declarados no Privacy provider do plugin.

Credenciais de demonstração

Não aplicável — nenhuma credencial é exigida para instalar ou usar o hub. Todo recurso de IA fica inerte até que uma chave de site ou pessoal seja configurada.

📄 Licença

Este projeto está licenciado sob a GNU General Public License v3 (GPLv3).

Copyright: 2026 Jean Lúcio