Document model provenance and typed vocabulary

README.md

@@ -0,0 +1,51 @@
+---
+license: mit
+library_name: pytorch
+tags:
+  - name-generation
+  - character-level
+  - lstm
+---
+
+# Naamkaran
+
+Naamkaran is a character-level LSTM that generates candidate names conditioned
+on a starting character and a binary gender input. The Python package exposes
+generation controls for the ending character, maximum length, sample count,
+and softmax temperature.
+
+## Files
+
+- `naamkaran.pt`: PyTorch state dictionary for the generator.
+- `vocabulary.parquet`: ordered character vocabulary with one non-null string
+  column named `token`.
+
+The vocabulary is Parquet rather than a serialized scikit-learn vectorizer.
+This makes the token order explicit and removes version-sensitive pickle
+loading from inference.
+
+## Training data
+
+The model was trained on names from the early 2022 Florida voter registration
+data. The package documentation cites the source dataset at
+<https://doi.org/10.7910/DVN/UBIG3F>.
+
+## Intended use
+
+Use this model to generate synthetic name-like strings for demonstrations,
+testing, and exploratory applications. It is not a source of verified personal
+names or demographic labels.
+
+## Limitations
+
+The training population and collection period constrain what the model learns.
+Generated strings can reproduce spelling patterns, imbalance, errors, and
+social biases present in the voter data. The binary gender conditioning does
+not represent the full range of gender identities. Do not use generated names
+to infer identity, ethnicity, citizenship, eligibility, or other sensitive
+attributes, and do not treat them as representative population samples.
+
+## Reproducible loading
+
+The `naamkaran` package pins this repository to a full commit SHA. Downstream
+code should also pass a full commit SHA as `revision` when downloading files.