Skip to content

Document Generator

ydata.synthesizers.text.model.document.DocumentFormat

Bases: Enum

Enum representing supported output formats for synthetic document generation.

Attributes:

Name Type Description
DOCX

Microsoft Word document format (docx)
PDF

Portable Document Format (pdf)
HTML

HyperText Markup Language format (html)

ydata.synthesizers.text.model.utils.dataset_config.DatasetConfig dataclass

Configuration for dataset-level document generation.

Attributes:

Name Type Description
document_type str

Type of document to generate (e.g. "Invoice", "Report").
base Optional[Dict[str, str]]

Shared parameters applied to every document. Keys map to the existing generate() params (audience, tone, purpose, region, language, length, topics, style_guide).
variations Optional[Dict[str, Union[Dict[str, float], List[str], List[Dict]]]]

Fields that change across documents. Each key maps to either a weighted dict {"value": weight}, a uniform list ["value_a", "value_b"], or (for the special "profile" key) a list of dicts where each dict describes a realistic document profile with optional weight. Keys present here override the corresponding base value per-document. Supports boolean values for render flags, e.g. {"scanned": {True: 0.3, False: 0.7}} to produce 30 % scanned documents.
constraints Optional[Dict[str, Union[int, List[str]]]]

Structured directives translated into prompt text. Supported keys: must_include (list of strings), min_items (int), max_items (int).
data Optional[List[Dict[str, Any]]]

Optional[List[Dict[str, Any]]] = None per-document payloads (JSON-serializable dicts), one row per document. When set, the content-generation LLM is skipped; batch size is len(data)
Validation
  • If data is non-empty, base / variations / constraints are optional (may be omitted or empty).
  • If data is absent or empty, base must contain at least one entry.

ydata.synthesizers.text.model.document.DocumentGenerator

Synthetic document generator that creates documents in various formats (DOCX, PDF, HTML) based on input specifications.

Each generation step is delegated to an :class:Agent backed by an :class:~ydata.synthesizers.utils.llm.LLMBackend. Agents validate every LLM response against Pydantic output models to guarantee structured, reliable outputs.

Parameters:

Name Type Description Default
document_format DocumentFormat | str | None

Output format for generated documents.

 PDF
backend LLMProvider | str

LLM provider to use. Defaults to "workbench". Other accepted values: "openai", "anthropic" / "claude", "gemini" / "google". Non-Workbench backends are intended as a fallback when Workbench is unavailable.

 WORKBENCH
subscription_key str | None

API / subscription key for the chosen provider. When omitted, each backend reads its standard environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY). Workbench falls back to the embedded default for internal builds.

 None
model str | OpenAIModel | AnthropicModel | GeminiModel | WorkbenchModel | None

Model identifier. When omitted each backend uses its default.

 GPT5 
# Default — Workbench with embedded / env key
gen = DocumentGenerator()

# Workbench with explicit key and model
gen = DocumentGenerator(subscription_key="<key>", model="gpt-5-2025-08-07-dzs-eus2")

# Gemini fallback (key from GOOGLE_API_KEY env var)
gen = DocumentGenerator(backend="gemini")

# Gemini with explicit key
gen = DocumentGenerator(backend="gemini", subscription_key="AIza...", model="gemini-1.5-pro")

# OpenAI fallback
gen = DocumentGenerator(backend="openai", subscription_key="sk-...")

generate(document_type=None, audience=None, tone=None, purpose=None, region=None, language=None, length=None, topics=None, style_guide=None, data=None, output_dir=None, scanned=False, logo_path=None, **kwargs)

Generate documents based on input specifications.

Each call produces exactly one output document.

When data is provided, only document_type is required. User data is serialized as the document body; the content-generation LLM is skipped. Other parameters are optional hints for HTML generation.

When data is None, specifications are sampled/validated as before and the content LLM runs before HTML generation.

Parameters:

Name Type Description Default
document_type str | None

Type of document to generate (required if data is set; required for the LLM path when data is None).

 None
audience str | None

Target audience for the document

 None
tone str | ToneCategory | None

Desired tone (formal, casual, etc.)

 None
purpose str | None

Purpose of the document

 None
region str | None

Target region/locale

 None
language str | None

Language of the document

 None
length str | None

Desired length of the document

 None
topics str | None

Key points to cover

 None
style_guide str | None

Style guide to follow

 None
data dict[str, Any] | None

Structured payload for a single document; when set, body text is taken from this dict (JSON-serialized), not from the content agent.

 None
output_dir str | None

Directory to store generated documents

 None
scanned bool

When True, forces the pure black-and-white palette and injects scanner-simulation CSS (greyscale, ~0.3 px blur, reduced contrast, scan-line texture) before rendering. No visual effect on DOCX output.

 False
logo_path str | None

Optional path to a user-provided logo image (PNG, JPG, GIF, SVG, or WEBP). When set, the logo is embedded into each generated document's logo/brand slot (or the top of the page if the template has none). Adds no generation latency.

 None
**kwargs

Reserved for forward compatibility

 {}

Raises:

Type Description
ValueError

If input validation fails or document format is unsupported

 
gen = DocumentGenerator(document_format="pdf")

# Plain generation
gen.generate(document_type="invoice", topics="Q2 consulting services")

# With a user-provided logo — embedded into the template's logo /
# brand slot (or the top of the page when the template has none).
# Supported formats: PNG, JPG/JPEG, GIF, SVG, WEBP.
gen.generate(document_type="invoice", logo_path="assets/acme.png")

generate_dataset(config, n_docs=None, output_dir=None, seed=None, return_metadata=True, logo_path=None, max_workers=1, progress_callback=None)

Generate multiple documents from a :class:DatasetConfig.

This is an orchestrator that expands the config into n_docs per-document parameter sets (respecting weighted/uniform variation distributions) and calls :meth:generate once per document.

Parameters:

Name Type Description Default
config DatasetConfig

Dataset-level configuration describing base params, variations, and optional constraints.

 required
n_docs int | None

Number of documents to generate when config.data is None. Required and must be positive in that case. When config.data is set, n_docs is taken from len(config.data) and any explicit n_docs is ignored.

 None
output_dir str | None

Directory to store generated documents. A temporary directory is created when not provided.

 None
seed int | None

Optional seed for deterministic variation expansion.

 None
return_metadata bool

If True (default), return a list of metadata dicts describing the parameters used for each document.

 True
max_workers int

Optionally run up to this many document generations concurrently (capped at the document count — len(config.data) or the expanded job count — and a small fixed limit). None or 1 keeps sequential execution. Applies to both the config.data path and the variation-expansion path.

 1
logo_path str | None

Optional path to a user-provided logo image (PNG, JPG, GIF, SVG, or WEBP) embedded into every generated document.

 None
progress_callback Callable[[int, int], None] | None

Optional callable invoked as progress_callback(completed, total) once per document as it finishes, where completed is the running count and total is the overall document count for this call. Called for both the config.data path and the variation-expansion path, and in both sequential and concurrent execution (when concurrent, it fires as each document actually finishes, not in submission order).

 None

Returns:

Type Description
list[dict[str, Any]] | None

A list of metadata dicts (one per document) when
list[dict[str, Any]] | None

return_metadata is True, otherwise None.

Raises:

Type Description
ValueError

If document count is undefined or invalid (empty config.data, or missing/non-positive n_docs when config.data is not used).

generate_from_template(document_type, information, output_dir, template_img_path, logo_path=None, n_docs=None, max_workers=1, progress_callback=None)

Generate documents by applying content to an image-derived HTML template.

The vision-extracted skeleton is reused across all information items so every output document shares the same visual design. Content injection is handled by _inject_content_into_template (the same agent used by the standard generate path) rather than a bespoke inline agent.

Parameters:

Name Type Description Default
document_type str

Type of document (e.g. "invoice").

 required
information list | str

One or more strings describing the content to place inside the template. A single string is treated as a one-item list.

 required
output_dir str

Directory where output files are written.

 required
template_img_path str | list[str]

Path to a reference image or PDF from which the HTML template skeleton is derived (via vision), or a list of paths — one page per entry, in visual document order (e.g. ["page1.png", "page2.png", "page3.png"]) — to derive a multi-page template with one <div class="page"> per page, in the same order as the entries. A single image path behaves exactly as before (one-page template). Any entry may be a PDF instead of an image: every page of the PDF is rasterized and expanded in place, so a single multi-page PDF (template_img_path="contract.pdf") — or a mix, e.g. ["cover.png", "contract.pdf"] — works the same as passing each page as its own image. Requires the pymupdf package when a PDF is used.

 required
logo_path str | None

Optional path to a user-provided logo image (PNG, JPG, GIF, SVG, or WEBP) embedded into every generated document.

 None
n_docs int | None

Optional expected document count, validated against information. When information is a single item (str/dict) and n_docs > 1, that item is broadcast across n_docs independent documents (each still gets its own content injection + render pass). When information already has more than one item, n_docs — if provided — must equal len(information); a mismatch raises ValueError. Defaults to len(information) when omitted.

 None
max_workers int

When more than one document will be generated, optionally run up to this many per-item pipelines (content injection + render) concurrently — capped at the item count and a small fixed limit. None or 1 keeps the default behaviour of processing every item together as a single batch (content injection is already internally parallelized across items in that case, so this only matters for larger item counts where explicit control over concurrency — e.g. to bound render-step load — is useful).

 1
progress_callback Callable[[int, int], None] | None

Optional callable invoked as progress_callback(completed, total). In the concurrent per-item path (max_workers > 1 and multiple items) it fires once per document as it actually finishes. In the default single-batch path there is no per-document granularity to report (all items are injected/rendered together in one pipeline call), so it fires once at the end with completed == total.

 None

Returns:

Type Description
list[str]

List of output file paths.

Raises:

Type Description
ValueError

If n_docs does not match the number of items in information (when information already has more than one item), or if n_docs is not a positive integer.