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 Optional[Union[DocumentFormat, str]]

Output format for generated documents.

 PDF
backend Union[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 Optional[str]

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 Optional[Union[str, OpenAIModel, AnthropicModel, GeminiModel, WorkbenchModel]]

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 Optional[Dict[str, Any]]

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 Optional[str]

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 Optional[str]

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, max_workers=None, logo_path=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 Optional[int]

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 Optional[str]

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

 None
seed Optional[int]

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 Optional[int]

When config.data is set, optionally run up to this many document generations concurrently (capped at len(config.data) and a small fixed limit). None or 1 keeps sequential execution.

 None
logo_path Optional[str]

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

 None

Returns:

Type Description
Optional[List[Dict[str, Any]]]

A list of metadata dicts (one per document) when
Optional[List[Dict[str, Any]]]

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)

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 Union[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

Path to a reference image from which the HTML template skeleton is derived (via vision).

 required
logo_path Optional[str]

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

 None

Returns:

Type Description
List[str]

List of output file paths.