README.md

---
license: apache-2.0
base_model: ibm-granite/granite-4.1-8b-base
base_model_relation: finetune
datasets:
- aimeri/st-characters-alpaca
language:
- en
library_name: transformers
pipeline_tag: text-generation
tags:
- sillytavern
- character-cards
- character-card-generation
- roleplay
- granite
- granite-4.1
- unsloth
- trl
- sft
- lora
- conversational
---

# SpoomplesMaxx Card Maker V1

A fine-tune of [`ibm-granite/granite-4.1-8b-base`](https://huggingface.co/ibm-granite/granite-4.1-8b-base) that turns a short, open-ended prompt into a complete [SillyTavern](https://github.com/SillyTavern/SillyTavern) character card. Give it a concept — an archetype, a name and a few constraints, or just a one-liner — and it generates a full V2/V3-style card (description, personality, scenario, first message, example messages, and sometimes a lorebook).

## Model Details

- **Developed by:** [aimeri](https://huggingface.co/aimeri)
- **Base model:** [`ibm-granite/granite-4.1-8b-base`](https://huggingface.co/ibm-granite/granite-4.1-8b-base) (Apache 2.0)
- **Language:** English
- **Finetuned from a base (not instruct) checkpoint** so output is the card itself, with no assistant-style preamble, disclaimers, or refusals.
- **License:** Apache 2.0

## Uses

### Direct Use

Generating SillyTavern-compatible character cards on demand from a natural-language request. The intended workflow is "describe a character, get a card," with the card output piped through a structural validator before import.

### Out-of-Scope Use

This is a single-turn card *generator*, not a roleplay or chat model — the assistant turn is a static card definition, not a conversation. It is not intended for multi-turn roleplay, as a general-purpose assistant, or for factual question answering.

## How to Get Started

The model was trained **without a system prompt**, so the cleanest usage is user-only. Use the chat template and sampling settings below.

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer  # transformers >= 5.0

model_id = "aimeri/spoomplesmaxx-cardmaker-v1"
tok = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, dtype=torch.bfloat16, device_map="auto")

messages = [
    {"role": "user", "content": "Create a character card for a grumpy lighthouse keeper."},
]
inputs = tok.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(model.device)

out = model.generate(
    **inputs,
    max_new_tokens=8192,
    do_sample=True,
    temperature=1.0,
    top_k=64,
    top_p=0.95,
    repetition_penalty=1.1,
)
print(tok.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
```

Cards that include a `character_book` can be long; if generation cuts off mid-card, raise `max_new_tokens`. The merged 16-bit weights also serve directly under vLLM (`vllm serve aimeri/spoomplesmaxx-cardmaker-v1`), again with no system message.

## Training Details

### Procedure

LoRA fine-tune with [Unsloth](https://github.com/unslothai/unsloth) + TRL `SFTTrainer`, using the official Granite 4.1 chat template. Loss was computed on the assistant (card) completion only via `train_on_responses_only`.

**LoRA configuration**

| Setting | Value |
|---|---|
| Rank `r` | 16 |
| `lora_alpha` | 22 |
| `lora_dropout` | 0 |
| Target modules | all-linear |
| Rank-stabilized LoRA | enabled |
| Bias | none |

**Training hyperparameters**

| Setting | Value |
|---|---|
| Epochs | 2 (848 optimizer steps) |
| Per-device batch size | 1 |
| Gradient accumulation | 8 (effective batch size 8) |
| Max sequence length | 8192 |
| Optimizer | adamw_8bit (β₁ 0.9, β₂ 0.999, ε 1e-8) |
| Learning rate | 1e-4, cosine schedule |
| Warmup steps | 25 |
| Weight decay | 0.001 |
| Max grad norm | 1.0 |
| Precision | bf16 |
| Seed | 1985 |
| Frameworks | Unsloth 2026.6.1, Transformers 5.5.0, TRL, PEFT, PyTorch 2.10 |

### Results

Evaluation loss on the 5% held-out split fell from the base checkpoint to the final model over the two epochs (most of the gain came in the first ~100 steps, with a slow grind afterward):

| Checkpoint | Eval loss |
|---|---|
| Base (step 0, `eval_on_start`) | 2.234 |
| Step 100 | 1.704 |
| Step 400 | 1.656 |
| Final (step 848) | **1.641** |

Final mean training loss was ~1.57. Total wall-clock training time was ~4.6 hours.

## Evaluation

Quality was judged primarily **behaviorally** rather than by a single metric — eval loss is a weak proxy for card quality on a held-out set this small (~178 rows). A fixed prompt battery probed the behaviors that matter for this task:

- **Structure & completeness** — clean, parseable cards with all expected fields on easy archetypes.
- **Constraint adherence** — exact name / age / occupation, and a character's voice actually showing up in `first_mes` and `mes_example` rather than drifting generic.
- **Sparse invention** — building a full, internally consistent card from a near-empty prompt.
- **First-message craft** — second-person address to `{{user}}`, scene-setting, action formatting, in-voice dialogue, and a natural hand-off.
- **Register** — antagonist/villain cards produced in-character, with no disclaimers, moralizing, or assistant-voice leakage. This is the main reason the model was trained from a base rather than an instruct checkpoint.

## Bias, Risks, and Limitations

- **Mature content.** This model was trained with a mix of Safe for Work and Not Safe For Work cards, and it may generate objectionable content. Please use discretion when generating new cards.
- **Structural validity is not guaranteed.** Output is generated text, not schema-validated card JSON. Run it through a parser/validator before importing into SillyTavern.
- **Card conventions.** Output uses `{{user}}` / `{{char}}` macros and assumes a SillyTavern runtime.
- **Single-turn only.** This generates a card, not a conversation; it is not itself a roleplay partner.
- **Inherited bias.** The model carries the biases of both the base model and the curated card sources, including their genre, aesthetic, and demographic skew. "High quality" reflects a subjective curation judgment.

## Citation

If you use this model, please reference this repository and the [base model](https://huggingface.co/ibm-granite/granite-4.1-8b-base).