Create README.md

README.md

@@ -0,0 +1,184 @@
+---
+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>