Instructions to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with llama-cpp-python:

# !pip install llama-cpp-python

from llama_cpp import Llama

llm = Llama.from_pretrained(
	repo_id="ia-espirita/riv-ai-v2-Q4_K_M-GGUF",
	filename="riv-ai-v2-q4_k_m.gguf",
)

llm.create_chat_completion(
	messages = [
		{
			"role": "user",
			"content": "What is the capital of France?"
		}
	]
)

Notebooks
Google Colab
Kaggle
Local Apps

llama.cpp

How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with llama.cpp:

Install from brew

brew install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama-server -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M
# Run inference directly in the terminal:
llama-cli -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Install from WinGet (Windows)

winget install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama-server -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M
# Run inference directly in the terminal:
llama-cli -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Use pre-built binary

# Download pre-built binary from:
# https://github.com/ggerganov/llama.cpp/releases
# Start a local OpenAI-compatible server with a web UI:
./llama-server -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M
# Run inference directly in the terminal:
./llama-cli -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Build from source code

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build -j --target llama-server llama-cli
# Start a local OpenAI-compatible server with a web UI:
./build/bin/llama-server -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M
# Run inference directly in the terminal:
./build/bin/llama-cli -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Use Docker

docker model run hf.co/ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

LM Studio
Jan

vLLM

How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "ia-espirita/riv-ai-v2-Q4_K_M-GGUF"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "ia-espirita/riv-ai-v2-Q4_K_M-GGUF",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Ollama
How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with Ollama:
```
ollama run hf.co/ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M
```

Unsloth Studio

How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with Unsloth Studio:

Install Unsloth Studio (macOS, Linux, WSL)

curl -fsSL https://unsloth.ai/install.sh | sh
# Run unsloth studio
unsloth studio -H 0.0.0.0 -p 8888
# Then open http://localhost:8888 in your browser
# Search for ia-espirita/riv-ai-v2-Q4_K_M-GGUF to start chatting

Install Unsloth Studio (Windows)

irm https://unsloth.ai/install.ps1 | iex
# Run unsloth studio
unsloth studio -H 0.0.0.0 -p 8888
# Then open http://localhost:8888 in your browser
# Search for ia-espirita/riv-ai-v2-Q4_K_M-GGUF to start chatting

Using HuggingFace Spaces for Unsloth

# No setup required
# Open https://huggingface.co/spaces/unsloth/studio in your browser
# Search for ia-espirita/riv-ai-v2-Q4_K_M-GGUF to start chatting

How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with Pi:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama-server -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Configure the model in Pi

# Install Pi:
npm install -g @mariozechner/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Hermes Agent new

How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with Hermes Agent:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama-server -hf ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Configure Hermes

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Run Hermes

hermes

Docker Model Runner
How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with Docker Model Runner:
```
docker model run hf.co/ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M
```

Lemonade

How to use ia-espirita/riv-ai-v2-Q4_K_M-GGUF with Lemonade:

Pull the model

# Download Lemonade from https://lemonade-server.ai/
lemonade pull ia-espirita/riv-ai-v2-Q4_K_M-GGUF:Q4_K_M

Run and chat with the model

lemonade run user.riv-ai-v2-Q4_K_M-GGUF-Q4_K_M

List all available models

lemonade list

🔮 RIV AI v2 — GGUF Q4_K_M 🇧🇷

GGUF Q4_K_M version of ia-espirita/riv-ai-v2 — an AI model specialized in Allan Kardec's Spiritist Doctrine, fine-tuned on Llama 3.1 8B Instruct via QLoRA. Ready to run with Ollama, LM Studio, llama.cpp or any GGUF-compatible runtime.

🚀 Quick Start

The easiest way — Ollama

ollama run iaespirita/riv-ai-v2

Or directly from this repo (no need to publish locally):

ollama run hf.co/ia-espirita/riv-ai-v2-Q4_K_M-GGUF

With llama.cpp (Mac / Linux)

brew install llama.cpp

llama-cli \
  --hf-repo ia-espirita/riv-ai-v2-Q4_K_M-GGUF \
  --hf-file riv-ai-v2-q4_k_m.gguf \
  -p "O que é o perispírito segundo a Doutrina Espírita?" \
  -c 2048

With Python

pip install llama-cpp-python

from llama_cpp import Llama

llm = Llama.from_pretrained(
    repo_id="ia-espirita/riv-ai-v2-Q4_K_M-GGUF",
    filename="riv-ai-v2-q4_k_m.gguf",
    n_ctx=2048,
)

response = llm.create_chat_completion(
    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": "Animais têm espírito?"},
    ],
    temperature=0.2,
    max_tokens=512,
)

print(response["choices"][0]["message"]["content"])

ℹ️ Note: the model is trained in Brazilian Portuguese and responds in Portuguese. The system prompt and user inputs above are in Portuguese by design.

💬 Sample responses

What is the perispirit?

According to The Spirits' Book, the perispirit is a semi-material, fluidic envelope that surrounds the body of the Spirit like a transparent membrane. It has special properties, allowing the Spirit to act upon matter, becoming extensible and penetrating as needed. This envelope is indispensable for the Spirit's communication with the material world.

📖 Source: The Spirits' Book, questions 93-95.

Do animals have a spirit?

Yes, according to Spiritism, animals possess a spiritual principle that distinguishes them from material body, just as humans do. This principle is the germ of the Spirit, which develops and refines itself through reincarnations, beginning in the simplest races of organic beings.

📖 Source: The Spirits' Book, questions 597-602.

How did Spiritism come about?

Spiritism emerged in the mid-19th century from Allan Kardec's systematic studies of the table-turning phenomena and mediumistic communications. In 1857 he published The Spirits' Book, the founding milestone of the Doctrine, and in 1858 launched the Revue Spirite — Journal d'Études Psychologiques, a monthly publication that would document the evolution of the Doctrine until 1869.

📖 Source: Revue Spirite, 1858, January.

⚠️ About the citations: the model cites sources correctly in concept, but the specific numbering of questions/chapters may occasionally have inaccuracies. Always validate against the original work at Kardecpedia.

📦 Available variants

Version	For whom	Where
GGUF Q4_K_M (this repo)	Local use with Ollama / LM Studio / llama.cpp	`riv-ai-v2-Q4_K_M-GGUF`
16-bit + LoRA adapter	Research, vLLM, derivative fine-tuning	`riv-ai-v2`
RIV IA online (with RAG)	Direct use, no installation	iaespirita.com
Ollama Hub	One-command install	`iaespirita/riv-ai-v2`

🔧 Specifications

Attribute	Value
Base model	`meta-llama/Meta-Llama-3.1-8B-Instruct`
Fine-tuning	QLoRA (rank 16, alpha 32) via Unsloth
Dataset	`ia-espirita/riv-ai-v2-dataset` — 4,896 Q&A pairs
Quantization	Q4_K_M (4-bit, k-quants medium)
Size	~4.9 GB
Context	2,048 tokens
Language	Brazilian Portuguese
GGUF conversion	via GGUF-my-repo

🎯 What the model covers

Trained on Allan Kardec's complete public-domain works (1857–1869):

Topic	Primary source
God and His qualities	The Spirits' Book
Reincarnation and moral laws	The Spirits' Book
Mediumship and its forms	The Mediums' Book
Life after death	Heaven and Hell
Christian morality from a Spiritist perspective	The Gospel According to Spiritism
Science, creation, miracles	Genesis
History of the Spiritist movement	Revue Spirite (12 volumes, 1858–1869)
Practical mediumistic sessions	Practical Instructions (1858)
Doctrine summary for beginners	What is Spiritism (1859)

🛠️ Ollama Modelfile (reference)

To customize locally:

FROM ./riv-ai-v2-q4_k_m.gguf

TEMPLATE """{{ if .System }}<|start_header_id|>system<|end_header_id|>

{{ .System }}<|eot_id|>{{ end }}{{ if .Prompt }}<|start_header_id|>user<|end_header_id|>

{{ .Prompt }}<|eot_id|>{{ end }}<|start_header_id|>assistant<|end_header_id|>

{{ .Response }}<|eot_id|>"""

SYSTEM """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."""

PARAMETER stop "<|start_header_id|>"
PARAMETER stop "<|end_header_id|>"
PARAMETER stop "<|eot_id|>"
PARAMETER stop "<|begin_of_text|>"
PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER num_ctx 2048

ollama create my-riv -f Modelfile
ollama run my-riv

⚠️ Limitations

Study tool — does not replace reading Kardec's original works.
Specific citations (question/chapter numbers) may have inaccuracies. The model learns the doctrinal concept faithfully, but the exact numbering should always be validated against the source.
It is not a medium and does not receive messages from spirits.
It does not make predictions nor prescribe medical treatments.
For sensitive topics (suicide, emotional crisis), seek professional help or call CVV: 188 (Brazil) / your local crisis line.

🌐 IA.Espirita Project

Resource	Link
🌐 Website (RIV IA online with RAG)	iaespirita.com
🤗 HF Model (16-bit + adapter)	`ia-espirita/riv-ai-v2`
📚 Dataset	`ia-espirita/riv-ai-v2-dataset`
🦙 Ollama Hub	`iaespirita/riv-ai-v2`
▶️ YouTube	@ia.espirita
📸 Instagram	@ia.espirita
🎵 TikTok	@ia.esprita
🎧 Podcast	Spotify
📧 Contact	contato@iaespirita.com.br

📜 License

Distributed under Apache 2.0.

The works of Allan Kardec used in training are in the public domain (published between 1857–1869; Kardec passed away on March 31, 1869).

🙏 Citation

@misc{iaespirita2026rivaiv2gguf,
  title={RIV AI v2 — GGUF Q4_K_M: Open Source quantized Spiritist AI Model},
  author={IA.Espirita},
  year={2026},
  url={https://huggingface.co/ia-espirita/riv-ai-v2-Q4_K_M-GGUF},
  note={GGUF Q4_K_M conversion of ia-espirita/riv-ai-v2, fine-tuned on Llama 3.1 8B Instruct with Allan Kardec's complete public-domain works (Codification + Practical Instructions + What is Spiritism + Revue Spirite 1858-1869)}
}

"To be born, to die, to be reborn again and progress unceasingly, such is the Law."
— Allan Kardec, epitaph on his tomb at the Père-Lachaise cemetery, Paris.

Downloads last month: 364

GGUF

Model size

8B params

Architecture

llama

Hardware compatibility

4-bit

Model tree for ia-espirita/riv-ai-v2-Q4_K_M-GGUF

Base model

meta-llama/Llama-3.1-8B

Finetuned

meta-llama/Llama-3.1-8B-Instruct