awslabs / awslabs/synthetically_engineered_evaluation_data
Rename the Generator facade (candidate: Synthesizer), keeping Generator as a deprecated alias
- Dominant language
- Python
- Stars
- 9
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
Deferred from the review on #15 so that PR could land on its fixes rather than on a rename. Cosmetic, but worth doing.
## The problem
`seed_data.api.Generator` is the package's single public entry point, and the name is wrong on two counts.
**It collides with a core Python concept.** From my inline comment on #15:
> We might want to consider a slightly more descriptive name than 'Generator' since this may confuse with the concept of a generator in core python.
A reader who sees `Generator` in a type annotation or a traceback has to work out that it is not a `typing.Generator`, not a generator function, and not something you iterate.
**It also undersells the surface, which was less true when the name was chosen.** Four of the thirteen public verbs generate nothing at all — they return schemas:
| Verb | Returns |
|---|---|
| `plan` | `InferredSchema` |
| `ingest` (deprecated alias for `plan`) | `InferredSchema` |
| `infer_schema` | `Schema` |
| `infer_packet` | a packet directory path |
That half arrived with the SEED unification (#14 / #15). The object is now a configured handle over two engines — plan *and* generate — and `Generator` names one of them.
## Candidate
**`Synthesizer`.** "Synthetic data" is the term of art and it matches the repo name; it reads correctly for both halves (`synth.plan(...)`, `synth.generate(...)`); and it collides with nothing in the stdlib or in this codebase.
```python
from seed_data import Synthesizer, ModelConfig
synth = Synthesizer(models=ModelConfig(data="gpt-oss"), output_dir="./output")
schema = synth.plan("orders.sql", "an orders dataset")
result = synth.generate_structured(schema, rows=500, seed=42)
doc = synth.generate("invoice", scenario="Q3 renewal")
```
Also considered:
- **`SeedClient`** — boto3-idiomatic and honest, since it genuinely is a client of Bedrock. Neutral as to verb. Stutters a little as `seed_data.SeedClient`, and "client" says nothing about the domain.
- **`Seed`** — shortest and most brandable, but it collides head-on with the `seed=` RNG parameter that #15 threaded through the structured path. `Seed(...).generate_structured(schema, seed=42)` is ambiguous in every code sample we'd write. Recommend against.
- **`Pipeline`** / **`Engine`** / **`Session`** — all already load-bearing internally (`stages/pipeline.py`, `structured/pipeline.py`, `ingest/pipeline.py`; "engines" is how `api.py` describes what the facade sits on; `seed_data/session.py`). Recommend against.
## Constraint: this cannot be a breaking change
`Generator` shipped in v0.0.6 as the documented entry point. Per @hayleypark on #15:
> **`Generator` is still your call.** It predates this work (yours, in `5fdd7c3`), shipped in v0.0.6 as the documented entry point, so renaming it breaks existing users.
And `docs/archive/planning/README.md` lists it as non-negotiable:
> | `Generator` API (`generate` / `generate_batch` / `generate_packet`) | Unchanged — same signatures, same typed returns |
So: **rename the class, keep `Generator` as a deprecated alias.** #15 already established the pattern for exactly this, twice — `Generator.ingest` → `plan` and the `ingest` / `run` CLI subcommands both dispatch with a deprecation warning.
## Scope
- [ ] Rename the class in `src/seed_data/api.py`
- [ ] `Generator` alias emitting `DeprecationWarning`, matching the `Generator.ingest` → `plan` pattern
- [ ] Export both from `seed_data/__init__.py` (note the lazy `__getattr__` there — both names need to resolve)
- [ ] Sweep `docs/docs/` to the new name; the alias stays documented as deprecated
- [ ] Test that the alias works *and* warns
- [ ] Leave `docs/archive/` untouched — frozen record
Non-goals: no signature changes, no verb renames, no behaviour change. Purely the class name plus the alias.
## Context
- #15 — where this came up; see the inline thread on `docs/docs/API-Reference/generator.md` and https://github.com/awslabs/synthetically_engineered_evaluation_data/pull/15#issuecomment-5604982871
- #14 — the unification that added the `plan` / `infer_*` half of the surface
Contributor guide
Research direction
Start in src/seed_data/api.py, then inspect the lazy exports in seed_data/__init__.py and the existing Generator.ingest → plan deprecation pattern. Sweep docs/docs/ for the public name while leaving docs/archive/ unchanged. Done means Synthesizer is exported, Generator remains a working deprecated alias that emits DeprecationWarning, and the alias behavior is tested.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, documentation
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100