ia-espirita/riv-ai-v2

🔮 RIV AI v2 — Modelo de IA Espírita Open Source

🆕 Versão 2.0 — atualização significativa. Esta é a evolução do RIV AI v1, agora baseada em Llama 3.1 e treinada com a obra de Allan Kardec praticamente completa: as 5 obras da Codificação + obras complementares + Revistas Espíritas (1858–1869). Dataset 4× maior que a v1.

RIV AI (homenagem a Hippolyte Léon Denizard Rivail — Allan Kardec) é um modelo de linguagem open-source treinado na Doutrina Espírita, conforme codificada e desenvolvida por Allan Kardec.

A v2 foi fine-tunada via QLoRA sobre o Llama 3.1 8B Instruct com um dataset expandido de 4.896 pares de pergunta/resposta extraídos da obra integral de Kardec. O objetivo é oferecer um assistente que responda sobre a Doutrina com fidelidade doutrinária e citação de fontes, servindo como ferramenta de estudo, divulgação e replicação científica.

"O Espiritismo é uma ciência que trata da natureza, origem e destino dos Espíritos, bem como de suas relações com o mundo corporal." — Allan Kardec, O Livro dos Espíritos, Introdução.

---

🆕 O que mudou da v1 para a v2

	v1	v2
Modelo base	Llama 3.0 8B Instruct	Llama 3.1 8B Instruct
Pares no dataset	~1.200	4.896 (4× maior)
Cobertura doutrinária	5 obras da Codificação	Codificação + Complementares + Revistas Espíritas
Épocas	3	2 (compensa o dataset maior, evita overfit)
Total de steps	~450	1.224
Loss final	0,64	0,74 (esperado e desejado — ver explicação abaixo)
Repositório	ia-espirita/riv-ai	ia-espirita/riv-ai-v2

Por que a loss da v2 é maior — e por que isso é positivo

A loss absoluta da v2 (0,74) é numericamente maior que a v1 (0,64), mas isso não significa pior qualidade. Pelo contrário:

• Dataset 4× maior = maior diversidade lexical e temática → o modelo generaliza em vez de memorizar
• 2 épocas vs 3 = redução intencional de exposição repetida → menos overfitting literal
• Cobertura ampliada = mais conceitos novos sendo aprendidos → loss converge mais alto, mas a representação é mais rica

Em resumo: a v1 ficou mais "decorada" no escopo restrito da Codificação. A v2 está mais "compreendendo" um corpus muito maior. Para uso real (RAG + geração), a v2 entrega respostas mais robustas e com contextualização mais ampla.

---

📦 Arquivos disponíveis

Arquivo	Formato	Tamanho	Uso
meta-llama-3.1-8b-instruct.Q4_K_M.gguf	GGUF 4-bit	~4,9 GB	Ollama, LM Studio, llama.cpp
adapter_model.safetensors	LoRA adapter	~168 MB	Transformers + PEFT (Python)
Modelo merged 16-bit	Safetensors (4 shards)	~16 GB	vLLM, deploy server

---

🎯 Para que serve?

Este modelo foi criado para responder perguntas sobre a Doutrina Espírita com:

• Precisão doutrinária — fundamentado na obra integral de Allan Kardec
• Citação de fontes — toda resposta referencia livro, questão e/ou capítulo
• Tom acolhedor e didático — como um amigo estudioso explicando Kardec
• Analogias modernas — traduz conceitos espíritas para linguagem contemporânea quando apropriado
• Português brasileiro — treinado nativamente em PT-BR

Exemplos de perguntas que o modelo responde:

Pergunta	Fonte da resposta
O que é Deus?	O Livro dos Espíritos, questão 1
Animais têm espírito?	O Livro dos Espíritos, questões 597-602
O que acontece quando morremos?	O Livro dos Espíritos, questões 149-165
O que é mediunidade?	O Livro dos Médiuns, cap. 14
O que é o perispírito?	O Livro dos Espíritos, questões 93-95
Como surgiu o Espiritismo?	Revista Espírita, 1858 / O Que É o Espiritismo
O que é o Espiritismo em poucas palavras?	O Que É o Espiritismo, "Resumo da Doutrina"
Como conduzir uma sessão mediúnica?	Instruções Práticas sobre as Manifestações Espíritas (1858)
Existe céu e inferno?	O Céu e o Inferno, Parte Primeira
Como fazer o Evangelho no Lar?	O Evangelho Segundo o Espiritismo, cap. 28
Ciência e Espiritismo se contradizem?	A Gênese, cap. 1

---

💻 Como usar

Com Ollama (mais fácil)

ollama run iaespirita/riv-ai-v2

Modelo disponível em: ollama.com/iaespirita/riv-ai-v2

Com LM Studio

1. Baixe o arquivo meta-llama-3.1-8b-instruct.Q4_K_M.gguf deste repositório
2. Abra o LM Studio e importe o arquivo
3. Configure o system prompt:

   Você é RIV AI, um assistente especializado em Doutrina Espírita. Responda de forma objetiva, didática e precisa, sempre citando a fonte (obra, questão ou capítulo) ao final. Use português brasileiro.

4. Comece a conversar

Com llama.cpp

llama-cli -hf ia-espirita/riv-ai-v2 --jinja

Com Transformers (Python)

from transformers import AutoTokenizer, AutoModelForCausalLM

model_name = "ia-espirita/riv-ai-v2"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

messages = [
    {"role": "system", "content": "Você é RIV AI, um assistente especializado em Doutrina Espírita. Responda de forma objetiva, didática e precisa, sempre citando a fonte (obra, questão ou capítulo) ao final. Use português brasileiro."},
    {"role": "user", "content": "O que acontece quando morremos?"}
]

input_ids = tokenizer.apply_chat_template(messages, return_tensors="pt")
output = model.generate(input_ids, max_new_tokens=512, temperature=0.7)
print(tokenizer.decode(output[0], skip_special_tokens=True))

Com vLLM (servidor OpenAI-compatible)

python -m vllm.entrypoints.openai.api_server \
    --model ia-espirita/riv-ai-v2 \
    --port 8000

---

📚 Fontes do treinamento

O dataset v2 foi construído a partir da obra integral de Allan Kardec em domínio público, organizada em três blocos:

Bloco 1 — Codificação Espírita (5 obras canônicas)

Obra	Ano	Estrutura	Tema central
O Livro dos Espíritos	1857	1.019 questões em 4 partes	Deus, espíritos, leis morais, vida futura
O Livro dos Médiuns	1861	32 capítulos, 370 itens	Mediunidade, manifestações e comunicação
O Evangelho Segundo o Espiritismo	1864	28 capítulos	Moral de Jesus à luz do Espiritismo
O Céu e o Inferno	1865	2 partes (doutrina + relatos)	Justiça divina, penas e recompensas futuras
A Gênese	1868	18 capítulos	Ciência e Espiritismo: criação, milagres, profecias

Bloco 2 — Obras complementares de Kardec

Obra	Ano	Estrutura	Tema central
Instruções Práticas sobre as Manifestações Espíritas	1858	Manual prático	Primeira obra de Kardec sobre o tema. Como conduzir reuniões mediúnicas, glossário inicial
O Que É o Espiritismo	1859	Opúsculo em 3 capítulos	Introdução em formato de diálogo: explica a Doutrina para iniciantes e céticos

Bloco 3 — Revistas Espíritas

Obra	Ano	Estrutura	Tema central
Revista Espírita — Jornal de Estudos Psicológicos	1858–1869	12 volumes anuais	Periódico mensal editado por Kardec. Artigos, comunicações mediúnicas, debates, comentários doutrinários, casos práticos

Todas as obras são de domínio público (Allan Kardec faleceu em 1869; obras publicadas entre 1857–1869).

---

🔧 Detalhes técnicos do treinamento

Parâmetro	Valor
Modelo base	meta-llama/Meta-Llama-3.1-8B-Instruct
Método	QLoRA (4-bit quantization)
Framework	Unsloth 2026.4.8 (2× faster)
Dataset	4.896 pares Q&A no formato ShareGPT
Idioma	Português Brasileiro
Hardware	NVIDIA Tesla T4 (Google Colab)
Precisão	fp16 (T4 não suporta bf16)
Épocas	2
Total steps	1.224
Batch size efetivo	8 (2 per device × 4 gradient accumulation × 1 GPU)
Learning rate	2e-4
LR scheduler	linear
Warmup steps	10
Weight decay	0,01
Optimizer	AdamW 8-bit
LoRA rank (r)	16
LoRA alpha	32
LoRA dropout	0
LoRA target modules	q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
Trainable parameters	41.943.040 / 8.072.204.288 (0,52%)
Max seq length	2048
Random seed	3407
Gradient checkpointing	Unsloth optimized
Tempo de treino	~1h50min em T4
GGUF quantization	Q4_K_M (~4,9 GB)

Curva de loss (amostragem a cada 20 steps)

Step    20  →  1,669   (warmup)
Step   100  →  1,010
Step   200  →  1,003
Step   300  →  0,969
Step   400  →  0,957
Step   500  →  0,958
Step   600  →  0,938   (fim da época 1)
Step   620  →  0,856   (início da época 2 — drop natural)
Step   700  →  0,762
Step   800  →  0,755
Step   900  →  0,741
Step  1000  →  0,731
Step  1100  →  0,741
Step  1180  →  0,742   (convergência)

A curva mostra duas fases distintas: descida acentuada no warmup → estabilização ao redor de 0,95 na primeira época → segundo drop quando inicia a segunda época → convergência estável em ~0,74.

---

📊 Dataset

O dataset está publicado em ia-espirita/riv-ai-v2-dataset.

Distribuição por bloco

Bloco	Pares aproximados
Codificação Espírita (5 obras)	~1.200
Obras complementares (Instruções Práticas + O Que É o Espiritismo)	~600
Revistas Espíritas (12 volumes)	~3.000
Temas modernos / sintéticos / existenciais	~100
Total	4.896

Formato

{
  "conversations": [
    {"from": "human", "value": "Animais têm alma segundo a Doutrina Espírita?"},
    {"from": "gpt", "value": "Sim, os animais possuem um princípio inteligente que sobrevive à morte do corpo físico. Esse princípio evolui progressivamente através dos reinos da natureza...\n\n📖 Fonte: O Livro dos Espíritos, questões 597-602."}
  ]
}

---

🔮 Por que "RIV"?

RIV é uma homenagem a Rivail — o verdadeiro nome de Allan Kardec.

Hippolyte Léon Denizard Rivail (1804-1869) foi o pedagogo francês que codificou a Doutrina Espírita. Ele adotou o pseudônimo "Allan Kardec" para separar seu trabalho acadêmico da obra espírita. O nome RIV AI conecta a tradição kardecista com a era da inteligência artificial — o passado e o futuro do conhecimento espírita.

---

⚠️ Limitações e uso responsável

• Este modelo é uma ferramenta de estudo, não substitui a leitura das obras originais de Allan Kardec.
• Citações específicas (questões, capítulos, itens) podem conter imprecisões. O modelo aprende a estrutura e o conceito doutrinário, mas pode ocasionalmente gerar numerações incorretas. Sempre verifique a citação na obra original.
• Não é um médium e não recebe mensagens de espíritos.
• Não faz previsões do futuro nem prescreve tratamentos médicos.
• Para questões de mediunidade prática, sempre procure um centro espírita presencialmente.
• Para temas sensíveis como suicídio, o modelo orienta o contato com o CVV (188).
• O dataset desta v2 cobre a obra de Allan Kardec. Para conteúdo da série André Luiz (psicografia de Chico Xavier), use o modelo companheiro ia-espirita/andre-luiz-ai. Obras de Emmanuel, Divaldo Franco e outros autores mediúnicos poderão ser incluídas em versões futuras.

---

🗺️ Roadmap

• v1.0 — Codificação Espírita (5 obras de Allan Kardec)
• v2.0 — Codificação + Instruções Práticas + O Que É o Espiritismo + Revistas Espíritas (este modelo)
• v3.0 — Obras de Emmanuel, Divaldo Franco e ESDE
• v4.0 — Versão em Espanhol (es)
• v5.0 — Versão em Inglês (en)

---

🌐 Projeto IA.Espirita

O RIV AI v2 é a versão open-source do projeto IA.Espirita — Doutrina Espírita na Era da Inteligência Artificial. O RIV IA (iaespirita.com) usa uma arquitetura mais robusta (modelo base maior com reasoning + RAG estrito sobre o mesmo corpus), enquanto este modelo é publicado como artefato de pesquisa, replicação e deploy offline.

Plataforma	Link
🌐 Site	iaespirita.com
🤖 RIV IA (chatbot)	Converse agora
▶️ YouTube	@ia.espirita
🎵 TikTok	@ia.esprita
📸 Instagram	@ia.espirita
🎧 Spotify	IA.Espirita Podcast
🐦 X/Twitter	@IAEspiritaBR
📧 E-mail	contato@iaespirita.com.br

---

📜 Licença

O modelo é distribuído sob licença Apache 2.0.

As obras de Allan Kardec utilizadas no treinamento são de domínio público (publicadas entre 1857-1869).

---

🙏 Citação

@misc{iaespirita2026rivaiv2,
  title={RIV AI v2: Modelo de IA Espírita Open Source baseado na obra integral de Allan Kardec},
  author={IA.Espirita},
  year={2026},
  url={https://huggingface.co/ia-espirita/riv-ai-v2},
  note={Fine-tuned on Llama 3.1 8B Instruct with QLoRA using Allan Kardec's complete works (Codification + Practical Instructions + What is Spiritism + Revue Spirite 1858-1869)}
}

---

🤝 Contribuições

Contribuições são bem-vindas. Se você é estudioso da Doutrina Espírita e/ou desenvolvedor:

• 📝 Revise e expanda o dataset com novas perguntas e respostas
• 🧪 Teste o modelo e reporte erros doutrinários (especialmente citações imprecisas)
• 🌍 Ajude a traduzir o dataset para espanhol e inglês
• 📚 Contribua com dados de obras mediúnicas para as próximas versões

Abra uma issue ou pull request neste repositório.

---

"Nascer, morrer, renascer ainda e progredir sem cessar, tal é a Lei."
— Allan Kardec, epitáfio em seu túmulo no cemitério Père-Lachaise, Paris.