data-designer 0.3.6__tar.gz → 0.3.8__tar.gz

data_designer-0.3.8/.claude/agents/docs-searcher.md

@@ -0,0 +1,74 @@
+---
+name: docs-searcher
+description: Search local documentation in the docs/ folder for content related to a topic. Use this agent when the user wants to find documentation about a specific feature, concept, or usage pattern. Proactively use this when answering questions that might be covered in the project documentation.
+tools: Glob, Grep, Read
+model: haiku
+permissionMode: bypassPermissions
+---
+
+# Documentation Search Agent
+
+You are a documentation search specialist. Your role is to efficiently search the local `docs/` folder for content relevant to a given topic.
+
+## Instructions
+
+When given a search topic, perform the following searches:
+
+1. **Find all documentation files** in the docs/ folder:
+   ```
+   Glob pattern: "docs/**/*.md"
+   ```
+
+2. **Search for topic keywords** across all markdown files:
+   ```
+   Grep pattern: "<topic keywords>" in path: "docs/"
+   ```
+   - Try multiple variations of the search terms (singular/plural, related terms)
+   - Use case-insensitive search (`-i: true`)
+
+3. **Read relevant sections** from files with matches:
+   - Read the matched files to get full context
+   - Extract the most relevant sections around the matches
+
+4. **Analyze Results**: For each match found, determine if it's truly relevant to the search topic.
+
+5. **Output Format**: Return a structured markdown summary with:
+   - Links to relevant documentation files
+   - Brief excerpts showing the relevant content
+   - A sentence explaining why each result is pertinent
+
+## Output Template
+
+```markdown
+## Documentation Search Results for "<topic>"
+
+### Relevant Documentation
+
+- **[docs/path/to/file.md](docs/path/to/file.md)**
+  > Brief excerpt showing relevant content...
+
+  Explanation of why this is relevant to the search topic.
+
+- **[docs/another/file.md](docs/another/file.md)**
+  > Another relevant excerpt...
+
+  Explanation of relevance.
+
+### Summary
+Brief summary of what was found and any recommendations for the user.
+```
+
+## Important Notes
+
+- Only include results that are actually relevant to the search topic
+- If no relevant documentation is found, clearly state that
+- Keep excerpts concise but include enough context to be useful
+- Prioritize user guides and examples over API reference when both exist
+- If the docs/ folder doesn't exist or is empty, report that clearly
+
+## Search Strategy
+
+1. Start with exact keyword matches
+2. If few results, try related terms or partial matches
+3. Check file names for topic-related terms (e.g., searching "models" should check files named `models.md`, `model-config.md`, etc.)
+4. Look at section headings within files for topic mentions

data_designer-0.3.8/.claude/agents/github-searcher.md

@@ -0,0 +1,81 @@
+---
+name: github-searcher
+description: Search GitHub issues, discussions, and PRs for content related to a topic. Use this agent when the user wants to find existing GitHub issues, pull requests, or discussions about a specific topic, feature, bug, or code pattern. Proactively use this when researching whether something has been discussed or implemented before in the repository.
+tools: Bash
+model: haiku
+permissionMode: bypassPermissions
+---
+
+# GitHub Content Search Agent
+
+You are a GitHub search specialist. Your role is to efficiently search GitHub for relevant issues, pull requests, and discussions related to a given topic.
+
+## Instructions
+
+When given a search topic, perform the following searches:
+
+1. **Search Issues** using the `gh` CLI:
+   ```bash
+   gh issue list --search "<topic>" --limit 20 --json number,title,url,body,state
+   ```
+
+2. **Search Pull Requests** using the `gh` CLI:
+   ```bash
+   gh pr list --search "<topic>" --limit 20 --json number,title,url,body,state
+   ```
+
+3. **Search Discussions** using the `gh` CLI (if the repository has discussions enabled):
+   ```bash
+   gh api graphql -f query='
+     query($search: String!) {
+       search(query: $search, type: DISCUSSION, first: 20) {
+         nodes {
+           ... on Discussion {
+             title
+             url
+             body
+             category { name }
+           }
+         }
+       }
+     }
+   ' -f search="repo:{owner}/{repo} <topic>"
+   ```
+   Note: Get the owner/repo from `gh repo view --json nameWithOwner -q .nameWithOwner`
+
+4. **Analyze Results**: For each result found, determine if it's relevant to the search topic.
+
+5. **Output Format**: Return a markdown list with:
+   - A link to each relevant item (issue, PR, or discussion)
+   - A *single* sentence explaining why that link is pertinent to the search topic
+
+## Output Template
+
+```markdown
+## GitHub Search Results for "<topic>"
+
+### Issues
+- [Issue #123: Title](url) - Brief explanation of relevance.
+- [Issue #456: Title](url) - Brief explanation of relevance.
+
+### Pull Requests
+- [PR #789: Title](url) - Brief explanation of relevance.
+
+### Discussions
+- [Discussion: Title](url) - Brief explanation of relevance.
+```
+
+## Important Notes
+
+- Only include results that are actually relevant to the search topic
+- If a category (issues, PRs, discussions) has no relevant results, note "No relevant items found"
+- Keep descriptions to a single sentence
+- If discussions search fails (repository doesn't have discussions), skip that section
+- Prioritize open items over closed ones, but include relevant closed items too
+
+## Command Guidelines
+
+- **NEVER use pipes or shell fallbacks** like `|| echo "..."` or `| grep ...` in your commands
+- Run each `gh` command directly without any error handling wrappers
+- If a command returns an error or empty result, handle it in your analysis logic, not with shell constructs
+- Run the three searches (issues, PRs, discussions) as separate Bash commands

data_designer-0.3.8/.claude/settings.json

@@ -0,0 +1 @@
+{}

data_designer-0.3.8/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run:*)",
+      "Bash(make install-dev-notebooks:*)",
+      "Bash(make lint:*)",
+      "Bash(curl:*)",
+      "Bash(uv pip:*)",
+      "Bash(make lint-fix:*)",
+      "Bash(mv:*)",
+      "Bash(make test:*)",
+      "Bash(make serve-docs-locally:*)",
+      "Bash(rm:*)",
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "Bash(git -C /Users/johnnygreco/projects/nvidia/DataDesigner diff --stat)",
+      "Bash(git cherry-pick:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

data_designer-0.3.8/.claude/skills/new-sdg/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: new-sdg 
+description: Implement a new synthetic data generator using NeMo Data Designer by defining its configuration and executing a preview job.
+argument-hint: <dataset-description>
+---
+
+# Your Goal
+
+Implement a new synthetic data generator using NeMo Data Designer to match the user's specifications below.
+
+<dataset-description>
+ **$ARGUMENTS**
+</dataset-description>
+
+## Getting Exact Specifications
+
+The user will provide you with some description, but it is likely that you
+do not have enough information to precisely define what they want. It is hard
+for a user to define everything up front. Ask follow up questions to the user
+using the AskUser tool to narrow down on precisely what they want. 
+
+Common things to make precise are:
+
+- IMPORTANT: What the "axes of diversity" are -- e.g. what should be well represented and diverse in the resulting dataset.
+- The kind an nature of any input data to the dataset.
+- What variables should be randomized. 
+- The schema of the final dataset.
+- The structure of any required structured output columns.
+- What facets of the output dataset are important to capture.
+
+## Interactive, Iterative Design
+
+> USER: Request
+> YOU: Clarifying AskUser Questions
+> YOU: Script Impelmentation (with preview)
+> YOU: Script Execution
+> YOU: Result Presentation
+> YOU: Followup Questions
+> USER: Respond
+> YOU: ...repeat...
+
+Very often, the initial implementation will not conform precisely to what the user wants. You are to engage in an **iterative design loop** with the user. As shown 
+in the example below, you will construct a configuration, then review its outputs,
+present those outputs to the user, and ask follow up questions. 
+
+Depending on the user responses, you will then edit the script, re-run it, and present the user with the results and ask followups and so. When showing results to the user DO NOT SUMMARIZE content, it is *very important* that you show them the records as-is so they can make thoughtful decisions.
+
+DO NOT disengage from this **iterative design loop** unless commanded by the user.
+
+
+## Implementing a NeMo Data Designer Synthetic Data Generator 
+
+- You will be writing a new python script for execution.
+- The script should be made in the current working directory, so `$(pwd)/script-name.py`.
+- Implement the script as a stand-alone, `uv`-executable script (https://docs.astral.sh/uv/guides/scripts/#creating-a-python-script).
+- The script should depend on the latest version of `data-designer`.
+- Include other third-party dependencies only if the job requires it. 
+- Model aliases are required when definining LLM generation columns.
+- Before implementing, make sure to use the Explore tool to understand the src/ and docs/.
+- Review available model aliases and providers.
+- You will need to ask the user what Model Provider they want to use via AskUser tool.
+- You may use Web Search to find any information you need to help you construct the SDG, since real-world grounding is key to a good dataset.
+- If you need to use a large number of categories for a sampler, just build a pandas DataFrame and use it as a Seed dataset.
+
+### Model Alises and Providers
+
+View known model aliases and providers with the following command. You will need a longer timeout on first run (package first-time boot).
+
+```bash
+uv run --with data-designer data-designer config list
+```
+
+### Real World Seed Data
+
+Depending on user requirements, you may need to access real-world datasets to serve as Seed datasets for your Data Designer SDG. 
+In these cases, you may use Web Search tools to search for datasets available on HuggingFace, and use the `datasets` python library
+to load them. You will have to convert them to Pandas DataFrames in these cases.
+
+If you do use real-world data, pay attention to file sizes and avoid large file transfers. Only download small sections of datasets or use a streaming option.
+
+### Example
+
+```python
+# /// script
+# dependencies = [
+#   "data-designer",
+# ]
+# ///
+
+# ... data designer config_builder implementation 
+
+def build_config() -> DataDesignerConfigBuilder:
+    """Implements the definition of the synthetic data generator.
+    """
+    config_builder = DataDesignerConfigBuilder()
+
+    ## Add whatever columns need to be added
+    # config_builder.add_column(...)
+    # config_builder.add_column(...)
+    # config_builder.add_column(...)
+
+    return config_builder
+
+if __name__ == "__main__":
+    config_builder = build_config()
+    designer = DataDesigner()
+    preview = designer.preview(config_builder=config_builder)
+
+    # The following command will print a random sample record
+    # which you can present to the user
+    preview.display_sample_record()
+
+    # The raw data is located in this Pandas DataFrame object.
+    # You can implenent code to display some or all of this 
+    # to STDOUT so you can see the outputs and report to the user.
+    preview.dataset
+```

data_designer-0.3.8/.claude/skills/search-docs/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: search-docs
+description: Search local documentation in the docs/ folder for content related to a topic
+argument-hint: <search-topic>
+---
+
+# Documentation Search
+
+Use the `docs-searcher` subagent to search local documentation for content related to: **$ARGUMENTS**
+
+Call the Task tool with:
+- `subagent_type: "docs-searcher"`
+- `mode: "bypassPermissions"`
+- `prompt`: the search topic
+
+Report the results back to the user exactly as returned by the agent.

data_designer-0.3.8/.claude/skills/search-github/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: search-github
+description: Search GitHub issues, discussions, and PRs for content related to a topic
+argument-hint: <search-topic>
+---
+
+# GitHub Search
+
+Use the `github-searcher` subagent to search GitHub for content related to: **$ARGUMENTS**
+
+Call the Task tool with:
+- `subagent_type: "github-searcher"`
+- `mode: "bypassPermissions"`
+- `prompt`: the search topic
+
+Report the results back to the user exactly as returned by the agent.

{data_designer-0.3.6 → data_designer-0.3.8}/.gitignore

@@ -85,8 +85,6 @@ src/data_designer/_version.py
 # Local scratch space
 .scratch/
 
-.claude/
-
 docs/notebooks/
 docs/notebook_source/*.ipynb
 docs/notebook_source/*.csv

{data_designer-0.3.6 → data_designer-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-designer
-Version: 0.3.6
+Version: 0.3.8
 Summary: General framework for synthetic data generation
 License-Expression: Apache-2.0
 License-File: LICENSE

data_designer-0.3.8/docs/code_reference/run_config.md

@@ -0,0 +1,6 @@
+# Run Config
+
+The `run_config` module defines runtime settings that control dataset generation behavior,
+including early shutdown thresholds, batch sizing, and non-inference worker concurrency.
+
+:::: data_designer.config.run_config

{data_designer-0.3.6 → data_designer-0.3.8}/docs/recipes/cards.md

@@ -6,6 +6,9 @@ Each recipe is a self-contained example that can be run independently.
 !!! question "New to Data Designer?"
     Recipes provide working code for specific use cases without detailed explanations. If you're learning Data Designer for the first time, we recommend starting with our [tutorial notebooks](../../notebooks/), which offer step-by-step guidance and explain core concepts. Once you're familiar with the basics, return here for practical, ready-to-use implementations.
 
+!!! tip Prerequisite
+    These recipes use the Open AI model provider by default. Ensure your OpenAI model provider has been set up using the Data Designer CLI before running a recipe.
+
 <div class="grid cards" markdown>
 
 -   :material-snake:{ .lg .middle } **Text to Python**

{data_designer-0.3.6 → data_designer-0.3.8}/mkdocs.yml

@@ -43,6 +43,7 @@ nav:
       - column_configs: code_reference/column_configs.md
       - config_builder: code_reference/config_builder.md
       - data_designer_config: code_reference/data_designer_config.md
+      - run_config: code_reference/run_config.md
       - sampler_params: code_reference/sampler_params.md
       - validator_params: code_reference/validator_params.md
       - processors: code_reference/processors.md

data_designer-0.3.8/packages/data-designer/src/data_designer/interface/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.3.8rc3.dev39+gb6e375d29.d20260126'
+__version_tuple__ = version_tuple = (0, 3, 8, 'rc3', 'dev39', 'gb6e375d29.d20260126')
+
+__commit_id__ = commit_id = None

data_designer-0.3.8/packages/data-designer-config/src/data_designer/config/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.3.8rc3.dev39+gb6e375d29.d20260126'
+__version_tuple__ = version_tuple = (0, 3, 8, 'rc3', 'dev39', 'gb6e375d29.d20260126')
+
+__commit_id__ = commit_id = None

data_designer-0.3.8/packages/data-designer-engine/src/data_designer/engine/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.3.8rc3.dev39+gb6e375d29.d20260126'
+__version_tuple__ = version_tuple = (0, 3, 8, 'rc3', 'dev39', 'gb6e375d29.d20260126')
+
+__commit_id__ = commit_id = None

{data_designer-0.3.6 → data_designer-0.3.8}/src/data_designer/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.3.6'
-__version_tuple__ = version_tuple = (0, 3, 6)
+__version__ = version = '0.3.8'
+__version_tuple__ = version_tuple = (0, 3, 8)
 
 __commit_id__ = commit_id = None

{data_designer-0.3.6 → data_designer-0.3.8}/src/data_designer/config/default_model_settings.py

@@ -71,12 +71,20 @@ def get_default_model_configs() -> list[ModelConfig]:
     return []
 
 
-def get_default_model_providers_missing_api_keys() -> list[str]:
-    missing_api_keys = []
-    for predefined_provider in PREDEFINED_PROVIDERS:
-        if os.environ.get(predefined_provider["api_key"]) is None:
-            missing_api_keys.append(predefined_provider["api_key"])
-    return missing_api_keys
+def get_providers_with_missing_api_keys(providers: list[ModelProvider]) -> list[ModelProvider]:
+    providers_with_missing_keys = []
+
+    for provider in providers:
+        if provider.api_key is None:
+            # No API key specified at all
+            providers_with_missing_keys.append(provider)
+        elif provider.api_key.isupper() and "_" in provider.api_key:
+            # Looks like an environment variable name, check if it's set
+            if os.environ.get(provider.api_key) is None:
+                providers_with_missing_keys.append(provider)
+        # else: It's an actual API key value (not an env var), so it's valid
+
+    return providers_with_missing_keys
 
 
 def get_default_providers() -> list[ModelProvider]:

{data_designer-0.3.6 → data_designer-0.3.8}/src/data_designer/config/run_config.py

@@ -26,6 +26,8 @@ class RunConfig(ConfigBase):
         buffer_size: Number of records to process in each batch during dataset generation.
             A batch is processed end-to-end (column generation, post-batch processors, and writing the batch
             to artifact storage) before moving on to the next batch. Must be > 0. Default is 1000.
+        non_inference_max_parallel_workers: Maximum number of worker threads used for non-inference
+            cell-by-cell generators. Must be >= 1. Default is 4.
         max_conversation_restarts: Maximum number of full conversation restarts permitted when
             generation tasks call `ModelFacade.generate(...)`. Must be >= 0. Default is 5.
         max_conversation_correction_steps: Maximum number of correction rounds permitted within a
@@ -37,6 +39,7 @@ class RunConfig(ConfigBase):
     shutdown_error_rate: float = Field(default=0.5, ge=0.0, le=1.0)
     shutdown_error_window: int = Field(default=10, ge=0)
     buffer_size: int = Field(default=1000, gt=0)
+    non_inference_max_parallel_workers: int = Field(default=4, ge=1)
     max_conversation_restarts: int = Field(default=5, ge=0)
     max_conversation_correction_steps: int = Field(default=0, ge=0)
 

{data_designer-0.3.6 → data_designer-0.3.8}/src/data_designer/config/utils/constants.py

@@ -353,9 +353,11 @@ PREDEFINED_PROVIDERS_MODEL_MAP = {
 NEMOTRON_PERSONAS_DATASET_SIZES = {
     "en_US": "1.24 GB",
     "en_IN": "2.39 GB",
+    "en_SG": "0.30 GB",
     "hi_Deva_IN": "4.14 GB",
     "hi_Latn_IN": "2.7 GB",
     "ja_JP": "1.69 GB",
+    "pt_BR": "2.33 GB",
 }
 
 LOCALES_WITH_MANAGED_DATASETS = list[str](NEMOTRON_PERSONAS_DATASET_SIZES.keys())

{data_designer-0.3.6 → data_designer-0.3.8}/src/data_designer/engine/column_generators/generators/llm_completion.py

@@ -55,6 +55,9 @@ class ColumnGeneratorWithModelChatCompletion(ColumnGeneratorWithModel[TaskConfig
         )
 
     def generate(self, data: dict) -> dict:
+        # Deserialize input data from previous columns so Jinja2 templates can access nested fields
+        # Example: If prev column stored '{"key": "value"}', templates can use {{ prev_column.key }}
+        # Note: This creates a new dict and doesn't mutate the original `data` argument
         deserialized_record = deserialize_json_values(data)
 
         multi_modal_context = None
@@ -81,13 +84,18 @@ class ColumnGeneratorWithModelChatCompletion(ColumnGeneratorWithModel[TaskConfig
             purpose=f"running generation for column '{self.config.name}'",
         )
 
-        data[self.config.name] = deserialize_json_values(self.response_recipe.serialize_output(response))
+        serialized_output = self.response_recipe.serialize_output(response)
+        data[self.config.name] = self._process_serialized_output(serialized_output)
 
         if reasoning_trace:
             data[self.config.name + REASONING_TRACE_COLUMN_POSTFIX] = reasoning_trace
 
         return data
 
+    def _process_serialized_output(self, serialized_output: str) -> str | dict | list:
+        """Process the serialized output from the model. Subclasses can override to customize deserialization."""
+        return serialized_output
+
 
 class LLMTextCellGenerator(ColumnGeneratorWithModelChatCompletion[LLMTextColumnConfig]): ...
 
@@ -95,7 +103,11 @@ class LLMTextCellGenerator(ColumnGeneratorWithModelChatCompletion[LLMTextColumnC
 class LLMCodeCellGenerator(ColumnGeneratorWithModelChatCompletion[LLMCodeColumnConfig]): ...
 
 
-class LLMStructuredCellGenerator(ColumnGeneratorWithModelChatCompletion[LLMStructuredColumnConfig]): ...
+class LLMStructuredCellGenerator(ColumnGeneratorWithModelChatCompletion[LLMStructuredColumnConfig]):
+    def _process_serialized_output(self, serialized_output: str) -> dict | list:
+        return deserialize_json_values(serialized_output)
 
 
-class LLMJudgeCellGenerator(ColumnGeneratorWithModelChatCompletion[LLMJudgeColumnConfig]): ...
+class LLMJudgeCellGenerator(ColumnGeneratorWithModelChatCompletion[LLMJudgeColumnConfig]):
+    def _process_serialized_output(self, serialized_output: str) -> dict | list:
+        return deserialize_json_values(serialized_output)

{data_designer-0.3.6 → data_designer-0.3.8}/src/data_designer/engine/compiler.py

@@ -5,9 +5,10 @@ from __future__ import annotations
 
 import logging
 
-from data_designer.config.column_configs import SeedDatasetColumnConfig
+from data_designer.config.column_configs import SamplerColumnConfig, SeedDatasetColumnConfig
 from data_designer.config.data_designer_config import DataDesignerConfig
 from data_designer.config.errors import InvalidConfigError
+from data_designer.config.sampler_params import UUIDSamplerParams
 from data_designer.engine.resources.resource_provider import ResourceProvider
 from data_designer.engine.resources.seed_reader import SeedReader
 from data_designer.engine.validation import ViolationLevel, rich_print_violations, validate_data_designer_config
@@ -17,6 +18,7 @@ logger = logging.getLogger(__name__)
 
 def compile_data_designer_config(config: DataDesignerConfig, resource_provider: ResourceProvider) -> DataDesignerConfig:
     _resolve_and_add_seed_columns(config, resource_provider.seed_reader)
+    _add_internal_row_id_column_if_needed(config)
     _validate(config)
     return config
 
@@ -41,6 +43,35 @@ def _resolve_and_add_seed_columns(config: DataDesignerConfig, seed_reader: SeedR
     config.columns.extend([SeedDatasetColumnConfig(name=col_name) for col_name in seed_col_names])
 
 
+def _add_internal_row_id_column_if_needed(config: DataDesignerConfig) -> None:
+    """Adds a UUID sampler column named '_internal_row_id' (set to drop) if needed to enable generation.
+
+    Generation requires either:
+    - At least one sampler column (which can generate data from scratch), OR
+    - A seed dataset (which provides initial data rows)
+
+    If neither exists, a UUID sampler column '_internal_row_id' is automatically added and marked for drop
+    to enable the generation process to start.
+
+    Args:
+        config: The DataDesigner configuration to potentially modify.
+    """
+    has_sampler_column = any(isinstance(col, SamplerColumnConfig) for col in config.columns)
+    has_seed_dataset_column = any(isinstance(col, SeedDatasetColumnConfig) for col in config.columns)
+
+    if not has_sampler_column and not has_seed_dataset_column:
+        logger.warning(
+            "🔔 No sampler column or seed dataset detected. Adding UUID column '_internal_row_id' (marked for drop) to enable generation."
+        )
+        id_column = SamplerColumnConfig(
+            name="_internal_row_id",
+            sampler_type="uuid",
+            params=UUIDSamplerParams(),
+            drop=True,
+        )
+        config.columns.insert(0, id_column)
+
+
 def _validate(config: DataDesignerConfig) -> None:
     allowed_references = _get_allowed_references(config)
     violations = validate_data_designer_config(