Greptile Summary

This PR exposes on_batch_complete as an optional parameter on DataDesigner.create, allowing callers to register a per-batch callback without accessing engine internals directly. The change is a thin pass-through: the new parameter is collected at the create boundary and forwarded unchanged to builder.build().

• data_designer.py: Adds on_batch_complete: Callable[[Path], None] | None = None to create, updates the docstring, and inserts the argument into the builder.build() call.
• test_data_designer.py: Adds a focused unit test that mocks the builder and asserts the callback is forwarded by identity to builder.build().

Important Files Changed

sequenceDiagram
    participant Caller
    participant DataDesigner
    participant DatasetBuilder

    Caller->>DataDesigner: "create(config_builder, on_batch_complete=cb)"
    DataDesigner->>DataDesigner: _create_resource_provider(...)
    DataDesigner->>DataDesigner: _create_dataset_builder(...)
    DataDesigner->>DatasetBuilder: "build(num_records=N, on_batch_complete=cb, resume=mode)"
    loop Each batch
        DatasetBuilder-->>Caller: cb(batch_artifact_path)
    end
    DatasetBuilder-->>DataDesigner: (complete)
    DataDesigner-->>Caller: DatasetCreationResults

_{Reviews (4): Last reviewed commit: "Add note about exceptions to docstring" | Re-trigger Greptile}

PR #663 Review — Expose on_batch_complete via DataDesigner.create

Summary

Threads an existing engine-level on_batch_complete: Callable[[Path], None] | None parameter
out through the public DataDesigner.create method on the interface package, so users can
register a per-batch callback without reaching into engine internals. Closes #662.

The change is minimal (47/-1) and surgical:

• packages/data-designer/src/data_designer/interface/data_designer.py: add the kwarg and
  forward it to builder.build(...).
• packages/data-designer/tests/interface/test_data_designer.py: a unit test asserting the
  callback is forwarded with identity to the underlying builder.

Findings

Correctness

• Signature matches the engine: dataset_builder.py:223 declares
  on_batch_complete: Callable[[Path], None] | None = None, identical to the new
  interface kwarg. The forwarding call uses keyword args, so positional drift is
  not a risk.
• Default None preserves existing behavior — a pure additive change with no
  caller impact.
• Callable is imported from collections.abc (the project convention) rather
  than typing, consistent with from __future__ import annotations already in
  use in this file.

Project conventions

• Follows the layering rules in AGENTS.md: interface forwards into engine; no
  reverse imports. ✅
• Type annotations and modern syntax (Callable[[Path], None] | None) align with
  STYLEGUIDE expectations. ✅
• Docstring entry added in the Args: section, matching the existing style of
  surrounding parameters.

Test coverage

• test_create_forwards_on_batch_complete_callback asserts identity (is) on the
  forwarded callback and the num_records kwarg — a tight, focused check. Good.
• The test only exercises the wiring; behavior of the callback (invocation per
  batch, path correctness) remains covered by engine-level tests. That separation
  of concerns is appropriate for an interface-layer change.
• Minor nit: the dummy callback uses del path to silence "unused argument"
  lint, which is fine but def on_batch_complete(_path: Path) -> None: pass
  would be more idiomatic. Not blocking.

Risk / blast radius

• Backward compatible: new kwarg with a default of None.
• No public-API break; no changes to engine, config, or CLI.
• No performance implications — the callback is only invoked on batch completion
  in the engine; this PR doesn't add any per-record overhead.

Documentation

• Public-facing docstring is updated. Consider whether the Fern docs site
  (fern/) has an example or API reference that should mention
  on_batch_complete on create(). If create() is auto-generated from the
  signature, no action needed; otherwise a short note + tiny example would help
  users discover the feature. Not blocking.

Verdict

LGTM. Small, well-scoped, test-covered, backward compatible, and consistent with
the layering invariants in AGENTS.md. The only optional follow-up is verifying
the docs site surfaces the new parameter; everything else is good as-is.