docs: top-level README, repo reorg, sdist manifest

Add README.md orienting the three parts (Python naming feature, name
dataset, Rust port). Ship parquet + rust sources in sdist (MANIFEST.in),
ignore rust/target. Add scripts/bench_naming.py (Python perf harness).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jqueguiner

.gitignore

@@ -53,3 +53,6 @@ nosetests.xml
 *.ipr
 venv/
 .vscode
+
+# Rust port build artifacts
+rust/target/

MANIFEST.in

@@ -1,5 +1,10 @@
+include README.md
 include README.rst
 include README.upstream.rst
+include data/*.parquet
+include data/README.md
+recursive-include rust *.rs *.toml *.md
+recursive-exclude rust/target *
 include LICENSE.txt
 include CONTRIBUTING.rst
 include CHANGELOG.md

README.md

@@ -0,0 +1,64 @@
+# faker2 — fork with name intelligence + a Rust port
+
+This fork of [faker2](README.upstream.rst) adds three things on top of upstream:
+
+1. **Name intelligence** (`faker2/naming/`) — gender inference, gender-preserving
+   name replacement, and English grammatical-number agreement.
+2. **A real name ground-truth dataset** (`data/`) — 1.43M first names across 139
+   countries with gender + relative frequency, as Parquet.
+3. **A Rust port** (`rust/`) — the core engine + key providers + the same name
+   intelligence, re-implemented in Rust.
+
+Upstream faker docs: [`README.upstream.rst`](README.upstream.rst).
+
+## Repository layout
+
+```
+faker2/                 Python package (upstream faker fork)
+  naming/               ← added: name intelligence
+    gender.py             gender infer + preserving replace (bundled locales)
+    realnames.py          same, backed by data/ ground truth (needs pyarrow)
+    grammar.py            pluralize / singularize / agreement
+data/                   ← added: name ground truth
+  first_names.parquet     1.43M names, 139 countries, gender, relative frequency
+  last_names.parquet      small sample (surnames NOT comprehensive)
+  README.md               schema + provenance
+rust/                   ← added: Rust port
+  src/                    engine, providers, gender, grammar, realnames
+  README.md               crate docs
+tests/                  Python tests (incl. test_gender_grammar.py)
+```
+
+## Python — name intelligence
+
+```python
+from faker2.naming import realnames, grammar
+
+realnames.infer_gender("Jacques", "FR")       # "m"
+realnames.first_name_like("Jacques", "FR")    # frequency-weighted male FR name
+realnames.first_name("JP", "f")               # weighted female Japanese name
+
+grammar.pluralize("baby")                     # "babies"
+grammar.agree(3, "dog")                       # "3 dogs"
+```
+
+`realnames` needs `pyarrow` (in `dev-requirements.txt`). The bundled-locale
+variant `faker2.naming.gender` has no extra dependency.
+
+## Rust port
+
+```
+cd rust
+cargo test                          # zero-dependency core
+cargo run -- --seed 42 name
+cargo run -- like Jacques fr        # gender-preserving replacement
+cargo test --features real-names    # opt-in parquet ground truth
+```
+
+See [`rust/README.md`](rust/README.md).
+
+## Data provenance
+
+The name dataset was extracted from a PostgreSQL dump and normalized so
+`frequency` is a **relative share** — no raw population counts are exposed. See
+[`data/README.md`](data/README.md).

scripts/bench_naming.py

@@ -0,0 +1,40 @@
+"""Python perf harness — mirror of rust/examples/bench.rs."""
+import time
+
+from faker2 import Faker
+from faker2.naming import realnames as rn
+
+f = Faker()
+Faker.seed(42)
+
+# 1) basic name generation (upstream faker)
+n = 1_000_000
+t = time.perf_counter()
+sink = 0
+for _ in range(n):
+    sink += len(f.first_name())
+d = time.perf_counter() - t
+print(f"basic first_name(): {n} in {d:.3f}s = {n/d/1e6:.3f} M ops/s (sink {sink})")
+
+# 2) real-names bank load
+t = time.perf_counter()
+rn.infer_gender("Jacques", "FR")  # triggers load+build
+print(f"real bank load: {time.perf_counter()-t:.3f}s")
+
+# 3) gender-preserving replacement
+m = 1_000_000
+t = time.perf_counter()
+s2 = 0
+for _ in range(m):
+    s2 += len(rn.first_name_like("Jacques", "FR"))
+d = time.perf_counter() - t
+print(f"first_name_like: {m} in {d:.3f}s = {m/d/1e6:.3f} M ops/s (sink {s2})")
+
+# 4) infer only
+t = time.perf_counter()
+s3 = 0
+for _ in range(m):
+    if rn.infer_gender("Jacques", "FR") == "m":
+        s3 += 1
+d = time.perf_counter() - t
+print(f"infer_gender: {m} in {d:.3f}s = {m/d/1e6:.3f} M ops/s (sink {s3})")