README.md

---
license: cc-by-nc-4.0
library_name: onnx
pipeline_tag: text-generation
language:
- en
tags:
- onnx
- pytorch
- lstm
- character-level
- procedural-generation
- planet-names
- non-commercial
---

# Planet Namer

Planet Namer is a tiny character-level LSTM that generates science-fiction
planet names from seven normalized planet attributes. It was built for
on-device use in *Starbound Exodus* and exported as a fixed-shape,
single-token ONNX model.

This repository is licensed for **non-commercial use only** under
[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/). See
[`LICENSE`](LICENSE) for the repository-specific notice.

## Model details

| Property | Value |
| --- | --- |
| Architecture | Single-layer character LSTM with stat-conditioned initial state, per-step stat concatenation, and FiLM conditioning |
| Parameters | 226,242 |
| Vocabulary | 66 tokens (63 characters plus PAD/SOS/EOS) |
| Maximum output length | 20 characters |
| Hidden / embedding size | 192 / 64 |
| Inputs | Five fixed-shape tensors; see below |
| Outputs | Next-character logits and recurrent hidden/cell states |

The seven input values must be in `[0, 1]` and in this exact order:

1. `atmosphere`
2. `gravity`
3. `resources`
4. `lifesigns`
5. `temperature`
6. `water`
7. `radiation`

## Files

- `planet_namer_fp16.onnx` — recommended compact ONNX export (448 KiB)
- `planet_namer.onnx` — FP32 ONNX export (888 KiB)
- `planet_namer_checkpoint.pt` — PyTorch state dictionary
- `vocab.json` — vocabulary, token IDs, stat order, and dimensions
- `inference.py` — minimal ONNX Runtime command-line example
- `train.py` — architecture, training, evaluation, and export code

The ONNX model is a single-step recurrent model. On the first step, pass the
real stat vector to both `stats_init` and `stats`, along with zero `h_in` and
`c_in`. On later steps, pass zeros to `stats_init`, keep passing the real
values to `stats`, and feed the previous `h_out` and `c_out` back into the
model.

## Usage

Install the lightweight inference dependencies:

```bash
python -m pip install -r requirements.txt
```

Generate a name from the seven stats:

```bash
python inference.py \
  --stats 0.9 0.8 0.7 0.9 0.6 0.8 0.1 \
  --temperature 0.8 \
  --seed 42
```

Use `--temperature 0` for greedy decoding. Higher temperatures increase
variation. The helper validates the stat count and range before inference.

The PyTorch checkpoint is a state dictionary, not a serialized executable
model. Instantiate `PlanetNameLSTM` from `train.py` with a vocabulary size of
66, then load the state dictionary with `weights_only=True`.

## Training data

The model was trained on 1,957 planet and location names collected from these
fictional universes: Star Trek, Mass Effect, Warhammer 40,000, Star Wars,
Dune, Babylon 5, Halo, Stargate, Firefly, Foundation, and The Expanse.
The conditioning values are hand-authored or synthetic metadata. When several
names shared the same stat vector, the training pipeline deterministically
spread those values using orthographic properties of each name.

The raw name lists are **not included in this model repository**. Names and
marks from the referenced fictional universes may be protected by copyright,
trademark, or other rights belonging to their respective owners. This release
does not grant rights to any third-party material.

## Evaluation

The following results were reproduced from the released checkpoint with seed
42 and the training script's stratified 80/10/10 split (1,564 / 194 / 199):

| Metric | Result |
| --- | ---: |
| Training exact match at temperature 0.1 | 82.35% (1,288 / 1,564) |
| Test exact match at temperature 0.1 | 77.39% |
| Test mean Levenshtein distance | 1.87 |
| Novelty at temperature 1.0 | 88.5% (200 generated samples) |
| Generated-vs-training character-bigram KL | 0.2901 |

These are development diagnostics, not a benchmark. In particular, the
name-derived collision spreading leaks orthographic information into the
conditioning values, making held-out exact-match results optimistic. The
novelty result is a single seeded sampling run and will vary.

## Intended use

Intended uses are non-commercial creative experiments, games, prototypes,
research, and procedural-content tooling where a user wants short fictional
planet-name suggestions conditioned on normalized attributes.

The model is not intended for factual astronomy, scientific classification,
identity-related naming, or commercial products and services. Review generated
names before publication.

## Limitations and risks

- The model can reproduce or closely resemble names seen during training.
- Outputs may resemble protected franchise names or marks; novelty is not a
  clearance check.
- The training corpus is small, English-centric, and dominated by a few
  fictional universes.
- The stat/name relationship is partly synthetic and should not be interpreted
  as semantic ground truth.
- Sampling can produce empty, awkward, truncated, or mixed-case strings.
- The ONNX graphs use fixed batch size 1 and fixed recurrent-state dimensions.

Users are responsible for reviewing outputs, respecting third-party rights,
providing attribution, and complying with the non-commercial license.

## License

The model weights, ONNX exports, vocabulary, and repository-authored code and
documentation are released under the
[Creative Commons Attribution-NonCommercial 4.0 International License](https://creativecommons.org/licenses/by-nc/4.0/).
Third-party names and marks are excluded from that grant.