Multi-File & Multi-Folder

In this notebook we will demonstrate how the DataFramer Python SDK (PIP Package: pydataframer) can be used to generate large amounts of high quality synthetic datasets for multi-file and multi-folder use cases, where each generated sample can consist of multiple files or an entire folder structure.

Multi-file datasets contain multiple independent files (e.g., a collection of PDF lab reports), while multi-folder datasets organize files into folder hierarchies (e.g., per-patient folders each containing multiple documents). In both cases, seed data is uploaded as a ZIP archive and generated outputs are saved to a Databricks Volume.

Prerequisites

Import this notebook into your Databricks workspace and run it there. It reads and writes files in a Databricks Volume, so it cannot run in Google Colab or a local Jupyter.

Volume access (one-time admin setup)
Whoever runs this notebook — a person, or a service principal when it runs as a job — needs:
- USE CATALOG on the catalog
- USE SCHEMA on the schema
- READ VOLUME and WRITE VOLUME on the volume
This notebook writes files rather than table rows, so it needs no table privileges and no SQL warehouse.
DataFramer Databricks Credentials (one-time admin setup)
A DataFramer company admin must configure the Databricks service principal credentials in the DataFramer web application. Navigate to Settings > Keys, choose the provider Databricks, and enter:
- Client ID — the service principal application (client) ID
- Client Secret — the service principal secret
- Workspace URL — the workspace’s address
  (e.g. https://dbc-xxxxx.cloud.databricks.com)
Once saved, every AI task of every team member runs on Databricks: databricks/ models run as chosen, and a model chosen from another provider is moved to its Databricks equivalent. A company holds one provider credential at a time, so saving the Databricks credential replaces an Anthropic or OpenAI key. No credentials need to be passed in API calls.
DataFramer API key
Retrieve it from Settings > Keys > Copy API Key on the web application. Store it in a Databricks secret scope; this example uses a scope named dataframer with the key DATAFRAMER_API_KEY. Whoever runs this notebook needs at least READ permission on that scope — including the service principal, when it runs as a job.

Step 1: Install and Setup SDK

Install the DataFramer SDK and the Databricks connector package for DataFramer.

%%capture
%pip install --upgrade pydataframer pydataframer-databricks pyyaml tenacity

Initialize the DataFramer client and the DatabricksConnector

In this step, we initialize the DataFramer client with the API key stored in the dataframer secret scope, and the DatabricksConnector, which reaches Unity Catalog as the identity running this notebook.

import os
import yaml
import requests
from io import BytesIO
from pathlib import Path
from datetime import datetime

import dataframer
from dataframer import Dataframer
from pydataframer_databricks import DatabricksConnector
from tenacity import retry, retry_if_result, stop_never, wait_fixed

# Uses the workspace, warehouse and identity of the notebook it runs in
databricks_connector = DatabricksConnector(scope="dataframer")

client = Dataframer(api_key=databricks_connector.get_secret("DATAFRAMER_API_KEY"))

print("✓ Dataframer client initialized successfully")
print(f"Using base URL: {client.base_url}")
print(f"Dataframer SDK version: {dataframer.__version__}")

Step 2: Upload data to DataFramer

For multi-file and multi-folder datasets, seed data must be uploaded as a ZIP archive stored in a Databricks Volume. The ZIP should contain all the sample files (for multi-file) or folder structures (for multi-folder) that DataFramer will analyze to generate new synthetic data.

Multi-file upload

A multi-file ZIP contains multiple independent files at the top level (e.g., several PDF lab reports).

dataset = client.dataframer.seed_datasets.create_from_zip(
    name=f"pdf_multi_file_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
    description="Multi-file PDF dataset from Databricks Volume",
    zip_file=open("/Volumes/workspace/default/dataframer_output/pdf_multi_file.zip", "rb"),
)

dataset_id = dataset.id
print(f"✓ Dataset uploaded: {dataset_id} (type: {dataset.dataset_type})")

Multi-folder upload

A multi-folder ZIP contains top-level folders, each with its own set of files (e.g., per-patient folders with lab reports, notes, and imaging results).

dataset = client.dataframer.seed_datasets.create_from_zip(
    name=f"pdf_multi_folder_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
    description="Multi-folder PDF dataset from Databricks Volume",
    zip_file=open("/Volumes/workspace/default/dataframer_output/pdf_multi_folder.zip", "rb"),
)

dataset_id = dataset.id
print(f"✓ Dataset uploaded: {dataset_id} (type: {dataset.dataset_type})")

Retrieve Dataset Details

This API demonstrates how to retrieve a specific dataset given a dataset ID.

# Get detailed information about the dataset
dataset_info = client.dataframer.seed_datasets.retrieve(dataset_id=dataset_id)

print()
print("📋 Dataset Information:")
print("=" * 80)
print()
print(f"ID: {dataset_info.id}")
print(f"Name: {dataset_info.name}")
print(f"Type: {dataset_info.dataset_type}")
print(f"Description: {dataset_info.description}")
print(f"Created: {dataset_info.created_at}")
print()
print(f"📁 Contents:")
print(f"  Files: {dataset_info.file_count}")
print(f"  Folders: {dataset_info.folder_count}")
print()
print("=" * 80)

Step 3: Generate Specification via the analysis API

A specification (or “spec”) is a detailed description that captures the structure, patterns, and requirements of your data. Think of a spec as a blueprint for your data generation task. DataFramer automatically generates specifications by analyzing your seed data. This cell ensures a specification exists for the dataset by reusing an existing one or generating a new one. When using a databricks/ model, DataFramer automatically retrieves your company’s stored Databricks credentials (configured by your admin in Settings > Keys).

spec_name = f"spec_for_dataset_{dataset_id}"

# --- Check for existing spec ---
specs = client.dataframer.specs.list()

existing_spec = next(
    (s for s in specs if s.name == spec_name),
    None
)

spec_id = None

if existing_spec:
    spec_id = existing_spec.id
    print("Spec already exists — reusing existing spec ✅")
else:
    spec = client.dataframer.specs.create(
        dataset_id=dataset_id,
        name=spec_name,
        spec_generation_model_name="databricks/system.ai.claude-sonnet-5",
        extrapolate_values=True,
        generate_distributions=True,
    )
    spec_id = spec.id
    print(f"Started specification generation:")
    print(f"Spec ID: {spec_id}")

    def spec_not_ready(result):
        return result.status not in ("SUCCEEDED", "FAILED")

    @retry(wait=wait_fixed(5), retry=retry_if_result(spec_not_ready), stop=stop_never)
    def poll_spec_status(client, spec_id):
        return client.dataframer.specs.retrieve(spec_id=spec_id)

    print("Polling for spec status (this may take a minute)...")
    spec_status = poll_spec_status(client, spec_id)

    if spec_status.status == "FAILED":
        raise RuntimeError(spec_status.error or "Unknown error")

    print(f"\nSpec generated successfully! ✅")

print(f"spec_id: {spec_id}")

Review Generated Specification

This cell retrieves the latest version of the generated specification and inspects key properties inferred from the dataset, such as data property variations.

# Get the spec (latest content_yaml is returned directly)
spec = client.dataframer.specs.retrieve(spec_id=spec_id)

# Parse the configuration YAML
config = yaml.safe_load(spec.content_yaml)
spec_data = config.get("spec", config)

print("\nData property variations:")
for prop in spec_data.get("data_property_variations", []):
    print(f"  • {prop['property_name']}: {len(prop['property_values'])} values")

Step 4: Update Specification (Optional)

This cell demonstrates how to programmatically update a given specification. To keep this demo simple, the update is applied only when the specification is newly created (i.e., when the latest version is 1). If the specification has already been updated, this step is skipped. In this step, we take the first property the spec found in your documents that has no conditional distributions, and make its first value appear in 60% of the generated samples. A property you add yourself must fit your documents: one that does not makes every sample fail generation’s consistency check.

# Get the spec with version history
spec = client.dataframer.specs.retrieve(spec_id=spec_id, include_versions=True)

# To keep this demo simple, only update if this is a newly created spec (1 version)
if spec.versions and len(spec.versions) > 1:
    print("ℹ️ Specification has already been updated — skipping this step")
else:
    # Parse the current config
    current_config = yaml.safe_load(spec.content_yaml)
    spec_data = current_config.get('spec', current_config)

    # Pick a property the spec found in your documents. A property with conditional
    # distributions takes its values from those, so choose one without.
    prop = next(
        (p for p in spec_data.get('data_property_variations', [])
         if len(p['property_values']) > 1 and not p.get('conditional_distributions')),
        None
    )

    if prop is None:
        print("ℹ️ No property without conditional distributions — skipping this step")
    else:
        # Make its first value appear in 60% of samples; the others share the rest
        first, *rest = prop['property_values']
        prop['base_distributions'] = {first: 60.0, **{v: round(40 / len(rest), 2) for v in rest}}
        print(f"✓ '{first}' now has a 60% share in property '{prop['property_name']}'")

        # Convert back to YAML
        new_content_yaml = yaml.dump(
            current_config,
            default_flow_style=False,
            sort_keys=False
        )

        # Update the spec (creates a new version automatically)
        updated_spec = client.dataframer.specs.update(
            spec_id=spec_id,
            content_yaml=new_content_yaml
        )

        print("✓ Spec updated successfully")

Step 5: Generate New Samples

Once the spec is generated and finalized after any manual modifications, we will use this spec to generate synthetic data on your Databricks models. Databricks credentials are retrieved automatically from your company’s stored configuration.

# --- Start generation run ---
run = client.dataframer.runs.create(
    spec_id=spec_id,
    generation_model="databricks/system.ai.claude-sonnet-5",
    number_of_samples=3,

    ## Advanced configuration for outline generation
    outline_model="databricks/system.ai.claude-sonnet-5",

    # revision_types=["coherence_flow", "consistency", "distinguishability", "conformance"],
    # filtering_types=["structural", "conformance"],
    # max_revision_cycles=2,
    revision_model="databricks/system.ai.claude-sonnet-5",
)

run_id = run.id

print("Started generation run")
print(f"Run ID: {run_id}")

def run_not_finished(result):
    return result.status not in ("SUCCEEDED", "FAILED")

@retry(wait=wait_fixed(10), retry=retry_if_result(run_not_finished), stop=stop_never)
def poll_run_status(client, run_id):
    return client.dataframer.runs.retrieve(run_id=run_id)

print("Polling for run status (this may take a couple of minutes)...")
run_status = poll_run_status(client, run_id)

if run_status.status == "FAILED":
    raise RuntimeError("Generation failed")

print(f"\nGeneration completed successfully!")
print(f"Run ID: {run_id}")
print(f"Samples completed: {run_status.samples_completed}")

Step 6: Evaluate Generated Samples

While DataFramer evaluates each sample as it is generated, it also supports a post-generation evaluation. This API shows how to evaluate the generated dataset. Read the documentation for more details.

# --- Start evaluation ---
print(f"Creating evaluation for run: {run_id}")

evaluation = client.dataframer.evaluations.create(
    run_id=run_id,
    evaluation_model="databricks/system.ai.claude-sonnet-5"
)

evaluation_id = evaluation.id

print("\nEvaluation created")
print(f"Evaluation ID: {evaluation_id}")
print(f"Created at   : {evaluation.created_at}")

def eval_not_finished(result):
    return result.status not in ("SUCCEEDED", "FAILED")

@retry(wait=wait_fixed(5), retry=retry_if_result(eval_not_finished), stop=stop_never)
def poll_eval_status(client, evaluation_id):
    return client.dataframer.evaluations.retrieve(evaluation_id=evaluation_id)

print("Polling for evaluation status...")
eval_status = poll_eval_status(client, evaluation_id)

if eval_status.status == "FAILED":
    print("\nEvaluation failed. ❌")
    if eval_status.error_message:
        print(f"  Error: {eval_status.error_message}")
else:
    print("\nEvaluation completed successfully! ✅")

Step 7: Download Generated Files

List Generated Files

This API lists all the files that were present in the generated dataset.

# Get generated files for the run
run_details = client.dataframer.runs.retrieve(run_id=run_id)

print("📁 Generated Files:")
print("=" * 80)
print(f"Run ID: {run_id}")
if run_details.generated_files:
    print(f"Total files: {len(run_details.generated_files)}")
    print("=" * 80)

    for i, file in enumerate(run_details.generated_files, 1):
        print(f"\n📄 File {i}:")
        print(f"  Path: {file.path}")
        print(f"  ID: {file.id}")
        print(f"  Size: {file.size_bytes} bytes")
        print(f"  Type: {file.file_type}")
else:
    print("No generated files found")
    print("=" * 80)

Download All Files as ZIP

This API allows you to download all the generated files with metadata as a compressed ZIP file.

print("📥 Downloading generated files with metadata as ZIP...")

def download_not_ready(response):
    return not hasattr(response, 'download_url') or response.download_url is None

@retry(wait=wait_fixed(2), retry=retry_if_result(download_not_ready), stop=stop_never,
       before_sleep=lambda rs: print("  ZIP generation in progress, waiting..."))
def poll_download(client, run_id):
    return client.dataframer.runs.files.download_all(run_id=run_id)

response = poll_download(client, run_id)

# Download the ZIP from the presigned URL
zip_content = requests.get(response.download_url).content
downloaded_zip = BytesIO(zip_content)

print(f"\n✅ Downloaded ZIP file ({response.size_bytes} bytes)")

Load generated files into a Databricks Volume

Since multi-file and multi-folder datasets produce file-based outputs (e.g., PDFs, images), the generated data is written to a Databricks Volume rather than a Delta table. This preserves the original file structure. Multi-file output:

from pydataframer_databricks import DatasetType, FileType

databricks_connector.load_to_volume(
    volume_path="/Volumes/workspace/default/dataframer_output/",
    downloaded_zip=downloaded_zip,
    output_folder="generated_pdf_multifile_samples",
)

Multi-folder output:

from pydataframer_databricks import DatasetType, FileType

databricks_connector.load_to_volume(
    volume_path="/Volumes/workspace/default/dataframer_output/",
    downloaded_zip=downloaded_zip,
    output_folder="generated_pdf_multifolder_samples",
)

Get started

Capture & Correlate

User Journeys & AI

Findings

Human review operations

Judges and Evaluations

Data Generation

Integrations

Programmatic Access

Multi-File & Multi-Folder

Prerequisites

Step 1: Install and Setup SDK

Initialize the DataFramer client and the DatabricksConnector

Step 2: Upload data to DataFramer

Multi-file upload

Multi-folder upload

Retrieve Dataset Details

Step 3: Generate Specification via the analysis API

Review Generated Specification

Step 4: Update Specification (Optional)

Step 5: Generate New Samples

Step 6: Evaluate Generated Samples

Step 7: Download Generated Files

List Generated Files

Download All Files as ZIP

Load generated files into a Databricks Volume

​Prerequisites

​Step 1: Install and Setup SDK

​Initialize the DataFramer client and the DatabricksConnector

​Step 2: Upload data to DataFramer

​Multi-file upload

​Multi-folder upload

​Retrieve Dataset Details

​Step 3: Generate Specification via the analysis API

​Review Generated Specification

​Step 4: Update Specification (Optional)

​Step 5: Generate New Samples

​Step 6: Evaluate Generated Samples

​Step 7: Download Generated Files

​List Generated Files

​Download All Files as ZIP

​Load generated files into a Databricks Volume

Prerequisites

Step 1: Install and Setup SDK

Initialize the DataFramer client and the DatabricksConnector

Step 2: Upload data to DataFramer

Multi-file upload

Multi-folder upload

Retrieve Dataset Details

Step 3: Generate Specification via the analysis API

Review Generated Specification

Step 4: Update Specification (Optional)

Step 5: Generate New Samples

Step 6: Evaluate Generated Samples

Step 7: Download Generated Files

List Generated Files

Download All Files as ZIP

Load generated files into a Databricks Volume