Blame for README.md

---
license: apache-2.0
base_model: aimeri/Ministral-3-3B-Base-2512-chatml
base_model_relation: finetune
datasets:
- aimeri/name-generator
language:
- en
library_name: transformers
pipeline_tag: text-generation
tags:
- names
- character-names
- creative-writing
- ministral3
- chatml
- unsloth
---

# Name Generator

Ask for a name, get one name back and nothing else. A 3.4B fine-tune of Ministral 3 that answers
requests like "a Brazilian man's name" or "a woman from the Ottoman Empire" with names drawn from real
naming data, instead of the handful of names language models keep reaching for (Elara Voss, Kael
Thorne, Dr. Sarah Chen).

> **v2 is out:** [aimeri/name-generator-v2](https://huggingface.co/aimeri/name-generator-v2) also
> invents fantasy names (elves, dwarves, orcs, dragons, fantasy kingdoms) and keeps the real ones.

GGUF quants (Q8_0, Q6_K, Q5_K_M, Q4_K_M) for llama.cpp, LM Studio and similar:
[aimeri/name-generator-GGUF](https://huggingface.co/aimeri/name-generator-GGUF)

## Examples

From the Q8_0 GGUF in llama.cpp: the greedy answer, then the first four distinct samples at
temperature 0.8.

| Request | Greedy | Sampled |
|---|---|---|
| What is a good male Brazilian name? | Lucas Silva | Alexandre Silva · Felipe Barbosa · Lucas Fernandes · Filipe Nogueira |
| Japanese woman's name | Kobayashi Masako | Maeda Yumi · Mizukami Masako · Kamimura Natsuko · Terada Shiori |
| German man born in the 1950s | Michael Schmidt | Gerhard Schülke · Jürgen Beyer · Michael Engel · Hermann Hoffmann |
| Give me a Russian man's full name | Vladimir Sergeyevich Kolesnikov | Maxwell Sergeevich Semyonov · Sergey Dmitriyevich Lebedev · Vasily Aleksandrovich Kolesnikov · Pavel Gusev |
| I need a name for a Mexican grandmother | María Teresa Martínez | Olivia García · María Díaz · María Teresa Díaz · Marina Rueda |
| A name from the Song dynasty | Zhu Xiu | Wei Xuan · Zhong Yuan · Zhao Xiu · Qian Zhong |

## Usage

Needs transformers 5.x (the architecture is `Ministral3ForCausalLM`).

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

repo = "aimeri/name-generator"
tokenizer = AutoTokenizer.from_pretrained(repo)
model = AutoModelForCausalLM.from_pretrained(repo, dtype="bfloat16", device_map="auto")

def names(request, n=5, temperature=0.8):
    text = tokenizer.apply_chat_template([{"role": "user", "content": request}],
                                         tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(text, return_tensors="pt").to(model.device)  # adds <s>, as in training
    out = model.generate(**inputs, max_new_tokens=24, do_sample=True, temperature=temperature,
                         num_return_sequences=n)
    start = inputs["input_ids"].shape[1]
    return [tokenizer.decode(o[start:], skip_special_tokens=True).strip() for o in out]

print(names("Give me a Brazilian woman's name"))
```

Two details matter:

- **Render, then tokenize.** The ChatML template emits no `<s>`; the tokenizer adds it when it encodes
  the rendered text. `apply_chat_template(..., tokenize=True)` skips it, which is not what the model was
  trained on.
- **Plain-string content.** The template trims `content` as a string; a list of `{"type": "text"}`
  parts ends up in the prompt as its Python repr.

Through an OpenAI-compatible server (llama.cpp, vLLM, LM Studio) send a single user message with
`max_tokens` around 24. The model ends its turn with `<|im_end|>` (the eos token).

### Getting good names

- Name a country or nationality ("Nigerian", "from Peru"), a historical state ("Ottoman Empire",
  "Soviet Union", "Song dynasty") or a region ("West African").
- Add sex and era for more control: "a woman born in the 1950s" shifts the first names to that decade.
- Names follow local conventions: family name first for Chinese, Japanese, Korean, Hungarian and
  Vietnamese; patronymics in Russian and Ukrainian full names; two surnames in Spanish and Portuguese
  full names.
- Sample at temperature 0.7–1.0 and ask once per character. Greedy decoding returns the single most
  typical name every time.

## Training

| | |
|---|---|
| Base | [aimeri/Ministral-3-3B-Base-2512-chatml](https://huggingface.co/aimeri/Ministral-3-3B-Base-2512-chatml): the text-only Ministral-3-3B-Base-2512 with `<|im_start|>`/`<|im_end|>` claimed for ChatML |
| Data | [aimeri/name-generator](https://huggingface.co/datasets/aimeri/name-generator/tree/v1), tag `v1`: 8,536 training and 459 validation examples covering 333 countries and historical states (24% historical) |
| Method | Supervised fine-tuning with Unsloth and TRL, full fine-tune, loss on the assistant turn only |
| Hyperparameters | learning rate 1e-5, linear schedule, 5% warmup, 1 epoch (2,134 steps), effective batch size 4, AdamW 8-bit, weight decay 0.001 |
| Software | transformers 5.20.2, Unsloth 2026.10.9 |

Each example pairs a request with one name. The names were sampled from real frequency data
(national statistics offices such as the US SSA and Census, INSEE, ONS, INE, IBGE, PESEL, SSB and
SCB; Wikidata people by citizenship and birth decade; Faker and Mimesis locale lists), by country,
sex and birth decade. Ministral-3-3B-Instruct-2512 wrote the requests from each name's metadata. See
the dataset card for details.

## Limitations

- **Real-world names only.** There were no fantasy names in training. Asked for an elf name, it
  returns English-sounding names ("Lily Lore", "Zoe Lightfoot").
- **Always a full name.** The training data had no first-name-only or surname-only answers, so
  "a Nigerian surname" still gets a full name.
- **Sex can slip** when sampling: asked for a woman's name from the Ottoman Empire, some samples are
  men's names.
- **Coverage follows the data.** Where a country has no official name statistics, names come from
  Wikidata's notable people, who skew older, male and elite. Some pairings reflect expatriates or
  data errors (a "Maxwell Sergeevich" among the Russian names).
- **Short English requests.** Training used single-turn requests of about one sentence.
- **Not real people.** Outputs are combinations of real given names and surnames. Any match with a
  real person is coincidental. Don't use this to identify people, infer anyone's background, or
  make documents.

## License

Apache 2.0, following the base model. The training dataset is CC BY-SA 4.0.