### Install GABRIEL and Configure API Key

Source: https://context7.com/openai/gabriel/llms.txt

Installation instructions for the GABRIEL library via pip and environment variable setup for the OpenAI API key.

```bash
pip install openai-gabriel

# Or install directly from GitHub
pip install --force-reinstall git+https://github.com/openai/GABRIEL.git@main

# Set your OpenAI API key
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Install development dependencies and run tests

Source: https://github.com/openai/gabriel/blob/main/README.md

Use these commands to set up the development environment and verify the installation with the built-in test suite.

```bash
pip install -e .[dev]
pytest
```

--------------------------------

### Install GABRIEL library

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Install the required package using pip.

```python
%pip install openai-gabriel
```

--------------------------------

### Install GABRIEL library

Source: https://github.com/openai/gabriel/blob/main/README.md

Installation commands for the GABRIEL package via pip.

```bash
pip install openai-gabriel

# or install directly from GitHub
pip install \
  --force-reinstall \
  git+https://github.com/openai/GABRIEL.git@main

# then run import gabriel
```

--------------------------------

### Handle Download Errors

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Example output showing a 404 error when a resource is not found during the download process.

```text
Output:
Error downloading voyager_interstellar_plasma_sounds: 404 Client Error: Not Found for url: https://www.nasa.gov/externalflash/interstellar.mp3
```

--------------------------------

### Display Loaded Audio DataFrame

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Example output showing the structure of the DataFrame after loading audio files.

```text
Output:
                             name  \
0             mercury6_zero_g.mp3   
1          mercury6_god_speed.mp3   
2  emfisis_chorus_radio_waves.mp3   
3             aurora7_liftoff.mp3   
4                sputnik_beep.mp3   

                                            path  
0             /content/audio/mercury6_zero_g.mp3  
1          /content/audio/mercury6_god_speed.mp3  
2  /content/audio/emfisis_chorus_radio_waves.mp3  
3             /content/audio/aurora7_liftoff.mp3  
4                /content/audio/sputnik_beep.mp3  
Saved aggregated file to /content/audio/gabriel_aggregated_content.csv
```

--------------------------------

### Load Data and Run Ranking Pipeline

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Loads the State of the Union addresses dataset, defines attributes for analysis (populism and conservatism), and initiates the ranking process using the gabriel library. Ensure the gabriel library is installed and the model is accessible.

```python
#Load the data and get a sample
from datasets import load_dataset
speeches = load_dataset("jsulz/state-of-the-union-addresses")

elo_data = speeches['train'].to_pandas()

#Define what we want to measure
attributes={'populism': 'the extent to which the text emphasizes populist values',
            'conservatism': 'how politically and socially conservative is the text'}

#Run the call
elo_res = await gabriel.rank(
    df = elo_data.sample(30, random_state=42),
    column_name='speech_html',
    attributes = attributes,
    n_rounds = 3,
    matches_per_round = 6,
    save_dir = 'elo_speeches',
    model = 'gpt-5.4-mini',
)
```

--------------------------------

### Run minimal rating flow

Source: https://github.com/openai/gabriel/blob/main/README.md

Example of using gabriel.rate to score entities against defined attributes.

```python
import os
import pandas as pd

import gabriel

PATH = os.path.expanduser("~/Documents/gabriel_runs")
toy_data = pd.DataFrame(
    {
        "entity": [
            "turkey",
            "pumpkin pie",
            "green bean casserole",
            "cornbread",
        ]
    }
)

attributes = {
    "savory taste": "How savory the dish is",
    "sweet taste": "Dessert-like sweetness",
    "tangy taste": "Notes of tartness or acidity",
}

rate_results = await gabriel.rate(
    toy_data,
    column_name="entity",
    attributes=attributes,
    save_dir=os.path.join(PATH, "toy_rate"),
    model="gpt-5.4-mini",
    n_runs=1,
    modality="entity",
    reset_files=True,
)
rate_results.head()
```

--------------------------------

### Create Toy DataFrame for Manual Labeling

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Generates a toy pandas DataFrame with sample text data. This is useful for providing manual examples to guide the classification model's judgment.

```python
# Create a toy spreadshseet
toy_data = pd.DataFrame({"text": [
    "Following last quarter’s review, I’m confident we can ship the analytics dashboard by Friday with the current headcount.",
    "I’m drowning in tickets; the build keeps failing and it’s wearing me down.",
    "Today’s walk by the bay shook off the fog in my head; I feel ready to try again.",
    "The rollout was mismanaged; we flagged the risk repeatedly and were summarily ignored.",
    "Preliminary analyses suggest the intervention achieved measurable improvements across key outcomes.",
    "My calendar is stacked, sleep is thin, but I think we can thread the needle if we cut scope.",
    "Let’s merge—benchmarks beat baseline and the regressions look contained.",
    "Honestly, I’m lost; nothing I do seems to move the needle and it’s exhausting.",
    "The exhibition balanced restraint with daring; a surprisingly confident curatorial voice."
]})
```

--------------------------------

### Create Toy Data and Define Attributes for Rating

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

This snippet demonstrates how to create a sample Pandas DataFrame for text data and define a dictionary of attributes with their descriptions. These attributes will be used by GABRIEL for rating. Ensure you have pandas installed.

```python
import pandas as pd

# Create a toy spreadshseet. This will work well with text from any language!
toy_data = pd.DataFrame({"text": [
    "Following last quarter’s review, I’m confident we can ship the analytics dashboard by Friday with the current headcount.",
    "I’m drowning in tickets; the build keeps failing and it’s wearing me down.",
    "Today’s walk by the bay shook off the fog in my head; I feel ready to try again.",
    "The rollout was mismanaged; we flagged the risk repeatedly and were summarily ignored.",
    "Preliminary analyses suggest the intervention achieved measurable improvements across key outcomes.",
    "My calendar is stacked, sleep is thin, but I think we can thread the needle if we cut scope.",
    "Let’s merge—benchmarks beat baseline and the regressions look contained.",
    "Honestly, I’m lost; nothing I do seems to move the needle and it’s exhausting.",
    "The exhibition balanced restraint with daring; a surprisingly confident curatorial voice."
]})
# You can load real data using df = pd.read_csv("path_to_your_spreadsheet"). See the 'Loading your data' section for more info

# Define the features we want to measure
attributes = {
    "focus on work life": "How much the text centers on jobs, projects, deadlines, meetings, or professional goals (0 = not about work, 100 = entirely about work).",
    "optimism": "How positive and forward-looking the text feels (near 0 = pessimistic/hopeless, near 100 = highly hopeful and upbeat).",
    "anger": "How much frustration, irritation, or hostility is expressed (near 0 = none, 100 = very angry).",
    "formality": "How formal, structured, and professional the language is (near 0 = very casual/slangy, near 100 = highly formal/academic).",
    "confidence": "How self-assured the speaker sounds about claims or outcomes (near 0 = doubtful/uncertain, near 100 = very certain/assertive).",
    "personal stress": "How strained, overwhelmed, or anxious the speaker sounds (near 0 = calm/relaxed, near 100 = extremely stressed)."
}

additional_instructions = "" #### Any additional instructions you want to pass to the model when rating. For instance examples of how to rate the text

```

--------------------------------

### Install ConvoKit dependency

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Install the required ConvoKit package for processing Reddit data.

```python
%pip install convokit
```

--------------------------------

### Initialize DataFrame for De-identification

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Prepare a pandas DataFrame with a 'text' column containing the data to be de-identified. This setup is required before using de-identification functions.

```python
import pandas as pd

deid_data = pd.DataFrame({
    "text": [
        "Elizabeth Green—known as Liz to most of her colleagues—presented her findings in Manchester on 2 February 2023 before catching the evening train back to York for her birthday dinner.",
        "While reviewing interview transcripts in Bilbao, research assistant John Carter realized that another participant, also named John but surnamed Alvarez, had been mixed into his April 2024 notes.",
        "Dr. Farah El-Hakim flew from Cairo to the equally bustling city of Karachi on 10 May 2025 to compare urban water-usage diaries collected by local volunteers.",
        "Please reach our field office at (415) 555-0771 if your luggage was misplaced during the overnight survey trip to Juneau on 17 December 2022.",
        "Barack Obama stopped by a public-policy round-table at the University of Chicago on 9 March 2024, a session later cited in anthropology student Talia Mendelsohn’s thesis.",
        "After two weeks in the fishing village of Roscoff, Pierre-Louis Martin mailed handwritten questionnaires to participants in the similarly sized town of Dingle, Ireland, on 6 August 2023.",
        "Mikhail “Misha” Ivanov annotated sixteen oral histories in Novosibirsk on 12 January 2022, occasionally initialing pages simply “M. Ivanov” when pressed for time.",
        "Former classmates José Hernandez and José Luis Rey reunited in Córdoba on 21 October 2023, quickly realizing their migration stories had diverged since graduation.",
        "The focus-group transcripts note that Serena Williams—cited as an example of media representation—appeared on screen behind the moderator during the session in Melbourne on 28 January 2024.",
        "On 5 June 2025, research coordinator Chi-Hoon Park emailed the project list at chihoon.park@ricefieldlab.org describing her return to Seoul after a month of fieldwork in Ulaanbaatar and attaching a fifty-page observation log."
    ]
})
```

--------------------------------

### Initializing GABRIEL environment

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Imports necessary libraries for handling data and media files before using GABRIEL functions.

```python
#### THIS CELL JUST LOADS IMAGES FOR A TEST RUN. Normally, you can skip all this and just provide to gabriel.load a path to a folder of images you have saved
import requests
import pandas as pd
from pathlib import Path
import os, mimetypes
import gabriel
```

--------------------------------

### Initialize GABRIEL and set API key

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Import necessary modules and configure the environment variable with your OpenAI API key.

```python
import gabriel
from gabriel.utils.plot_utils import regression_plot, bar_plot, box_plot, line_plot
import os
import pandas as pd

os.environ['OPENAI_API_KEY'] = "<replace this with your API key, inside the quotation marks>"
# the above line should look something like os.environ['OPENAI_API_KEY'] = "sk-proj-a18ma718q..." but with your full API key
```

--------------------------------

### Define Toy Data for Ranking

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Sets up a Pandas DataFrame with sample texts for ranking. Ensure pandas is imported.

```python
import pandas as pd

# Define the sample spreadsheet
toy_data = pd.DataFrame({"text": [
    "While your conclusion is careless, the deployment will likely improve consumer surplus.",
    "R&D intensity rose from 12% to 18% YoY; margins may compress before productivity gains materialize.",
    "That take is clown shoes—learn the basics before posting.",
    "Low-key hyped for on-device models—privacy win without the lag.",
    "@mina you’re right; the vendor ghosted us again—unacceptable.",
    "I concur with @lee: the policy update meaningfully strengthens user control.",
    "Subscription gating for security patches undermines trust.",
    "Empirical evidence suggests platform concentration exacerbates rent extraction absent interoperability mandates.",
    "New chips slap; battery life finally sane.",
    "Your deterministic framing is naïve; nonetheless, the architecture promises substantial welfare gains.",
    "If inference cost drops below $0.001/query, long-tail apps become viable; otherwise, unit economics fail.",
    "@devon is right—bait-and-switch trials are predatory; users deserve defaults that respect consent.",
    "Benchmarks improved 12→19 on MTEB; small but real.",
    "Anyone shouting “AI is over” is farming engagement—spare us.",
    "The deployment evidences credible privacy-by-design, a salutary precedent for the sector.",
    "Love the features, hate the upsells—pick a lane.",
    "Claims of AGI progress conflate scaling curves with capability thresholds; the evidence remains circumstantial.",
    "Good thread, @arya—clear, fair, helpful.",
    "Yes, lock-in is gross, but cross-vendor APIs mean switching costs are falling.",
    "With respect, your argument misrepresents the data and borders on bad faith."
]})

# Define the attributes we want to rate on
attributes = {
    "optimistic about technology": "Positive outlook on technology’s future or impact.",
    "anger": "Expression of frustration or hostility.",
    "formality": "Professional or academic style and structure.",
    "toxicity towards other users": "Insults, belittling, or demeaning remarks aimed at other users or groups.",
    "use of logic": "Explicit reasoning or evidence (numbers, if-then claims, comparisons, citations)."
}

```

--------------------------------

### gabriel.whatever

Source: https://context7.com/openai/gabriel/llms.txt

Runs arbitrary GPT prompts while leveraging GABRIEL's parallelization and checkpointing infrastructure.

```APIDOC
## gabriel.whatever

### Description
Runs arbitrary GPT prompts while leveraging GABRIEL's parallelization and checkpointing infrastructure.

### Parameters
- **df** (DataFrame) - Required - The input DataFrame containing prompts.
- **column_name** (str) - Required - The column name containing the prompt.
- **identifier_column** (str) - Required - Unique identifier column.
- **n_parallels** (int) - Optional - Number of parallel requests.
```

--------------------------------

### Sample sentence chunk

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Extracts a text snippet starting and ending at sentence boundaries with a minimum word count.

```python
def sample_sentence_chunk(raw_html: str, target_words: int = 500) -> str:
    """
    Return a snippet that:
      • starts at a sentence boundary
      • ends at a sentence boundary
      • contains *at least* `target_words` words
    """
    text = strip_tags(raw_html)
    sentences = sent_tokenize(text)

    if not sentences:                       # defensive
        return ""

    word_counts = [len(word_tokenize(s)) for s in sentences]
    total_words = sum(word_counts)

    # If the whole speech is shorter than the budget, just return it.
    if total_words <= target_words:
        return text.strip()

    # Choose a random start sentence such that enough words remain.
    valid_starts = [
        i for i in range(len(sentences))
        if sum(word_counts[i:]) >= target_words
    ]
    start = random.choice(valid_starts)

    # Accumulate sentences until the budget is met or exceeded.
    words_so_far, end = 0, start
    while words_so_far < target_words and end < len(sentences):
        words_so_far += word_counts[end]
        end += 1

    snippet = " ".join(sentences[start:end])
    return snippet.strip()
```

--------------------------------

### Run custom prompts with gabriel.whatever

Source: https://context7.com/openai/gabriel/llms.txt

Executes arbitrary GPT prompts using GABRIEL's infrastructure. Useful for tasks requiring high-volume parallel processing.

```python
import gabriel
import pandas as pd

# Custom prompts for any task
prompts_df = pd.DataFrame({
    "prompt": [
        "Translate to French: Hello, how are you today?",
        "Translate to French: The weather is beautiful.",
        "Translate to French: Thank you for your help.",
    ],
    "id": ["p1", "p2", "p3"]
})

results = await gabriel.whatever(
    df=prompts_df,
    column_name="prompt",
    identifier_column="id",
    save_dir="~/Documents/gabriel_runs/translations",
    model="gpt-4o-mini",
    n_parallels=650,
    reset_files=True,
)

print(results[["id", "Response"]])
```

--------------------------------

### Initialize and execute a survey with Gabriel

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Define a population description and a list of questions, then pass them to gabriel.poll to generate personas and collect survey results.

```python
population_description = """
Adults in the United States, sampled to be broadly representative on age,
gender, race/ethnicity, region, education, and party identification.
"""

questions = [
    "Overall, do you approve or disapprove of expanding Medicaid coverage?",
    "How strongly do you support or oppose it? Rate on a scale of 1 to 7, with 1 being strongly opposed and 7 being strongly supportive.",
    "What is the main reason for your view? Answer in one short sentence.",
    "Do you culturally identify more with your town, state, or country?",
    "On a scale of 1 to 10, how important is your career to you?",
    "How many kids do you plan on having in total?",
    "In one sentence, explain your rationale behind that number of kids.",
]

survey_results = await gabriel.poll(
    population_description = population_description,  # can also pass in a df with an existing sample of demographic characteristics or personas
    questions = questions,  # if no questions, you get the generated personas alone
    save_dir = "toy_poll",
    model = "gpt-5.4",
    reasoning_effort = "medium",
    num_personas = 200,
    n_questions_per_run = 10,
    batch_frac = 1.00,      # set lower to more diligently perform seeding
    reset_files = False,
)
```

--------------------------------

### Log Parallelization and Cost Metrics

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Logs initial parallelization settings, dynamic timeout calculations, and final cost metrics for batch processing.

```text
[parallelization] 2025-10-20 21:56:03 | Initial parallelization settings: cap=750, active=0, inflight=0, queue=1, processed=0/1, rate_limit_errors=0
[dynamic timeout] Initialized timeout to 37.8s (p90=16.8s, factor=2.25).
Actual total cost: $0.0022; average per row: $0.0022; average per 1000 rows: $2.2279
[Merge] Attempt 0: 10 matches this round, 10 total, 0 remaining
```

--------------------------------

### Load News Headlines Dataset

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Loads a sample dataset of news headlines from the 'wangrongsheng/ag_news' dataset and samples 30 headlines. This step prepares the data for classification.

```python
from datasets import load_dataset
news = load_dataset("wangrongsheng/ag_news")
news_headlines = news['train'].to_pandas().sample(30, random_state = 42)
```

--------------------------------

### Rate Entities with Gabriel

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Use this snippet to rate entities by setting modality to 'entity'. This leverages GPT's internal knowledge and web search capacity, bypassing the need for text data. Ensure you have the 'gabriel' library installed and imported.

```python
import pandas as pd

toy_data = pd.DataFrame({"entity": [
    "turkey",
    "pumpkin pie",
    "pecan pie",
    "green bean casserole",
    "mashed potatoes",
    "cornbread",
    "paneer makhani",
]})

attributes = {
    "savory taste": "", 
    "sweet taste": "",  
    "bitter taste": "", 
    "salty taste": "",  
    "sour taste": "",
    "cornbready taste": "",
}

results = await gabriel.rate(
    toy_data,
    column_name = "entity",          
    attributes = attributes,         
    save_dir = "entity_rate",
    model = "gpt-5.4-mini",            
    n_runs = 3,
    modality = "entity",
    reset_files = False,
)
```

--------------------------------

### View audio samples

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Displays audio files and their attribute ratings in a visual interface.

```python
gabriel.view(df = audio_classes.sample(10), column_name = "path", attributes = attributes, header_columns = ["name"])
```

--------------------------------

### View and listen to audio samples

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Provides an interface to listen to audio files and view their associated labels.

```python
# you can use gabriel.view to hear sample audio files and see their labels
gabriel.view(df = audio_classes.sample(10), column_name = "path", attributes = labels, header_columns = ["name"])
```

--------------------------------

### Execute custom prompts with backend management

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Run arbitrary prompts through the Gabriel backend to benefit from built-in parallelization, rate limiting, and checkpointing.

```python
#The set of prompts you want to run
sample_prompts = [
    'Define artificial intelligence.',
    'What are neural networks used for?',
    'Explain the Turing test.',
    'Describe the concept of machine learning.',
    'List applications of computer vision.'
]

#Running the pipeline
custom_results = await gabriel.whatever(
    prompts = sample_prompts,
    identifiers = None, # if you have custom identifiers for each prompt, provide them here as a list
    save_dir = 'toy_custom_prompts',
    model = 'gpt-5.4-mini',
    reset_files = False,
)
```

```python
# you can also pass a dataframe of prompts, with the prompts in a column like 'prompt_text'

# make a DataFrame
sample_df = pd.DataFrame({
    "prompt_text": [
        "Define artificial intelligence.",
        "What are neural networks used for?",
        "Explain the Turing test.",
        "Describe the concept of machine learning.",
        "List applications of computer vision."
    ]
})
```

--------------------------------

### Prepare Classification Dataset

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Load and sample a news dataset for classification tasks.

```python
from datasets import load_dataset
news = load_dataset("wangrongsheng/ag_news")
news_headlines = news['train'].to_pandas().sample(30, random_state = 42)
news_headlines.head()

labels = {'world':'Headline primarily a politics / world headline',
          'sports':'The article from the headline is about sports',
          'sci/tech':'The headline is for an article about science or technology',
          'business':'The article is about business',
          'media industry': 'Headline focuses on the news or media business in particular'}
```

--------------------------------

### Initialize Requests Session

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Sets up a requests session with a custom User-Agent for making HTTP requests. This is important for identifying your application to the server.

```python
session = requests.Session()
session.headers.update({
    "User-Agent": "Mozilla/5.0 (compatible; ImageFetcher/1.0; +https://example.com)"
})
```

--------------------------------

### Helper Tools Overview

Source: https://github.com/openai/gabriel/blob/main/README.md

Summary of available helper functions for qualitative coding, data preparation, and analysis.

```APIDOC
## Helper Tools

- **gabriel.codify**: Highlights snippets in text matching qualitative codes.
- **gabriel.compare**: Identifies similarities/differences between paired items.
- **gabriel.bucket**: Builds taxonomies from terms into cluster labels.
- **gabriel.seed**: Enforces representative distribution/diversity of seeds.
- **gabriel.poll**: Seeds personas, expands into biographies, and surveys them.
- **gabriel.ideate**: Generates and filters novel scientific theories.
- **gabriel.debias**: Post-processes measurements to remove inference bias.
- **gabriel.load**: Prepares media files into a spreadsheet for GABRIEL.
- **gabriel.view**: UI for viewing sample texts with ratings/coding.
- **gabriel.paraphrase**: Rewrites texts consistently per instructions.
- **gabriel.whatever**: Executes custom GPT prompts with parallelization/checkpointing.
```

--------------------------------

### Configure OpenAI API Key

Source: https://github.com/openai/gabriel/blob/main/README.md

Set the required environment variable for API authentication.

```bash
export OPENAI_API_KEY="sk-..."
# or os.environ['OPENAI_API_KEY'] = "sk-..." inside a Jupyter notebook
```

--------------------------------

### Sample audio rankings

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Retrieves a sample of the ranked audio data.

```python
audio_rankings.sample(10)
```

--------------------------------

### Build taxonomies with gabriel.bucket

Source: https://context7.com/openai/gabriel/llms.txt

Clusters items into emergent categories to build taxonomies. The bucket_count parameter determines the number of resulting categories.

```python
import gabriel
import pandas as pd

# Unstructured list of items to categorize
items = pd.DataFrame({
    "item": [
        "iPhone", "Galaxy S24", "MacBook Pro", "ThinkPad", "iPad",
        "AirPods", "Bose Headphones", "Apple Watch", "Fitbit",
        "PlayStation 5", "Xbox Series X", "Nintendo Switch",
    ]
})

buckets = await gabriel.bucket(
    items,
    column_name="item",
    save_dir="~/Documents/gabriel_runs/product_taxonomy",
    bucket_count=5,
    model="gpt-4o-mini",
    reset_files=True,
)

print(buckets[["bucket_name", "bucket_definition"]])
```

--------------------------------

### Execute Paraphrase Pipeline

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Apply instructions to a dataset sample using the gabriel.paraphrase function.

```python
instructions = """
Summarize the speech into a short two sentence easy to read summary followed by a limmerick which captures the core content of the speech.
Focus only on domestic policy, include nothing on foreign affairs in your output.
"""

summaries = await gabriel.paraphrase(
    df = ds.sample(20, random_state=42),  # a sample of 15 SotUs
    column_name = "speech_html",  # name of column with content to paraphrase
    instructions = instructions,  # what you want done with each datapoint
    save_dir = "toy_paraphrase",  # directory to save results, use a Google Drive folder (e.g. "/content/drive/folder") for permanent storage (see 'Loading your data' section)
    model = "gpt-5.4-mini",       # GPT model used for ratings
    modality = "text",            # input modality can also be "entity" (for terms like 'apple pie', not full texts), "web" (see web section), "pdf", "image", or "audio" (see multimodal section)
    n_rounds = 1,       # if >1, the method with loop between rewriting, classifying whether the rewrites followed the instructions, and rewriting again for those that failed
    n_runs = 1,         # number of rewrites per datapoint
    n_parallels = 650,  # reduce if getting errors
    reset_files = False,
)
```

--------------------------------

### Call gabriel.whatever with web_search enabled

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Use this snippet to call the gabriel.whatever function with web search enabled. Configure parameters like model, save directory, and web search filters for targeted results. Smaller models are cheaper to use.

```python
county_results = await gabriel.whatever(
    df = prompt_df.sample(10, random_state = 42),
    save_dir = "toy_web",               # web runs are relatively expensive, so ensure you save to Drive or locally
    column_name = "prompt",             # column containing the prompt text
    identifier_column = "identifier",     # unique identifier for each prompt
    file_name = "regional_responses.csv",
    model = "gpt-5.4",                  # smaller models are cheaper
    web_search = True,
    web_search_filters = {"country": "country", "region": "region"},  # optional per-prompt filters; values are columns in the df
    n_parallels = 650,
    search_context_size = "medium",     # controls how much info examined from web; more is best but pricier
    reasoning_effort = "medium",
    use_dummy = False,
    reset_files = False,
)
```

```python
county_results
```

--------------------------------

### Sample Ranking Results

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Samples the results obtained from the gabriel ranking pipeline to inspect a subset of the generated rankings.

```python
elo_res.sample(10)
```

--------------------------------

### Generate Regional Analysis Prompts

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Prepares a DataFrame of prompts by rendering a Jinja2 template with regional and topic-specific instructions.

```python
# Load counties and duplicate location columns
counties_df = pd.read_excel("/content/us_counties_fips.xlsx")
counties_df["region"] = counties_df["County"].astype(str)  # region search hint
counties_df["country"] = "US"                              # country search hint

# define topic and additional instructions
topics = ["local public school us history class curricula"]

additional_instructions = """
Focus on US history classes and curricula, not on other classes nor on world history.
Investigate primary sources like the school websites, reading any syllabi, course descriptions, course materials, and other materials specific to school American history classes in the county.
Consider history classes from elementary, middle, and high school.
Get very specific on what is being taught. Be comprehensive and exhaustive on all primary source evidence you find about the curricula, documenting all specific relevant details you find.
Be sure to include highly detailed accounts of what all is taught in each of a variety of elementary, middle, and high school American history classes in the county, throughout a full school year/curriculum, to the extent that you can find.
Search until you find solid information; dig into any files and documents you can find.
It is crucial that not just broad strokes of topics taught are described, but detailed accounts of how much focus is placed on each topic/period/event in American history, and how things are portrayed and characterized.
You should include how the classes cover aspects of American history, and where they focus their attention.
Aim to characterize the discussion of different topics/periods/events in the classes (what is the nature of 'US history' in the classes?), and include copious direct quotes and paraphrases of the primary sources you find.
Don't stop looking until you find solid and specific relevant information. Use latest info when available, but if not, explore older sources thoroughly using methods to surface old records (Wayback etc) until you find solid information. Aggressively search for old records.
Do what you have to to render and read any documents you find; get creative if needed.
Focus first on all the details/direct quotes/paraphrases you can find, and then go back and summarize the big picture and note any gaps in your knowledge.
Aim to include direct snippets from any sources that capture the nature of the classes and the curricula, whether they are syllabi, course descriptions, course materials, board meetings, parent comments on social media, etc. Search far and wide from many sources.
Do not stop until you find solid and specific relevant information, from past or present local curricula.
"""

# here we use our prompt template for regional reports - you can use your own, or just directly feed in the prompts
template = gabriel.core.PromptTemplate.from_package("regional_analysis_prompt.jinja2")

# Build a DataFrame of prompts with identifiers and location columns
prompt_rows = []
for county in counties_df["County"].astype(str).dropna().unique():
    for topic in topics:
        prompt_text = template.render(
            region = county,
            topic = topic,
            additional_instructions = additional_instructions
        )
        prompt_rows.append({
            "prompt": prompt_text,
            "identifier": f"{county}|{topic}",
            "region": county,
            "country": "US"
        })
prompt_df = pd.DataFrame(prompt_rows)
```

--------------------------------

### Visualize Image Samples

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Displays a sample of images from a dataframe with specified attributes and headers.

```python
gabriel.view(df = image_classes.sample(10), column_name = "path", attributes = labels, header_columns = ["name"])
```

```python
# you can use gabriel.view to view sample images and their attribute ratings
gabriel.view(df = image_classes.sample(10), column_name = "path", attributes = attributes, header_columns = ["name"])
```

--------------------------------

### Load Dataset for Paraphrasing

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Prepare a dataset for processing by loading it into a pandas DataFrame.

```python
# we can use the same SotU dataset as before to test paraphrase on
from datasets import load_dataset
speeches = load_dataset("jsulz/state-of-the-union-addresses")
ds = speeches['train'].to_pandas()
```

--------------------------------

### Define toy classification data and labels

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Creates a sample DataFrame and defines a dictionary of labels with descriptions for classification tasks.

```python
### What we're doing here: we are creating a small toy spreadsheet, then passing it through the model to classify different features of each text.


# Part A. Create a dataframe. This is just like your own data, this line just creates a spreadsheet we can use to run through the package.
# this will work well with text from any language!
toy_data = pd.DataFrame({"text": [
    "I heard that the new president instituted a law on gun control.",
    "My dog decided to eat food at 3am.",
    "Congress passes amended budget for 2026",
    "Why are you so late for class today? Did your dog eat your homework?",
    "Local activists rally outside city hall demanding climate reform.",
    "Scientists discover new species of frog in the Amazon rainforest.",
    "Breaking: Supreme Court rules on landmark case affecting digital privacy.",
    "I just finished reading a book that completely changed how I think about economics."
]})
# You can load real data using df = pd.read_csv("path_to_your_spreadsheet"). See the 'Loading your data' section for more info

# Part B. Define the classes we want to assess
labels = {
    "discusses politics": "The text makes reference to political figures, institutions, or issues.",
    "news headline": "The text is written in the style of a journalistic news headline.",
    "discusses animals": "The text includes mention of animals, whether real or metaphorical.",
    "first person perspective": "The text is written from a personal point of view.",
    "focus is on gun control": "The text’s primary subject is gun control, firearm regulations, or related debates."
}
```

--------------------------------

### Bucket data using Gabriel

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Categorize a list of items into buckets using a specified model and configuration.

```python
random_people = [
    "Claude Monet", "Elon Musk", "Frida Kahlo", "Ulysses S. Grant", "Beyoncé", "Amelia Earhart", "Richard Feynman", "Warren Buffett", "Nelson Mandela", "Roger Federer",
    "Rosalind Franklin", "Michael Jordan", "Oprah Winfrey", "Plato", "Shakira", "Jensen Huang", "Jane Goodall", "Joan of Arc", "Salvador Dalí", "Angela Merkel",
    "Leonardo da Vinci", "Sun Yat-sen", "Cristiano Ronaldo", "Florence Nightingale", "Jacinda Ardern", "Albert Einstein", "Mark Zuckerberg", "Stephen Curry", "Ruth Bader Ginsburg",
    "David Attenborough", "Isaac Newton", "Noam Chomsky", "Greta Thunberg", "Simone Biles", "Alan Turing", "Billie Eilish", "George Washington", "Pablo Picasso", "Meryl Streep", "Indra Nooyi",
    "Niels Bohr", "Toni Morrison", "Dwayne Johnson", "George S. Patton", "Rihanna", "Malala Yousafzai", "ZENDAYA", "Taylor Swift", "Lin-Manuel Miranda", "Demis Hassabis",
    "Jonas Salk", "Kobe Bryant", "Mary Barra", "Jennifer Lawrence", "Claude Shannon", "Satya Nadella", "Benedict Cumberbatch", "Emma Watson", "Sun Tzu", "Serena Williams",
    "Emily Dickinson", "Quentin Tarantino", "Jennifer Doudna", "Oprah Winfrey", "Mahatma Gandhi", "Stephen Hawking", "Kamala Harris", "Winston Churchill", "Usain Bolt", "Hedy Lamarr",
    "Yao Ming", "Greta Gerwig", "George S. Patton", "Virat Kohli", "Anne Hathaway", "Barack Obama", "Confucius", "Andy Warhol", "Meryl Streep", "Sheryl Sandberg"
]

random_people_df = pd.DataFrame({"people": random_people})

people_buckets = await gabriel.bucket(
    df = random_people_df,
    column_name = "people",
    save_dir = "toy_bucket",
    model = "gpt-5.4-mini",
    additional_instructions = "",  # you can guide the detail of bucket terms here
    bucket_count = 6,              # set this to the number of buckets you want
    reset_files = False,
)
```

```python
people_buckets
```

--------------------------------

### Sample generated entities

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Displays a random sample of the generated entity dataset.

```python
people.sample(10)
```

--------------------------------

### Sample Classified Articles

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

This snippet shows how to sample the results of the article classification. It requires the 'classifications' object to be previously defined.

```python
classifications.sample(10, random_state=42)
```

--------------------------------

### Sample survey results

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Display a subset of the generated survey data.

```python
survey_results.sample(5)
```

--------------------------------

### Execute ELO Ranking

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Configures and runs the ranking process on a dataset. Ensure the input data and attributes are properly defined before execution.

```python
results = await gabriel.rank(
    toy_data,
    column_name = "text",          # name of column with posts to rank
    attributes = attributes,       # attributes to rank by
    n_rounds = 3,                  # number of ELO rounds (more = more pairwise judgments)
    matches_per_round = 5,         # 5 * 3 means 15 total matchups for every entry
    save_dir = "toy_rank",         # directory to save results
    model = "gpt-5.4-mini",        # model used for pairwise comparisons
    modality = "text",             # input modality can also be "entity" (for terms like 'apple pie', not full texts), "pdf", "image", or "audio" (see multimodal section)
    n_attributes_per_run = None,   # default: all attributes in one prompt; set 12 or lower to split many attributes across prompts
    n_parallels = 650,             # max parallel threads (reduce if many errors, increase for higher speed)
    reset_files = False,  # rerunning the cell loads from save / picks up from checkpoint
    recursive = False,    # set to True to recursively cut low performers on a single attribute and rerank until revealing the cream of the crop (isolates and orders the true top performers)
)
```

```python
results
```

--------------------------------

### Load Audio Files into DataFrame

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Uses the Gabriel library to load local audio files into a DataFrame, requiring the modality parameter to be set to 'audio'.

```python
audio_df = gabriel.load("/content/audio", modality = "audio", reset_files = True)  # be sure to set modality = "audio" in later functions too!
```

--------------------------------

### Load data with gabriel.load

Source: https://context7.com/openai/gabriel/llms.txt

Aggregates files from a directory into a DataFrame. Supports multiple modalities including text, images, audio, and PDFs.

```python
import gabriel

# Load all text files from a directory
text_df = gabriel.load(
    folder_path="~/Documents/interview_transcripts",
    modality="text",  # or "image", "audio", "pdf"
    save_dir="~/Documents/gabriel_runs/loaded_data",
    reset_files=True,
)

print(text_df[["name", "path", "text"]].head())
```

--------------------------------

### Sample Image Ratings

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Retrieves a sample of the rated image data.

```python
image_ratings.sample(10)
```

--------------------------------

### Download and Process Audio Files

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Downloads a set of audio files from provided URLs and saves them to a local directory, handling content-type validation and file extension guessing.

```python
import requests, os, mimetypes
from pathlib import Path
import pandas as pd

SESSION = requests.Session()
SESSION.headers.update({"User-Agent": "Mozilla/5.0 (compatible/AudioFetcher/1.0)"})

URLS = {
    "apollo11_small_step": "https://www.nasa.gov/wp-content/uploads/2015/01/590331main_ringtone_smallStep.mp3",
    "apollo13_houston_problem": "https://www.nasa.gov/wp-content/uploads/2015/01/574928main_houston_problem.mp3",
    "apollo11_eagle_has_landed": "https://www.nasa.gov/wp-content/uploads/2015/01/569462main_eagle_has_landed.mp3",
    "apollo11_liftoff_countdown": "https://www.nasa.gov/wp-content/uploads/2015/01/590320main_ringtone_apollo11_countdown.mp3",
    "apollo8_merry_christmas": "https://www.nasa.gov/wp-content/uploads/2015/01/581549main_Apollo-8_Merry-Christmas.mp3",
    "mercury6_zero_g": "https://www.nasa.gov/wp-content/uploads/2015/01/582367main_Mercury-6_Zero-G.mp3",
    "mercury6_god_speed": "https://www.nasa.gov/wp-content/uploads/2015/01/582368main_Mercury-6_God-Speed.mp3",
    "aurora7_liftoff": "https://www.nasa.gov/wp-content/uploads/2015/01/582371main_Aurora-7_Liftoff.mp3",
    "sputnik_beep": "https://www.nasa.gov/wp-content/uploads/2015/01/578626main_sputnik-beep.mp3",
    "emfisis_chorus_radio_waves": "https://www.nasa.gov/wp-content/uploads/2015/01/693857main_emfisis_chorus_1.mp3",
    "voyager_interstellar_plasma_sounds": "https://www.nasa.gov/externalflash/interstellar.mp3",
    "voyager_jupiter_lightning": "https://www.nasa.gov/wp-content/uploads/2015/01/603921main_voyager_jupiter_lightning.mp3",
    "stardust_tempel1": "https://www.nasa.gov/wp-content/uploads/2015/01/598980main_stardust_tempel1.mp3",
    "jfk_we_choose_the_moon": "https://www.nasa.gov/wp-content/uploads/2015/01/586447main_JFKwechoosemoonspeech.mp3",
    "jfk_return_him_safely": "https://www.nasa.gov/wp-content/uploads/2015/01/591240main_JFKmoonspeech.mp3",
}

def download_audio(name, url, dest_dir="audio"):
    dest = Path(dest_dir)
    dest.mkdir(parents=True, exist_ok=True)
    with SESSION.get(url, stream=True, timeout=30) as r:
        r.raise_for_status()
        ctype = r.headers.get("Content-Type", "")
        if not (ctype.startswith("audio/") or url.lower().endswith((".mp3", ".wav", ".ogg", ".m4a"))):
            raise ValueError(f"{name}: URL did not return an audio file (Content-Type={ctype or 'unknown'}).")
        ext = mimetypes.guess_extension(ctype.split(";")[0]) or os.path.splitext(url)[1] or ".mp3"
        path = dest / f"{name}{ext}"
        with open(path, "wb") as f:
            for chunk in r.iter_content(8192):
                if chunk:
                    f.write(chunk)
    return str(path)

# Download & build DataFrame of local files
audio_paths = []
audio_names = []
for name, url in URLS.items():
    try:
        p = download_audio(name, url)
        audio_paths.append(p); audio_names.append(name)
    except Exception as e:
        print(f"Error downloading {name}: {e}")
```

--------------------------------

### Sample audio ratings

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Displays a sample of the generated audio ratings.

```python
audio_ratings.sample(10)
```

--------------------------------

### Load Dataset for Passage Coding

Source: https://github.com/openai/gabriel/blob/main/gabriel_tutorial_notebook.ipynb

Import the gabriel library and load a dataset using the datasets library for passage coding tasks. This sets up the data for thematic analysis.

```python
import gabriel
from datasets import load_dataset

speeches = load_dataset("jsulz/state-of-the-union-addresses")
sotu_df = speeches['train'].to_pandas()
```