GABRIEL (Generalized Attribute Based Ratings Information Extraction Library)

You can refine how GABRIEL interacts with models using these options:

• additional_instructions: Add clarifications to the prompt (e.g., to mandate that labels must be mutually exclusive).
• template_path: Provide a custom Jinja template path while maintaining built-in retries and checkpoints.
• gabriel.whatever: Use this for fully custom prompts, attachments, or specific routing logic.

Most measurement helpers allow you to specify the data type via the modality parameter. Supported values include:

• text
• entity
• pdf
• image
• audio
• web

Web Search: Set web_search=True to allow GPT to gather context from the web before performing a rating or extraction.

Image Detail: For image understanding, use the image_detail parameter with one of the following values:

• low
• high
• original
• auto

Audio: Audio inputs are routed through Chat Completions. As of July 2026, use the gpt-audio-1.5 model slug; gpt-audio-mini is deprecated.

GABRIEL manages outputs and checkpoints through the save_dir parameter (which supports tilde ~ and environment variables).

• Outputs: Each run writes cleaned outputs and checkpoints raw calls in files like *_raw_responses.csv.
• Resuming: To resume a compatible partial run, set reset_files=False.
• Starting Fresh: If your research specification or prompt changes, use a fresh directory or set reset_files=True to prevent mixing old responses with new ones.
• Auditing: Use gabriel.view to perform quick spot checks on results.

To set up a development environment with linting (ruff, mypy) and run the test suite:

pip install -e .[dev]
pytest

Note: Tests use built-in dummy responses, so an API key is not required for testing.

You can install GABRIEL from PyPI or directly from the GitHub repository. After installation, you can use it in your Python environment by running import gabriel.

Prerequisites

Before running any GABRIEL functions, you must set your OpenAI API key as an environment variable:

export OPENAI_API_KEY="sk-..."

If you are using Google Colab, store the key in Secrets under the name OPENAI_API_KEY and access it via google.colab.userdata.

pip install openai-gabriel

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

The run method returns a pd.DataFrame that includes the original data plus new columns based on the mode used:

• In Static Mode (when categories is provided): A new column is created for each category key provided in the categories dictionary. Each cell in these columns contains a List[str] of snippets that matched that category.
• In Dynamic Mode (when categories is None): A single new column named coded_passages is added. Each cell contains a dictionary where keys are the discovered categories and values are List[str] of snippets.

Example of coded_passages structure in Dynamic Mode:

# Resulting row in df_proc['coded_passages']
{
    "entity_type": ["Apple", "Microsoft"],
    "location": ["Cupertino", "Redmond"]
}

The Deidentifier supports a powerful workflow for refining de-identification without repeated LLM costs:

1. Warm Start: Provide a mapping_column containing dictionaries of { "real_form": { "casted form": "...", "real forms": [...] } }. The task will load the first non-empty mapping found for each group and use it as the starting point for the LLM.
2. Manual Refinement:
   • Run the task once to generate a mapping.
   • Manually edit the resulting mapping column in your CSV/DataFrame to correct any errors.
   • Rerun the task with use_existing_mappings_only=True. This will skip all LLM calls and simply apply your corrected mappings to the text.

GABRIEL provides several core functions for measuring and extracting information from qualitative data:

• gabriel.rate: Assigns 0–100 scores per attribute across various modalities (text, entities, images, audio, or web-sourced context).
• gabriel.rank: Performs pairwise tournaments to surface relative winners with grounded z-scores.
• gabriel.classify: Performs single- or multi-label tagging using label definitions and produces consensus columns.
• gabriel.extract: Extracts typed fields or multiple entities from sources like passages, pages, images, PDFs, or audio items. Note that one source may produce multiple rows.
• gabriel.discover: Contrasts two labeled corpora to identify discriminating features.

GABRIEL includes helpers for cleaning and preparing datasets:

• gabriel.load: Converts folders of media into spreadsheets containing clean IDs and file paths.
• gabriel.merge: Performs fuzzy joins using embeddings and GPT checks.
• gabriel.deduplicate: Produces de-duplicated lists using embeddings and GPT checks.
• gabriel.filter: Screens large candidate lists using natural-language conditions.
• gabriel.deidentify: Replaces PII (Personally Identifiable Information) with realistic stand-ins to protect privacy.

For qualitative research workflows, use the following tools:

• gabriel.codify: Highlights snippets that match specific qualitative codes.
• gabriel.view: A UI-based tool for auditing results, often paired with codify.
• gabriel.compare: Contrasts paired items (such as drafts, policies, or campaigns) to identify concise similarities and differences.
• gabriel.bucket: Proposes bucket names and definitions from a large term universe. This creates a taxonomy that can be used for subsequent classify steps.

To generate new content or run bespoke logic:

• gabriel.ideate and gabriel.seed: Generate diverse candidates for further measurement.
• gabriel.whatever: Runs bespoke prompts with support for custom response_fn or web search. It reuses the library's core infrastructure for retries, logging, and checkpointing.