README.md

---
license: apache-2.0
datasets:
- TinyModels/jjk-wiki-corpus
language:
- en
pipeline_tag: text-generation
tags:
- RAG
- Qwen2.5
- Jujutsu-Kaisen
- Anime
- Knowledge-Bot
- Retrieval-Augmented-Generation
---

<div align="center">

# 🟣 JujutsuKaiserver

### *The Cursed Intelligence. The Canon Oracle.*

[![Model](https://img.shields.io/badge/Base-Qwen2.5--1.5B--Instruct-blueviolet?style=for-the-badge)](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct)
[![Quantization](https://img.shields.io/badge/Quantization-4--bit-purple?style=for-the-badge)](https://huggingface.co/TinyModels/JujutsuKaiserver)
[![RAG](https://img.shields.io/badge/RAG-FAISS%20Powered-darkviolet?style=for-the-badge)](https://huggingface.co/TinyModels/JujutsuKaiserver)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=for-the-badge)](LICENSE)
[![Dataset](https://img.shields.io/badge/Dataset-jjk--wiki--corpus-orange?style=for-the-badge)](https://huggingface.co/datasets/TinyModels/jjk-wiki-corpus)

<br/>

> *"Throughout Heaven and Earth, I alone am the honored one."*  
> — **Satoru Gojo** | and also this model, kind of.

<br/>

**JujutsuKaiserver** is a Retrieval-Augmented Generation (RAG) model built for one purpose:  
to answer anything and everything about the **Jujutsu Kaisen** universe — with canon-backed accuracy, zero hallucination tolerance, and the confidence of Unlimited Void.

</div>

---

## ⚡ What It Does

Ask it anything. Techniques. Domains. Arcs. Hidden lore. Character relationships. Cursed Energy mechanics. It retrieves the most relevant passages from a **200+ page wiki corpus**, feeds them into a fine-tuned **Qwen2.5-1.5B-Instruct** backbone, and gives you a clean, grounded answer — not a guess.

| Ask This | Get This |
|----------|----------|
| *"What is Sukuna's Shrine?"* | Full technique breakdown with canon context |
| *"How does Mahito's Idle Transfiguration work?"* | Soul-level mechanics explained accurately |
| *"What happened in the Shibuya Incident?"* | Arc summary backed by wiki chunks |
| *"Who is the strongest Grade 1 sorcerer?"* | Ranked answer with sourced reasoning |

---

## 🧠 Architecture

```
User Query
    │
    ▼
sentence-transformers (all-MiniLM-L6-v2)
    │  [embed query]
    ▼
FAISS Index (jjk_index.faiss)
    │  [top-5 relevant wiki chunks]
    ▼
Qwen2.5-1.5B-Instruct (4-bit)
    │  [context + question → chat template]
    ▼
Canon-grounded Answer
```

### Model Composition

| Component | Details |
|-----------|---------|
| 🤖 **Base LLM** | `Qwen/Qwen2.5-1.5B-Instruct` (4-bit quantized) |
| 🔢 **Embeddings** | `sentence-transformers/all-MiniLM-L6-v2` |
| 📦 **Vector Store** | FAISS — `jjk_index.faiss` |
| 📖 **Knowledge Base** | 120+ cleaned JJK Fandom Wiki articles (`chunks.txt`) |
| 🔧 **Pipeline** | Custom `JujutsuKaiserver` class with Qwen chat template |

---

## 🚀 Quick Start

```python
from huggingface_hub import snapshot_download

model_dir = snapshot_download("TinyModels/JujutsuKaiserver")

import sys
sys.path.insert(0, model_dir)
from pipeline import JujutsuKaiserver

bot = JujutsuKaiserver(model_dir=model_dir)

# Ask anything
print(bot.ask("What is Gojo's Domain Expansion called?"))
# → "Infinite Void (無量空処). It..."
```

> ⚠️ **Requirements**: `bitsandbytes`, GPU with **≥6 GB VRAM**. CPU inference works but is slow.

### Install Dependencies

```bash
pip install transformers bitsandbytes faiss-cpu sentence-transformers huggingface_hub
```

---

## 🖥️ Gradio Demo (Optional)

Spin up a local chat UI in seconds:

```python
import gradio as gr
from pipeline import JujutsuKaiserver

bot = JujutsuKaiserver(model_dir="<path_to_downloaded_model>")

def chat(message, history):
    return bot.ask(message)

gr.ChatInterface(
    fn=chat,
    title="🟣 JujutsuKaiserver",
    description="Ask anything about the JJK universe."
).launch()
```

---

## ✨ Features

- 🔍 **Factual Q&A** — Every answer is grounded in retrieved wiki content, not imagination
- 🚫 **Hallucination Guard** — Model is prompted to say *"I don't know"* when context is insufficient
- 📚 **Deep Coverage** — 200+ wiki pages: characters, techniques, domains, arcs, lore
- ⚡ **T4-Friendly** — 4-bit quantization means it runs on free Colab tiers
- 🤖 **Gradio Ready** — One-script local demo included out of the box

---

## ⚠️ Known Limitations

- **Recent chapters** beyond the scraping date may not be indexed yet
- **Ambiguous context** can still occasionally produce imperfect answers — being addressed via a feedback loop
- **Roleplay mode** is possible with a custom system prompt, but this version is optimized for factual retrieval

---

## 🔮 Roadmap

- [ ] **Live Feedback Flagging** — 👍/👎 votes from the Gradio Space feed a correction dataset automatically
- [ ] **Self-Correcting Pipeline** — Weekly DPO fine-tuning on flagged examples + FAISS index refresh
- [ ] **Expanded KB** — Episode transcripts, manga panels text, community lore
- [ ] **Streaming Support** — Token-by-token output for snappier UX

---

## 📂 Repo Structure

```
JujutsuKaiserver/
├── pipeline.py          # Core RAG pipeline class
├── jjk_index.faiss      # FAISS vector index
├── chunks.txt           # Raw wiki knowledge base
├── generation_config.json
└── README.md
```

---

<div align="center">

**Built with 🩸 and cursed energy for the JJK community.**

*Got a question the bot fumbled? Open a [Discussion](https://huggingface.co/TinyModels/JujutsuKaiserver/discussions) and help us fix it.*

`TinyModels` • `QuantaSparkLabs` • Apache 2.0

</div>