README.md

---
base_model: HauhauCS/Qwen3.5-4B-Uncensored-HauhauCS-Aggressive
library_name: peft
license: mit
language:
  - ja
pipeline_tag: text-generation
tags:
  - roleplay
  - character
  - japanese
  - qwen
  - lora
  - gguf
  - uncensored
  - desktop-companion
metrics:
  - character-consistency
---

# Inaba Meguru LoRA (因幡めぐる)

A lightweight Japanese roleplay LoRA for Qwen3.5-4B.

> 🐾 This model powers **[InabaPet](https://github.com/wallouo/InabaPet)** — a desktop AI companion with chat, vision, voice, and head-pat interactions, running entirely on-device.

## Overview

This project aims to recreate **Inaba Meguru (因幡めぐる)** from *Sabbat of the Witch* (サノバウィッチ) as faithfully as possible while remaining lightweight enough to run entirely on consumer hardware.

The original goal was simple:

> I wanted Meguru to live on my desktop.

Unlike general-purpose chat models, this LoRA focuses on character roleplay and is designed primarily for desktop companion applications and immersive conversations.

The model is trained on [HauhauCS/Qwen3.5-4B-Uncensored-HauhauCS-Aggressive](https://huggingface.co/HauhauCS/Qwen3.5-4B-Uncensored-HauhauCS-Aggressive). Although it is still a 4B model with some unavoidable limitations, it offers a significant improvement over my previous desktop companion model based on Qwen2.5 while remaining completely free to run locally without API costs.

## Quick Start

### Ollama (recommended)

```bash
# 1. Download meguru_q4_k_m.gguf + Modelfile from this repo's Files tab
# 2. Import into Ollama (run in the download folder):
ollama create meguru -f Modelfile
# 3. Run
ollama run meguru
```

### Hugging Face + Ollama (one-liner)

```bash
ollama run hf.co/wallouo/Inaba
```

### llama.cpp

```bash
./llama-cli -m meguru_q4_k_m.gguf -p "めぐる、おはよう！" -t 4 --temp 0.8 --top-p 0.9 --min-p 0.05
```

### Python (transformers + PEFT)

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained(
    "HauhauCS/Qwen3.5-4B-Uncensored-HauhauCS-Aggressive",
    torch_dtype="auto",
    device_map="auto",
)
model = PeftModel.from_pretrained(base_model, "wallouo/Inaba")
tokenizer = AutoTokenizer.from_pretrained("wallouo/Inaba")

messages = [{"role": "user", "content": "めぐる、おはよう！"}]
inputs = tokenizer.apply_chat_template(messages, return_tensors="pt").to(model.device)
output = model.generate(**inputs, max_new_tokens=120, temperature=0.8, top_p=0.9, min_p=0.05)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

## Hardware Requirements

| Item | Value |
|---|---|
| Model size (GGUF Q4_K_M) | 2.71 GB |
| Min VRAM | ~4 GB |
| Recommended VRAM | 6–8 GB (for comfortable multi-turn context) |
| Tested on | NVIDIA RTX 4060 8GB VRAM, Ollama |
| Context length | 4096 |
| Runtime | Ollama, llama.cpp |

## Features

- Faithful Meguru personality
- Natural Japanese roleplay
- Optimized for local inference (Q4_K_M GGUF)
- Lightweight 4B model — runs on consumer GPUs
- Suitable for desktop companion applications
- Designed for immersive conversations instead of general question answering

## Training Information

| Item | Value |
|---|---|
| Base Model | [HauhauCS/Qwen3.5-4B-Uncensored-HauhauCS-Aggressive](https://huggingface.co/HauhauCS/Qwen3.5-4B-Uncensored-HauhauCS-Aggressive) |
| Fine-tuning Method | LoRA (QLoRA 4-bit) |
| Framework | Unsloth |
| Quantization | Q4_K_M (GGUF) |
| Language | Japanese |
| Dataset Size | 891 conversations |
| Learning Rate | 1e-4 |
| Training Steps | 280 |
| Hardware | NVIDIA RTX 4060 8GB VRAM |

The training converged smoothly, with the loss decreasing from approximately 4.3 to 1.31, indicating healthy and stable optimization.

## Dataset

The dataset was not created by simply collecting dialogue from the visual novel. Instead, a significant amount of time was spent refining the data to maximize character consistency.

The overall pipeline included:

1. **Character dialogue extraction** — pulled protagonist + Meguru lines from game scripts
2. **Removal of noisy and out-of-character samples** — filtered plot-only narration and non-distinctive responses using an LLM-based cleaner
3. **AI-assisted dialogue expansion** — generated additional conversations to strengthen multi-turn depth and low-emotion daily dialogue
4. **Multi-turn conversation generation** — chained single exchanges into coherent conversation threads
5. **Emotion balancing** — ensured coverage across emotional states to avoid mode collapse
6. **Manual refinement and quality review** — hand-checked for persona consistency

The goal was always quality over quantity.

## Recommended Generation Settings

The following settings consistently produced the most natural roleplay performance during testing.

| Parameter | Value |
|---|---|
| Temperature | 0.8 |
| Top_p | 0.9 |
| Min_p | 0.05 |
| Top_k | Disabled |

### Why is Top_k disabled?

During experimentation, I found that enabling both Min_p and Top_k often caused the 4B model to become noticeably less coherent.

For example, with `Min_p = 0.08` and `Top_k = 40`, the model frequently became almost unable to produce complete sentences, repeatedly generating outputs such as:

> 「っ……っ……」

Disabling Top_k completely resolved this issue while maintaining creativity and response quality.

## Modelfile

The `Modelfile` included in this repo configures Ollama with the system prompt, generation parameters, and chat template needed to reproduce Meguru's character behavior. See the file in the **Files and versions** tab.

## Example Conversation

One of Meguru's defining personality traits is that she is energetic, cheerful, and not particularly academic. The following conversation demonstrates that behavior.

| Role | Text |
|---|---|
| **User** | めぐる、最近量子力学の本を読んでるんだけど、「シュレーディンガーの猫」って何なの？全然わからない…… |
| **Meguru** | えええ！？ ち、当然だ！量子力学なんて、絶対無理っしょ！？ |
| **Translation** | "Ehhh!? O-Of course! Quantum mechanics is impossible to understand!" |

Instead of attempting to explain quantum physics, Meguru responds exactly the way her character would — honest, lively, and completely overwhelmed by the topic. Maintaining this kind of personality consistency is the primary objective of this LoRA.

## Known Limitations

Although the dataset has gone through multiple rounds of refinement, some issues still remain due to the limitations of current 4B language models.

Common issues include:

- Speaker confusion
- Role drift during long conversations
- Occasionally inventing previous dialogue
- Cross-language contamination
- Reduced character consistency over extended contexts

Based on my experiments, these issues appear to originate primarily from the reasoning limitations of the base model rather than the dataset itself.

### Example: Cross-language Contamination

One interesting failure case observed during testing:

| Role | Text |
|---|---|
| **User** | 一緒にベッドで寝よう。 |
| **Meguru** | 単純に、お昼の休憩時にちょっとだけベッドしたくなったってだけだし！ |

The phrase **ベッドしたくなった** is not natural Japanese. The model incorrectly translated the Chinese concept of "wanting to lie on the bed" into Japanese by treating ベッド as a verb.

A native speaker would naturally say something like:

- ベッドで寝たくなった
- ベッドで横になりたくなった

This type of multilingual semantic interference is one of the common weaknesses of current lightweight multilingual language models and is extremely difficult to eliminate completely through LoRA training alone.

## Evaluation

Due to the subjective nature of character roleplay, no standard benchmark was used. Instead, qualitative assessment was performed across the following dimensions:

| Dimension | Rating (1–5) | Notes |
|---|---|---|
| Character consistency | 4 | Strong persona adherence in short-to-medium conversations |
| Japanese naturalness | 4 | Fluent output with occasional cross-language contamination |
| Multi-turn stability | 3 | Role drift appears in extended contexts (>20 turns) |
| Emotion range | 4 | Covers cheerful, flustered, embarrassed states well |

## Development Notes

One thing I learned while developing this project is that improving a character model is not only about collecting more data. After repeatedly refining the dataset, cleaning noisy samples, expanding conversations, adjusting prompts, and retraining the LoRA, I found that most remaining issues were no longer caused by the dataset itself.

Instead, they mainly stem from the reasoning and contextual limitations of today's 4B language models.

I'm looking forward to revisiting this project when future small models become more capable, require less VRAM, or when parameter-efficient fine-tuning techniques continue to improve.

## Intended Use

**This model is intended for:**

- Character roleplay
- Desktop companion projects
- AI VTuber experiments
- Local Japanese conversation
- Personal entertainment

**This model is NOT intended for:**

- General-purpose chat assistance
- Knowledge question answering
- Factual or professional advice
- Any commercial deployment involving the character

## License

The LoRA adapter weights are released under the **MIT License**.

> **Important:** The character **Inaba Meguru (因幡めぐる)** is a copyrighted character from *Sabbat of the Witch* (サノバウィッチ) by **Yuzusoft**. This project is a fan-made, non-commercial work created for personal entertainment and technical exploration. All character rights belong to Yuzusoft.

## Acknowledgements

This project exists because I genuinely like Inaba Meguru.

I hope this model can bring a little happiness to anyone who enjoys her character as much as I do.

If you find this project useful, feel free to leave a ❤️ on Hugging Face or share your feedback.

Thank you for trying the model.