diff --git a/.github/workflows/check-colab-notebooks.yml b/.github/workflows/check-colab-notebooks.yml
new file mode 100644
index 00000000..7116b4a0
--- /dev/null
+++ b/.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
diff --git a/Makefile b/Makefile
index 5dd1f59d..295400ce 100644
--- a/Makefile
+++ b/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
diff --git a/docs/colab_notebooks/1-the-basics.ipynb b/docs/colab_notebooks/1-the-basics.ipynb
new file mode 100644
index 00000000..ee9e5ccc
--- /dev/null
+++ b/docs/colab_notebooks/1-the-basics.ipynb
@@ -0,0 +1,537 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "a4ac4d55",
+ "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": "9e9f3c47",
+ "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": "41b31194",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "!pip install -qU data-designer"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "502b3aba",
+ "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": "8c512fbc",
+ "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": "8fae521f",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from data_designer.essentials import (\n",
+ " CategorySamplerParams,\n",
+ " DataDesigner,\n",
+ " DataDesignerConfigBuilder,\n",
+ " InferenceParameters,\n",
+ " LLMTextColumnConfig,\n",
+ " ModelConfig,\n",
+ " PersonFromFakerSamplerParams,\n",
+ " SamplerColumnConfig,\n",
+ " SamplerType,\n",
+ " SubcategorySamplerParams,\n",
+ " UniformSamplerParams,\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e71d0256",
+ "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/concepts/models/default-model-settings/) are used.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "68fc7172",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "data_designer = DataDesigner()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9a821a27",
+ "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/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": "a9515141",
+ "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/nvidia-nemotron-nano-9b-v2\"\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=InferenceParameters(\n",
+ " temperature=0.5,\n",
+ " top_p=1.0,\n",
+ " max_tokens=1024,\n",
+ " ),\n",
+ " )\n",
+ "]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3b940ab9",
+ "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": "ec21da7e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "config_builder = DataDesignerConfigBuilder(model_configs=model_configs)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "85b2324e",
+ "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",
+ "
\n",
+ "\n",
+ "You can view available samplers using the config builder's `info` property:\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "f49f435e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "config_builder.info.display(\"samplers\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f582b642",
+ "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": "8cfc43b1",
+ "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": "2d0eea21",
+ "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": "b5e65724",
+ "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": "e6788771",
+ "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": "a2705cd9",
+ "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": "e3dd2f69",
+ "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": "c6e43147",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "preview = data_designer.preview(config_builder, num_records=2)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "fab77d01",
+ "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": "875ee6a6",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# The preview dataset is available as a pandas DataFrame.\n",
+ "preview.dataset"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "87b59e4b",
+ "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": "5d347f4c",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Print the analysis as a table.\n",
+ "preview.analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d2fb84f2",
+ "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": "71a31e85",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "results = data_designer.create(config_builder, num_records=10)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "501e9092",
+ "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": "6f217b4a",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load the analysis results into memory.\n",
+ "analysis = results.load_analysis()\n",
+ "\n",
+ "analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4da82b0f",
+ "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](/notebooks/2-structured-outputs-and-jinja-expressions/)\n",
+ "\n",
+ "- [Seeding synthetic data generation with an external dataset](/notebooks/3-seeding-with-a-dataset/)\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "language": "python",
+ "name": "python3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/colab_notebooks/2-structured-outputs-and-jinja-expressions.ipynb b/docs/colab_notebooks/2-structured-outputs-and-jinja-expressions.ipynb
new file mode 100644
index 00000000..10156a10
--- /dev/null
+++ b/docs/colab_notebooks/2-structured-outputs-and-jinja-expressions.ipynb
@@ -0,0 +1,567 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "a70798bc",
+ "metadata": {},
+ "source": [
+ "# π¨ Data Designer Tutorial: Structured Outputs and Jinja Expressions\n",
+ "\n",
+ "#### π What you'll learn\n",
+ "\n",
+ "In this notebook, we will continue our exploration of Data Designer, demonstrating more advanced data generation using structured outputs and Jinja expressions.\n",
+ "\n",
+ "If this is your first time using Data Designer, we recommend starting with the [first notebook](/notebooks/1-the-basics/) in this tutorial series.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4ed4c65d",
+ "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": "73432e8e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "!pip install -qU data-designer"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "1a6aac78",
+ "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": "03df6d1c",
+ "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": "befb6573",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from data_designer.essentials import (\n",
+ " CategorySamplerParams,\n",
+ " DataDesigner,\n",
+ " DataDesignerConfigBuilder,\n",
+ " ExpressionColumnConfig,\n",
+ " InferenceParameters,\n",
+ " LLMStructuredColumnConfig,\n",
+ " ModelConfig,\n",
+ " PersonFromFakerSamplerParams,\n",
+ " SamplerColumnConfig,\n",
+ " SamplerType,\n",
+ " SubcategorySamplerParams,\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a022d1ae",
+ "metadata": {},
+ "source": [
+ "### βοΈ Initialize the Data Designer interface\n",
+ "\n",
+ "- `DataDesigner` is the main object that is used to interface with the library.\n",
+ "\n",
+ "- When initialized without arguments, the [default model providers](https://nvidia-nemo.github.io/DataDesigner/concepts/models/default-model-settings/) are used.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "568e1d91",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "data_designer_client = DataDesigner()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "de1ef709",
+ "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/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": "6757f43c",
+ "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/nvidia-nemotron-nano-9b-v2\"\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=InferenceParameters(\n",
+ " temperature=0.5,\n",
+ " top_p=1.0,\n",
+ " max_tokens=1024,\n",
+ " ),\n",
+ " )\n",
+ "]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3d1ea9b6",
+ "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": "f9ad410a",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "config_builder = DataDesignerConfigBuilder(model_configs=model_configs)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8f918afa",
+ "metadata": {},
+ "source": [
+ "### π§βπ¨ Designing our data\n",
+ "\n",
+ "- We will again create a product review dataset, but this time we will use structured outputs and Jinja expressions.\n",
+ "\n",
+ "- Structured outputs let you specify the exact schema of the data you want to generate.\n",
+ "\n",
+ "- Data Designer supports schemas specified using either json schema or Pydantic data models (recommended).\n",
+ "\n",
+ "
\n",
+ "\n",
+ "We'll define our structured outputs using [Pydantic](https://docs.pydantic.dev/latest/) data models\n",
+ "\n",
+ "> π‘ **Why Pydantic?**\n",
+ ">\n",
+ "> - Pydantic models provide better IDE support and type validation.\n",
+ ">\n",
+ "> - They are more Pythonic than raw JSON schemas.\n",
+ ">\n",
+ "> - They integrate seamlessly with Data Designer's structured output system.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "6aafd123",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from decimal import Decimal\n",
+ "from typing import Literal\n",
+ "\n",
+ "from pydantic import BaseModel, Field\n",
+ "\n",
+ "\n",
+ "# We define a Product schema so that the name, description, and price are generated\n",
+ "# in one go, with the types and constraints specified.\n",
+ "class Product(BaseModel):\n",
+ " name: str = Field(description=\"The name of the product\")\n",
+ " description: str = Field(description=\"A description of the product\")\n",
+ " price: Decimal = Field(description=\"The price of the product\", ge=10, le=1000, decimal_places=2)\n",
+ "\n",
+ "\n",
+ "class ProductReview(BaseModel):\n",
+ " rating: int = Field(description=\"The rating of the product\", ge=1, le=5)\n",
+ " customer_mood: Literal[\"irritated\", \"mad\", \"happy\", \"neutral\", \"excited\"] = Field(\n",
+ " description=\"The mood of the customer\"\n",
+ " )\n",
+ " review: str = Field(description=\"A review of the product\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9727c5ae",
+ "metadata": {},
+ "source": [
+ "Next, let's design our product review dataset using a few more tricks compared to the previous notebook.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9f9df709",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Since we often only want a few attributes from Person objects, we can\n",
+ "# set drop=True in the column config to drop the column from the final dataset.\n",
+ "config_builder.add_column(\n",
+ " SamplerColumnConfig(\n",
+ " name=\"customer\",\n",
+ " sampler_type=SamplerType.PERSON_FROM_FAKER,\n",
+ " params=PersonFromFakerSamplerParams(),\n",
+ " drop=True,\n",
+ " )\n",
+ ")\n",
+ "\n",
+ "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",
+ "# Sampler columns support conditional params, which are used if the condition is met.\n",
+ "# In this example, we set the review style to rambling if the target age range is 18-25.\n",
+ "# Note conditional parameters are only supported for Sampler column types.\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",
+ " conditional_params={\n",
+ " \"target_age_range == '18-25'\": CategorySamplerParams(values=[\"rambling\"]),\n",
+ " },\n",
+ " )\n",
+ ")\n",
+ "\n",
+ "# Optionally validate that the columns are configured correctly.\n",
+ "config_builder.validate()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f42b7843",
+ "metadata": {},
+ "source": [
+ "Next, we will use more advanced Jinja expressions to create new columns.\n",
+ "\n",
+ "Jinja expressions let you:\n",
+ "\n",
+ "- Access nested attributes: `{{ customer.first_name }}`\n",
+ "\n",
+ "- Combine values: `{{ customer.first_name }} {{ customer.last_name }}`\n",
+ "\n",
+ "- Use conditional logic: `{% if condition %}...{% endif %}`\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "d231f52e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# We can create new columns using Jinja expressions that reference\n",
+ "# existing columns, including attributes of nested objects.\n",
+ "config_builder.add_column(\n",
+ " ExpressionColumnConfig(name=\"customer_name\", expr=\"{{ customer.first_name }} {{ customer.last_name }}\")\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(ExpressionColumnConfig(name=\"customer_age\", expr=\"{{ customer.age }}\"))\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " LLMStructuredColumnConfig(\n",
+ " name=\"product\",\n",
+ " prompt=(\n",
+ " \"Create a product in the '{{ product_category }}' category, focusing on products \"\n",
+ " \"related to '{{ product_subcategory }}'. The target age range of the ideal customer is \"\n",
+ " \"{{ target_age_range }} years old. The product should be priced between $10 and $1000.\"\n",
+ " ),\n",
+ " system_prompt=SYSTEM_PROMPT,\n",
+ " output_format=Product,\n",
+ " model_alias=MODEL_ALIAS,\n",
+ " )\n",
+ ")\n",
+ "\n",
+ "# We can even use if/else logic in our Jinja expressions to create more complex prompt patterns.\n",
+ "config_builder.add_column(\n",
+ " LLMStructuredColumnConfig(\n",
+ " name=\"customer_review\",\n",
+ " prompt=(\n",
+ " \"Your task is to write a review for the following product:\\n\\n\"\n",
+ " \"Product Name: {{ product.name }}\\n\"\n",
+ " \"Product Description: {{ product.description }}\\n\"\n",
+ " \"Price: {{ product.price }}\\n\\n\"\n",
+ " \"Imagine your name is {{ customer_name }} and you are from {{ customer.city }}, {{ customer.state }}. \"\n",
+ " \"Write the review in a style that is '{{ review_style }}'.\"\n",
+ " \"{% if target_age_range == '18-25' %}\"\n",
+ " \"Make sure the review is more informal and conversational.\"\n",
+ " \"{% else %}\"\n",
+ " \"Make sure the review is more formal and structured.\"\n",
+ " \"{% endif %}\"\n",
+ " ),\n",
+ " system_prompt=SYSTEM_PROMPT,\n",
+ " output_format=ProductReview,\n",
+ " model_alias=MODEL_ALIAS,\n",
+ " )\n",
+ ")\n",
+ "\n",
+ "config_builder.validate()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "01dbf368",
+ "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": "7d0389c6",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "preview = data_designer_client.preview(config_builder, num_records=2)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "b312d760",
+ "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": "6252ae9a",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# The preview dataset is available as a pandas DataFrame.\n",
+ "preview.dataset"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ea32a75e",
+ "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": "c094a400",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Print the analysis as a table.\n",
+ "preview.analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8565a283",
+ "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": "d48a294c",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "job_results = data_designer_client.create(config_builder, num_records=10)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "96268be4",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load the generated dataset as a pandas DataFrame.\n",
+ "dataset = job_results.load_dataset()\n",
+ "\n",
+ "dataset.head()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "a2137aaf",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load the analysis results into memory.\n",
+ "analysis = job_results.load_analysis()\n",
+ "\n",
+ "analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c43a66cc",
+ "metadata": {},
+ "source": [
+ "## βοΈ Next Steps\n",
+ "\n",
+ "Check out the following notebook to learn more about:\n",
+ "\n",
+ "- [Seeding synthetic data generation with an external dataset](/notebooks/3-seeding-with-a-dataset/)\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "language": "python",
+ "name": "python3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/colab_notebooks/3-seeding-with-a-dataset.ipynb b/docs/colab_notebooks/3-seeding-with-a-dataset.ipynb
new file mode 100644
index 00000000..db5c9d27
--- /dev/null
+++ b/docs/colab_notebooks/3-seeding-with-a-dataset.ipynb
@@ -0,0 +1,465 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "c4c424f2",
+ "metadata": {},
+ "source": [
+ "# π¨ Data Designer Tutorial: Seeding Synthetic Data Generation with an External Dataset\n",
+ "\n",
+ "#### π What you'll learn\n",
+ "\n",
+ "In this notebook, we will demonstrate how to seed synthetic data generation in Data Designer with an external dataset.\n",
+ "\n",
+ "If this is your first time using Data Designer, we recommend starting with the [first notebook](/notebooks/1-the-basics/) in this tutorial series.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2ceb13f2",
+ "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": "ad4096cd",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "!pip install -qU data-designer"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "21336bf3",
+ "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": "db8fa976",
+ "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": "c2e17b2b",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from data_designer.essentials import (\n",
+ " DataDesigner,\n",
+ " DataDesignerConfigBuilder,\n",
+ " InferenceParameters,\n",
+ " ModelConfig,\n",
+ " SeedConfig,\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "29c28647",
+ "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/concepts/models/default-model-settings/) are used.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "cecf9242",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "data_designer_client = DataDesigner()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "74eab801",
+ "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/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": "b31991e8",
+ "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/nvidia-nemotron-nano-9b-v2\"\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=InferenceParameters(\n",
+ " temperature=0.5,\n",
+ " top_p=1.0,\n",
+ " max_tokens=1024,\n",
+ " ),\n",
+ " )\n",
+ "]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "006d1625",
+ "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": "396a4ed5",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "config_builder = DataDesignerConfigBuilder(model_configs=model_configs)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9860369b",
+ "metadata": {},
+ "source": [
+ "## π₯ Prepare a seed dataset\n",
+ "\n",
+ "- For this notebook, we'll create a synthetic dataset of patient notes.\n",
+ "\n",
+ "- We will _seed_ the generation process with a [symptom-to-diagnosis dataset](https://huggingface.co/datasets/gretelai/symptom_to_diagnosis).\n",
+ "\n",
+ "- We already have the dataset downloaded in the [data](../data) directory of this repository.\n",
+ "\n",
+ "
\n",
+ "\n",
+ "> π± **Why use a seed dataset?**\n",
+ ">\n",
+ "> - Seed datasets let you steer the generation process by providing context that is specific to your use case.\n",
+ ">\n",
+ "> - Seed datasets are also an excellent way to inject real-world diversity into your synthetic data.\n",
+ ">\n",
+ "> - During generation, prompt templates can reference any of the seed dataset fields.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "65a2fa3c",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Download sample dataset from Github\n",
+ "import urllib.request\n",
+ "\n",
+ "url = \"https://raw.githubusercontent.com/NVIDIA/GenerativeAIExamples/refs/heads/main/nemo/NeMo-Data-Designer/data/gretelai_symptom_to_diagnosis.csv\"\n",
+ "local_filename, headers = urllib.request.urlretrieve(url, \"gretelai_symptom_to_diagnosis.csv\")\n",
+ "\n",
+ "seed_dataset = SeedConfig(dataset=local_filename)\n",
+ "\n",
+ "# Pass the reference to the config builder for use during generation.\n",
+ "config_builder.with_seed_dataset(seed_dataset)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ea11134a",
+ "metadata": {},
+ "source": [
+ "## π¨ Designing our synthetic patient notes dataset\n",
+ "\n",
+ "- Here we use `add_column` with keyword arguments (rather than imported config objects).\n",
+ "\n",
+ "- Generally, we recommend using concrete objects, but this is a convenient shorthand.\n",
+ "\n",
+ "- **Note**: The prompt template can reference fields from our seed dataset:\n",
+ " - `{{ diagnosis }}` - the medical diagnosis from the seed data\n",
+ " - `{{ patient_summary }}` - the symptom description from the seed data\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "209af41c",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "config_builder.add_column(\n",
+ " name=\"patient_sampler\",\n",
+ " column_type=\"sampler\",\n",
+ " sampler_type=\"person_from_faker\",\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"doctor_sampler\",\n",
+ " column_type=\"sampler\",\n",
+ " sampler_type=\"person_from_faker\",\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"patient_id\",\n",
+ " column_type=\"sampler\",\n",
+ " sampler_type=\"uuid\",\n",
+ " params={\n",
+ " \"prefix\": \"PT-\",\n",
+ " \"short_form\": True,\n",
+ " \"uppercase\": True,\n",
+ " },\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"first_name\",\n",
+ " column_type=\"expression\",\n",
+ " expr=\"{{ patient_sampler.first_name}}\",\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"last_name\",\n",
+ " column_type=\"expression\",\n",
+ " expr=\"{{ patient_sampler.last_name }}\",\n",
+ ")\n",
+ "\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"dob\",\n",
+ " column_type=\"expression\",\n",
+ " expr=\"{{ patient_sampler.birth_date }}\",\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"symptom_onset_date\",\n",
+ " column_type=\"sampler\",\n",
+ " sampler_type=\"datetime\",\n",
+ " params={\"start\": \"2024-01-01\", \"end\": \"2024-12-31\"},\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"date_of_visit\",\n",
+ " column_type=\"sampler\",\n",
+ " sampler_type=\"timedelta\",\n",
+ " params={\"dt_min\": 1, \"dt_max\": 30, \"reference_column_name\": \"symptom_onset_date\"},\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"physician\",\n",
+ " column_type=\"expression\",\n",
+ " expr=\"Dr. {{ doctor_sampler.last_name }}\",\n",
+ ")\n",
+ "\n",
+ "config_builder.add_column(\n",
+ " name=\"physician_notes\",\n",
+ " column_type=\"llm-text\",\n",
+ " prompt=\"\"\"\\\n",
+ "You are a primary-care physician who just had an appointment with {{ first_name }} {{ last_name }},\n",
+ "who has been struggling with symptoms from {{ diagnosis }} since {{ symptom_onset_date }}.\n",
+ "The date of today's visit is {{ date_of_visit }}.\n",
+ "\n",
+ "{{ patient_summary }}\n",
+ "\n",
+ "Write careful notes about your visit with {{ first_name }},\n",
+ "as Dr. {{ doctor_sampler.first_name }} {{ doctor_sampler.last_name }}.\n",
+ "\n",
+ "Format the notes as a busy doctor might.\n",
+ "\"\"\",\n",
+ " model_alias=MODEL_ALIAS,\n",
+ " system_prompt=SYSTEM_PROMPT,\n",
+ ")\n",
+ "\n",
+ "config_builder.validate()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "32f43d20",
+ "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": "402a1025",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "preview = data_designer_client.preview(config_builder, num_records=2)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "de294013",
+ "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": "a38c360d",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# The preview dataset is available as a pandas DataFrame.\n",
+ "preview.dataset"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4a385031",
+ "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": "3531b1e4",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Print the analysis as a table.\n",
+ "preview.analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7fec6251",
+ "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": "bace6acb",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "job_results = data_designer_client.create(config_builder, num_records=10)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3eaafc74",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load the generated dataset as a pandas DataFrame.\n",
+ "dataset = job_results.load_dataset()\n",
+ "\n",
+ "dataset.head()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "473a0c89",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load the analysis results into memory.\n",
+ "analysis = job_results.load_analysis()\n",
+ "\n",
+ "analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7408eef8",
+ "metadata": {},
+ "source": [
+ "## βοΈ Next Steps\n",
+ "\n",
+ "Use Data Designer to generate synthetic data for your specific use case!\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "language": "python",
+ "name": "python3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/colab_notebooks/4-providing-images-as-context.ipynb b/docs/colab_notebooks/4-providing-images-as-context.ipynb
new file mode 100644
index 00000000..bac63375
--- /dev/null
+++ b/docs/colab_notebooks/4-providing-images-as-context.ipynb
@@ -0,0 +1,540 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "ebd062e8",
+ "metadata": {},
+ "source": [
+ "# π¨ Data Designer Tutorial: Providing Images as Context for Vision-Based Data Generation"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3ce5b7f7",
+ "metadata": {},
+ "source": [
+ "#### π What you'll learn\n",
+ "\n",
+ "This notebook demonstrates how to provide images as context to generate text descriptions using vision-language models.\n",
+ "\n",
+ "- β¨ **Visual Document Processing**: Converting images to chat-ready format for model consumption\n",
+ "- π **Vision-Language Generation**: Using vision models to generate detailed summaries from images\n",
+ "\n",
+ "If this is your first time using Data Designer, we recommend starting with the [first notebook](/notebooks/1-the-basics/) in this tutorial series.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "04d0bfd4",
+ "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": "661740a3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "!pip install -qU data-designer"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "b9c4188b",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "!pip install -q pillow>=12.0.0"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "ddaeb938",
+ "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": "c3aac5e8",
+ "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": "c8b905ee",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Standard library imports\n",
+ "import base64\n",
+ "import io\n",
+ "import uuid\n",
+ "\n",
+ "# Third-party imports\n",
+ "import pandas as pd\n",
+ "import rich\n",
+ "from datasets import load_dataset\n",
+ "from IPython.display import display\n",
+ "from rich.panel import Panel\n",
+ "\n",
+ "# Data Designer imports\n",
+ "from data_designer.essentials import (\n",
+ " DataDesigner,\n",
+ " DataDesignerConfigBuilder,\n",
+ " ImageContext,\n",
+ " ImageFormat,\n",
+ " InferenceParameters,\n",
+ " LLMTextColumnConfig,\n",
+ " ModalityDataType,\n",
+ " ModelConfig,\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f508d655",
+ "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/concepts/models/default-model-settings/) are used.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "f0607008",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "data_designer = DataDesigner()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a0467d8c",
+ "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/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": "1e4d9a15",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# This name is set in the model provider configuration.\n",
+ "MODEL_PROVIDER = \"nvidia\"\n",
+ "\n",
+ "model_configs = [\n",
+ " ModelConfig(\n",
+ " alias=\"vision\",\n",
+ " model=\"meta/llama-4-scout-17b-16e-instruct\",\n",
+ " provider=MODEL_PROVIDER,\n",
+ " inference_parameters=InferenceParameters(\n",
+ " temperature=0.60,\n",
+ " top_p=0.95,\n",
+ " max_tokens=2048,\n",
+ " ),\n",
+ " ),\n",
+ "]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "6d66a8a6",
+ "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": "80ad9b04",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "config_builder = DataDesignerConfigBuilder(model_configs=model_configs)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "75935c33",
+ "metadata": {},
+ "source": [
+ "### π± Seed Dataset Creation\n",
+ "\n",
+ "In this section, we'll prepare our visual documents as a seed dataset for summarization:\n",
+ "\n",
+ "- **Loading Visual Documents**: We use the ColPali dataset containing document images\n",
+ "- **Image Processing**: Convert images to base64 format for vision model consumption\n",
+ "- **Metadata Extraction**: Preserve relevant document information (filename, page number, source, etc.)\n",
+ "\n",
+ "The seed dataset will be used to generate detailed text summaries of each document image."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "868e41af",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Dataset processing configuration\n",
+ "IMG_COUNT = 512 # Number of images to process\n",
+ "BASE64_IMAGE_HEIGHT = 512 # Standardized height for model input\n",
+ "\n",
+ "# Load ColPali dataset for visual documents\n",
+ "img_dataset_cfg = {\"path\": \"vidore/colpali_train_set\", \"split\": \"train\", \"streaming\": True}"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5466e56f",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def resize_image(image, height: int):\n",
+ " \"\"\"\n",
+ " Resize image while maintaining aspect ratio.\n",
+ "\n",
+ " Args:\n",
+ " image: PIL Image object\n",
+ " height: Target height in pixels\n",
+ "\n",
+ " Returns:\n",
+ " Resized PIL Image object\n",
+ " \"\"\"\n",
+ " original_width, original_height = image.size\n",
+ " width = int(original_width * (height / original_height))\n",
+ " return image.resize((width, height))\n",
+ "\n",
+ "\n",
+ "def convert_image_to_chat_format(record, height: int) -> dict:\n",
+ " \"\"\"\n",
+ " Convert PIL image to base64 format for chat template usage.\n",
+ "\n",
+ " Args:\n",
+ " record: Dataset record containing image and metadata\n",
+ " height: Target height for image resizing\n",
+ "\n",
+ " Returns:\n",
+ " Updated record with base64_image and uuid fields\n",
+ " \"\"\"\n",
+ " # Resize image for consistent processing\n",
+ " image = resize_image(record[\"image\"], height)\n",
+ "\n",
+ " # Convert to base64 string\n",
+ " img_buffer = io.BytesIO()\n",
+ " image.save(img_buffer, format=\"PNG\")\n",
+ " byte_data = img_buffer.getvalue()\n",
+ " base64_encoded_data = base64.b64encode(byte_data)\n",
+ " base64_string = base64_encoded_data.decode(\"utf-8\")\n",
+ "\n",
+ " # Return updated record\n",
+ " return record | {\"base64_image\": base64_string, \"uuid\": str(uuid.uuid4())}"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "bbca6568",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load and process the visual document dataset\n",
+ "print(\"π₯ Loading and processing document images...\")\n",
+ "\n",
+ "img_dataset_iter = iter(\n",
+ " load_dataset(**img_dataset_cfg).map(convert_image_to_chat_format, fn_kwargs={\"height\": BASE64_IMAGE_HEIGHT})\n",
+ ")\n",
+ "img_dataset = pd.DataFrame([next(img_dataset_iter) for _ in range(IMG_COUNT)])\n",
+ "\n",
+ "print(f\"β
Loaded {len(img_dataset)} images with columns: {list(img_dataset.columns)}\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5ce17e71",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "img_dataset.head()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9c0faf28",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Add the seed dataset containing our processed images\n",
+ "df_seed = pd.DataFrame(img_dataset)[[\"uuid\", \"image_filename\", \"base64_image\", \"page\", \"options\", \"source\"]]\n",
+ "config_builder.with_seed_dataset(\n",
+ " DataDesigner.make_seed_reference_from_dataframe(df_seed, file_path=\"colpali_train_set.csv\")\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "35bc8b77",
+ "metadata": {
+ "lines_to_next_cell": 2
+ },
+ "outputs": [],
+ "source": [
+ "# Add a column to generate detailed document summaries\n",
+ "config_builder.add_column(\n",
+ " LLMTextColumnConfig(\n",
+ " name=\"summary\",\n",
+ " model_alias=\"vision\",\n",
+ " prompt=(\n",
+ " \"Provide a detailed summary of the content in this image in Markdown format. \"\n",
+ " \"Start from the top of the image and then describe it from top to bottom. \"\n",
+ " \"Place a summary at the bottom.\"\n",
+ " ),\n",
+ " multi_modal_context=[\n",
+ " ImageContext(\n",
+ " column_name=\"base64_image\",\n",
+ " data_type=ModalityDataType.BASE64,\n",
+ " image_format=ImageFormat.PNG,\n",
+ " )\n",
+ " ],\n",
+ " )\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "16ac3f58",
+ "metadata": {
+ "lines_to_next_cell": 2
+ },
+ "source": []
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1d13a0e4",
+ "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": "336af89f",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "preview = data_designer.preview(config_builder, num_records=2)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5a57a536",
+ "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": "9e05b387",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# The preview dataset is available as a pandas DataFrame.\n",
+ "preview.dataset"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f69d543e",
+ "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": "e3cb66a7",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Print the analysis as a table.\n",
+ "preview.analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "60815241",
+ "metadata": {},
+ "source": [
+ "### π Visual Inspection\n",
+ "\n",
+ "Let's compare the original document image with the generated summary to validate quality:\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3c9dddf6",
+ "metadata": {
+ "lines_to_next_cell": 2
+ },
+ "outputs": [],
+ "source": [
+ "# Compare original document with generated summary\n",
+ "index = 0 # Change this to view different examples\n",
+ "\n",
+ "# Merge preview data with original images for comparison\n",
+ "comparison_dataset = preview.dataset.merge(pd.DataFrame(img_dataset)[[\"uuid\", \"image\"]], how=\"left\", on=\"uuid\")\n",
+ "\n",
+ "# Extract the record for display\n",
+ "record = comparison_dataset.iloc[index]\n",
+ "\n",
+ "print(\"π Original Document Image:\")\n",
+ "display(resize_image(record.image, BASE64_IMAGE_HEIGHT))\n",
+ "\n",
+ "print(\"\\nπ Generated Summary:\")\n",
+ "rich.print(Panel(record.summary, title=\"Document Summary\", title_align=\"left\"))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "eb6e2469",
+ "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": "d6a0ed1c",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "results = data_designer.create(config_builder, num_records=10)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "255b8f6f",
+ "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": "43b935b3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load the analysis results into memory.\n",
+ "analysis = results.load_analysis()\n",
+ "\n",
+ "analysis.to_report()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a74f1121",
+ "metadata": {},
+ "source": [
+ "## βοΈ Next Steps\n",
+ "\n",
+ "Now that you've learned how to use visual context for image summarization in Data Designer, explore more:\n",
+ "\n",
+ "- Experiment with different vision models for specific document types\n",
+ "- Try different prompt variations to generate specialized descriptions (e.g., technical details, key findings)\n",
+ "- Combine vision-based summaries with other column types for multi-modal workflows\n",
+ "- Apply this pattern to other vision tasks like image captioning, OCR validation, or visual question answering\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "language": "python",
+ "name": "python3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/notebook_source/4-providing-images-as-context.py b/docs/notebook_source/4-providing-images-as-context.py
index 10afd4bd..dc2513cd 100644
--- a/docs/notebook_source/4-providing-images-as-context.py
+++ b/docs/notebook_source/4-providing-images-as-context.py
@@ -26,12 +26,6 @@
# If this is your first time using Data Designer, we recommend starting with the [first notebook](/notebooks/1-the-basics/) in this tutorial series.
#
-# %% [markdown]
-# ### β¬οΈ Install dependencies (if required)
-
-# %%
-# !uv pip install pillow
-
# %% [markdown]
# ### π¦ Import the essentials
#
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
index b2d13089..be7a7c51 100644
--- a/docs/overrides/main.html
+++ b/docs/overrides/main.html
@@ -2,16 +2,29 @@
{% block outdated %}
You're not viewing the latest version.
-
+
Click here to go to latest.
{% endblock %}
{% block content %}
{% if page.nb_url %}
-
- {% include ".icons/material/download.svg" %}
+
+
+ 
+
+