awslabs / awslabs/synthetically_engineered_evaluation_data

Rename the Generator facade (candidate: Synthesizer), keeping Generator as a deprecated alias

Open
#26 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.