data-designer 0.1.5__tar.gz → 0.2.0__tar.gz

data_designer-0.2.0/.github/workflows/check-colab-notebooks.yml

@@ -0,0 +1,55 @@
+name: Check Colab notebooks
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/notebook_source/*.py'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'docs/notebook_source/*.py'
+  workflow_dispatch:
+
+jobs:
+  check-colab-notebooks:
+    name: Check Colab Notebooks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          python-version: "3.11"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --group notebooks --group docs
+
+      - name: Generate Colab notebooks
+        run: |
+          make generate-colab-notebooks
+
+      - name: Check for differences
+        run: |
+          # Get the diff, filtering out cell ID changes (which are randomly generated)
+          # Filter out: file markers (--- and +++), and "id" lines
+          MEANINGFUL_DIFF=$(git diff docs/colab_notebooks/ | grep -E '^[+-]' | grep -v '^---' | grep -v '^+++' | grep -vE '^[+-]\s*"id": "[0-9a-fA-F]+",?$' || true)
+
+          if [ -z "$MEANINGFUL_DIFF" ]; then
+            echo "✅ Colab notebooks are up-to-date (ignoring cell ID changes)"
+          else
+            echo "❌ Colab notebooks are out of sync with source files"
+            echo ""
+            echo "The generated notebooks differ from the committed ones."
+            echo "Please run 'make generate-colab-notebooks' locally and commit the changes."
+            echo ""
+            echo "Differences found:"
+            echo "$MEANINGFUL_DIFF"
+            exit 1
+          fi

{data_designer-0.1.5 → data_designer-0.2.0}/Makefile

@@ -36,6 +36,7 @@ help:
 	@echo "🛠️  Utilities:"
 	@echo "  clean                     - Remove coverage reports and cache files"
 	@echo "  convert-execute-notebooks - Convert notebooks from .py to .ipynb using jupytext"
+	@echo "  generate-colab-notebooks  - Generate Colab-compatible notebooks"
 	@echo "  serve-docs-locally        - Serve documentation locally"
 	@echo "  check-license-headers     - Check if all files have license headers"
 	@echo "  update-license-headers    - Add license headers to all files"
@@ -95,6 +96,11 @@ convert-execute-notebooks:
 	rm docs/notebook_source/*.csv
 	@echo "✅ Notebooks created in docs/notebooks/"
 
+generate-colab-notebooks:
+	@echo "📓 Generating Colab-compatible notebooks..."
+	uv run --group notebooks python docs/scripts/generate_colab_notebooks.py
+	@echo "✅ Colab notebooks created in docs/colab_notebooks/"
+
 serve-docs-locally:
 	@echo "📝 Building and serving docs..."
 	uv sync --group docs
@@ -125,4 +131,4 @@ install-dev-notebooks:
 	$(call install-pre-commit-hooks)
 	@echo "✅ Dev + notebooks installation complete!"
 
-.PHONY: clean coverage format format-check lint lint-fix test check-license-headers update-license-headers check-all check-all-fix install install-dev install-dev-notebooks
+.PHONY: clean coverage format format-check lint lint-fix test check-license-headers update-license-headers check-all check-all-fix install install-dev install-dev-notebooks generate-colab-notebooks

{data_designer-0.1.5 → data_designer-0.2.0}/PKG-INFO

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

data_designer-0.2.0/docs/code_reference/analysis.md

@@ -0,0 +1,31 @@
+# Analysis
+
+The `analysis` modules provide tools for profiling and analyzing generated datasets. It includes statistics tracking, column profiling, and reporting capabilities.
+
+## Column Statistics
+
+Column statistics are automatically computed for every column after generation. They provide basic metrics specific to the column type. For example, LLM columns track token usage statistics, sampler columns track distribution information, and validation columns track validation success rates.
+
+The classes below are result objects that store the computed statistics for each column type and provide methods for formatting these results for display in reports.
+
+::: data_designer.config.analysis.column_statistics
+
+## Column Profilers
+
+Column profilers are optional analysis tools that provide deeper insights into specific column types. Currently, the only column profiler available is the Judge Score Profiler.
+
+The classes below are result objects that store the computed profiler results and provide methods for formatting these results for display in reports.
+
+::: data_designer.config.analysis.column_profilers
+
+## Dataset Profiler
+
+The [DatasetProfilerResults](#data_designer.config.analysis.dataset_profiler.DatasetProfilerResults) class contains complete profiling results for a generated dataset. It aggregates column-level statistics, metadata, and profiler results, and provides methods to:
+
+- Compute dataset-level metrics (completion percentage, column type summary)
+- Filter statistics by column type
+- Generate formatted analysis reports via the `to_report()` method
+
+Reports can be displayed in the console or exported to HTML/SVG formats.
+
+::: data_designer.config.analysis.dataset_profiler

data_designer-0.2.0/docs/code_reference/processors.md

@@ -0,0 +1,6 @@
+# Processors
+
+The `processors` module defines configuration objects for post-generation data transformations. Processors run after column generation and can modify the dataset schema or content before output.
+
+::: data_designer.config.processors
+

data_designer-0.2.0/docs/colab_notebooks/1-the-basics.ipynb

@@ -0,0 +1,540 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "9f804f90",
+   "metadata": {},
+   "source": [
+    "# 🎨 Data Designer Tutorial: The Basics\n",
+    "\n",
+    "#### 📚 What you'll learn\n",
+    "\n",
+    "This notebook demonstrates the basics of Data Designer by generating a simple product review dataset.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9cb786eb",
+   "metadata": {},
+   "source": [
+    "### ⚡ Colab Setup\n",
+    "\n",
+    "Run the cells below to install the dependencies and set up the API key. If you don't have an API key, you can generate one from [build.nvidia.com](https://build.nvidia.com).\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7f45ea56",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%capture\n",
+    "!pip install -U data-designer"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ea86e81e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import getpass\n",
+    "import os\n",
+    "\n",
+    "from google.colab import userdata\n",
+    "\n",
+    "try:\n",
+    "    os.environ[\"NVIDIA_API_KEY\"] = userdata.get(\"NVIDIA_API_KEY\")\n",
+    "except userdata.SecretNotFoundError:\n",
+    "    os.environ[\"NVIDIA_API_KEY\"] = getpass.getpass(\"Enter your NVIDIA API key: \")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "16611c7b",
+   "metadata": {},
+   "source": [
+    "### 📦 Import the essentials\n",
+    "\n",
+    "- The `essentials` module provides quick access to the most commonly used objects.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "875342bb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from data_designer.essentials import (\n",
+    "    CategorySamplerParams,\n",
+    "    ChatCompletionInferenceParams,\n",
+    "    DataDesigner,\n",
+    "    DataDesignerConfigBuilder,\n",
+    "    LLMTextColumnConfig,\n",
+    "    ModelConfig,\n",
+    "    PersonFromFakerSamplerParams,\n",
+    "    SamplerColumnConfig,\n",
+    "    SamplerType,\n",
+    "    SubcategorySamplerParams,\n",
+    "    UniformSamplerParams,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b58ac676",
+   "metadata": {},
+   "source": [
+    "### ⚙️ Initialize the Data Designer interface\n",
+    "\n",
+    "- `DataDesigner` is the main object is responsible for managing the data generation process.\n",
+    "\n",
+    "- When initialized without arguments, the [default model providers](https://nvidia-nemo.github.io/DataDesigner/latest/concepts/models/default-model-settings/) are used.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3ce805ad",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data_designer = DataDesigner()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "50e961ed",
+   "metadata": {},
+   "source": [
+    "### 🎛️ Define model configurations\n",
+    "\n",
+    "- Each `ModelConfig` defines a model that can be used during the generation process.\n",
+    "\n",
+    "- The \"model alias\" is used to reference the model in the Data Designer config (as we will see below).\n",
+    "\n",
+    "- The \"model provider\" is the external service that hosts the model (see the [model config](https://nvidia-nemo.github.io/DataDesigner/latest/concepts/models/default-model-settings/) docs for more details).\n",
+    "\n",
+    "- By default, we use [build.nvidia.com](https://build.nvidia.com/models) as the model provider.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1b07a6a5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This name is set in the model provider configuration.\n",
+    "MODEL_PROVIDER = \"nvidia\"\n",
+    "\n",
+    "# The model ID is from build.nvidia.com.\n",
+    "MODEL_ID = \"nvidia/nemotron-3-nano-30b-a3b\"\n",
+    "\n",
+    "# We choose this alias to be descriptive for our use case.\n",
+    "MODEL_ALIAS = \"nemotron-nano-v2\"\n",
+    "\n",
+    "# This sets reasoning to False for the nemotron-nano-v2 model.\n",
+    "SYSTEM_PROMPT = \"/no_think\"\n",
+    "\n",
+    "model_configs = [\n",
+    "    ModelConfig(\n",
+    "        alias=MODEL_ALIAS,\n",
+    "        model=MODEL_ID,\n",
+    "        provider=MODEL_PROVIDER,\n",
+    "        inference_parameters=ChatCompletionInferenceParams(\n",
+    "            temperature=0.5,\n",
+    "            top_p=1.0,\n",
+    "            max_tokens=1024,\n",
+    "        ),\n",
+    "    )\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6d873251",
+   "metadata": {},
+   "source": [
+    "### 🏗️ Initialize the Data Designer Config Builder\n",
+    "\n",
+    "- The Data Designer config defines the dataset schema and generation process.\n",
+    "\n",
+    "- The config builder provides an intuitive interface for building this configuration.\n",
+    "\n",
+    "- The list of model configs is provided to the builder at initialization.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d45fac13",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config_builder = DataDesignerConfigBuilder(model_configs=model_configs)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c35b0274",
+   "metadata": {},
+   "source": [
+    "## 🎲 Getting started with sampler columns\n",
+    "\n",
+    "- Sampler columns offer non-LLM based generation of synthetic data.\n",
+    "\n",
+    "- They are particularly useful for **steering the diversity** of the generated data, as we demonstrate below.\n",
+    "\n",
+    "<br>\n",
+    "\n",
+    "You can view available samplers using the config builder's `info` property:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14cb9967",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config_builder.info.display(\"samplers\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "40945aea",
+   "metadata": {},
+   "source": [
+    "Let's start designing our product review dataset by adding product category and subcategory columns.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a7d87e00",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config_builder.add_column(\n",
+    "    SamplerColumnConfig(\n",
+    "        name=\"product_category\",\n",
+    "        sampler_type=SamplerType.CATEGORY,\n",
+    "        params=CategorySamplerParams(\n",
+    "            values=[\n",
+    "                \"Electronics\",\n",
+    "                \"Clothing\",\n",
+    "                \"Home & Kitchen\",\n",
+    "                \"Books\",\n",
+    "                \"Home Office\",\n",
+    "            ],\n",
+    "        ),\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "config_builder.add_column(\n",
+    "    SamplerColumnConfig(\n",
+    "        name=\"product_subcategory\",\n",
+    "        sampler_type=SamplerType.SUBCATEGORY,\n",
+    "        params=SubcategorySamplerParams(\n",
+    "            category=\"product_category\",\n",
+    "            values={\n",
+    "                \"Electronics\": [\n",
+    "                    \"Smartphones\",\n",
+    "                    \"Laptops\",\n",
+    "                    \"Headphones\",\n",
+    "                    \"Cameras\",\n",
+    "                    \"Accessories\",\n",
+    "                ],\n",
+    "                \"Clothing\": [\n",
+    "                    \"Men's Clothing\",\n",
+    "                    \"Women's Clothing\",\n",
+    "                    \"Winter Coats\",\n",
+    "                    \"Activewear\",\n",
+    "                    \"Accessories\",\n",
+    "                ],\n",
+    "                \"Home & Kitchen\": [\n",
+    "                    \"Appliances\",\n",
+    "                    \"Cookware\",\n",
+    "                    \"Furniture\",\n",
+    "                    \"Decor\",\n",
+    "                    \"Organization\",\n",
+    "                ],\n",
+    "                \"Books\": [\n",
+    "                    \"Fiction\",\n",
+    "                    \"Non-Fiction\",\n",
+    "                    \"Self-Help\",\n",
+    "                    \"Textbooks\",\n",
+    "                    \"Classics\",\n",
+    "                ],\n",
+    "                \"Home Office\": [\n",
+    "                    \"Desks\",\n",
+    "                    \"Chairs\",\n",
+    "                    \"Storage\",\n",
+    "                    \"Office Supplies\",\n",
+    "                    \"Lighting\",\n",
+    "                ],\n",
+    "            },\n",
+    "        ),\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "config_builder.add_column(\n",
+    "    SamplerColumnConfig(\n",
+    "        name=\"target_age_range\",\n",
+    "        sampler_type=SamplerType.CATEGORY,\n",
+    "        params=CategorySamplerParams(values=[\"18-25\", \"25-35\", \"35-50\", \"50-65\", \"65+\"]),\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "# Optionally validate that the columns are configured correctly.\n",
+    "config_builder.validate()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "48699878",
+   "metadata": {},
+   "source": [
+    "Next, let's add samplers to generate data related to the customer and their review.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "df84faf3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config_builder.add_column(\n",
+    "    SamplerColumnConfig(\n",
+    "        name=\"customer\",\n",
+    "        sampler_type=SamplerType.PERSON_FROM_FAKER,\n",
+    "        params=PersonFromFakerSamplerParams(age_range=[18, 70], locale=\"en_US\"),\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "config_builder.add_column(\n",
+    "    SamplerColumnConfig(\n",
+    "        name=\"number_of_stars\",\n",
+    "        sampler_type=SamplerType.UNIFORM,\n",
+    "        params=UniformSamplerParams(low=1, high=5),\n",
+    "        convert_to=\"int\",  # Convert the sampled float to an integer.\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "config_builder.add_column(\n",
+    "    SamplerColumnConfig(\n",
+    "        name=\"review_style\",\n",
+    "        sampler_type=SamplerType.CATEGORY,\n",
+    "        params=CategorySamplerParams(\n",
+    "            values=[\"rambling\", \"brief\", \"detailed\", \"structured with bullet points\"],\n",
+    "            weights=[1, 2, 2, 1],\n",
+    "        ),\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "config_builder.validate()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8288352d",
+   "metadata": {},
+   "source": [
+    "## 🦜 LLM-generated columns\n",
+    "\n",
+    "- The real power of Data Designer comes from leveraging LLMs to generate text, code, and structured data.\n",
+    "\n",
+    "- When prompting the LLM, we can use Jinja templating to reference other columns in the dataset.\n",
+    "\n",
+    "- As we see below, nested json fields can be accessed using dot notation.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "157919b4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "config_builder.add_column(\n",
+    "    LLMTextColumnConfig(\n",
+    "        name=\"product_name\",\n",
+    "        prompt=(\n",
+    "            \"You are a helpful assistant that generates product names. DO NOT add quotes around the product name.\\n\\n\"\n",
+    "            \"Come up with a creative product name for a product in the '{{ product_category }}' category, focusing \"\n",
+    "            \"on products related to '{{ product_subcategory }}'. The target age range of the ideal customer is \"\n",
+    "            \"{{ target_age_range }} years old. Respond with only the product name, no other text.\"\n",
+    "        ),\n",
+    "        system_prompt=SYSTEM_PROMPT,\n",
+    "        model_alias=MODEL_ALIAS,\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "config_builder.add_column(\n",
+    "    LLMTextColumnConfig(\n",
+    "        name=\"customer_review\",\n",
+    "        prompt=(\n",
+    "            \"You are a customer named {{ customer.first_name }} from {{ customer.city }}, {{ customer.state }}. \"\n",
+    "            \"You are {{ customer.age }} years old and recently purchased a product called {{ product_name }}. \"\n",
+    "            \"Write a review of this product, which you gave a rating of {{ number_of_stars }} stars. \"\n",
+    "            \"The style of the review should be '{{ review_style }}'.\"\n",
+    "        ),\n",
+    "        system_prompt=SYSTEM_PROMPT,\n",
+    "        model_alias=MODEL_ALIAS,\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "config_builder.validate()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "009646e4",
+   "metadata": {},
+   "source": [
+    "### 🔁 Iteration is key – preview the dataset!\n",
+    "\n",
+    "1. Use the `preview` method to generate a sample of records quickly.\n",
+    "\n",
+    "2. Inspect the results for quality and format issues.\n",
+    "\n",
+    "3. Adjust column configurations, prompts, or parameters as needed.\n",
+    "\n",
+    "4. Re-run the preview until satisfied.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a9c90236",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "preview = data_designer.preview(config_builder, num_records=2)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3cfe180e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Run this cell multiple times to cycle through the 2 preview records.\n",
+    "preview.display_sample_record()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "65b2f595",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# The preview dataset is available as a pandas DataFrame.\n",
+    "preview.dataset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2134fa0f",
+   "metadata": {},
+   "source": [
+    "### 📊 Analyze the generated data\n",
+    "\n",
+    "- Data Designer automatically generates a basic statistical analysis of the generated data.\n",
+    "\n",
+    "- This analysis is available via the `analysis` property of generation result objects.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8a37dd61",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Print the analysis as a table.\n",
+    "preview.analysis.to_report()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b715bc3a",
+   "metadata": {},
+   "source": [
+    "### 🆙 Scale up!\n",
+    "\n",
+    "- Happy with your preview data?\n",
+    "\n",
+    "- Use the `create` method to submit larger Data Designer generation jobs.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "565f03a1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = data_designer.create(config_builder, num_records=10)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9d4c91ad",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load the generated dataset as a pandas DataFrame.\n",
+    "dataset = results.load_dataset()\n",
+    "\n",
+    "dataset.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "93c5a082",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load the analysis results into memory.\n",
+    "analysis = results.load_analysis()\n",
+    "\n",
+    "analysis.to_report()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "13f7c942",
+   "metadata": {},
+   "source": [
+    "## ⏭️ Next Steps\n",
+    "\n",
+    "Now that you've seen the basics of Data Designer, check out the following notebooks to learn more about:\n",
+    "\n",
+    "- [Structured outputs and jinja expressions](https://nvidia-nemo.github.io/DataDesigner/latest/notebooks/2-structured-outputs-and-jinja-expressions/)\n",
+    "\n",
+    "- [Seeding synthetic data generation with an external dataset](https://nvidia-nemo.github.io/DataDesigner/latest/notebooks/3-seeding-with-a-dataset/)\n",
+    "\n",
+    "- [Providing images as context](https://nvidia-nemo.github.io/DataDesigner/latest/notebooks/4-providing-images-as-context/)\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}