Skip to main content
This page provides documentation for Expected Parrot Domain-Specific Language (EDSL), an open-source Python package for performing research with AI agents and language models, and Coop, a platform for creating, storing and sharing AI research projects, and validating LLM results with human respondents.
  • EDSL is available to download from PyPI (run pip install edsl). The source code is available at GitHub.
  • Create an account to post and share content, run surveys with LLMs and humans, and store results at the Expected Parrot server. Learn more about how it works and start exploring.

​
Key features

Simplified access to hundreds of models
  • A single API key lets you conduct research with many popular models at once. Learn more.
Collaboration features
  • Use Coop to create, store and share your research projects seamlessly.
Data integrations
  • Easily import, analyze and extend many types of data to use with your research. Learn more.
Hybrid human-AI surveys
  • Collect and combine responses from humans and AI. Learn more.
Built-in analysis tools
  • Readily visualize, analyze and compare responses. Learn more.

​
Use cases

Our tools simplify survey creation, experiment execution and response analysis. Common use cases include: Data labeling
  • Use AI to answer qualitative and quantitative questions about your data, and extract insights. See examples.
Market research
  • Gather insights on consumer preferences, behaviors and trends. Simulate customer personas with AI agents and analyze their responses. See examples.
User experience research
  • Assess user satisfaction, usability and engagement. Use AI agents to simulate user profiles and analyze their feedback on products or services. See examples.
Integrate human and AI data
  • Combine human responses with AI-generated responses to create richer datasets. See examples.
Analyze survey data
  • Analyze survey data with built-in methods. Simulate follow-up interviews with respondents. See examples.
Compare model performance
  • Compare the performance of different language models on the same task. See examples.
Social science research
  • Explore hypotheses, gather qualitative or quantitative data and generate new data using AI.
For more on EDSL’s key features and use cases, visit the Overview section.

​
Getting started

To use EDSL, you need to install the package and choose how to access language models. Please see the links in the steps below for more details:
1

Install EDSL

Run the following command to install the package:
! uv pip install edsl -q
See Installation instructions for more details.
2

Create a Coop account

Create an account](https://www.expectedparrot.com/login) to access the Expected Parrot server, free storage and special features and collaboration tools. You can also log into Expected Parrot and import dependencies by running:
from edsl import Login
login()
3

Manage API keys for language models

Your account comes with a key that allows you to run surveys with all available models. You can also provide and share your own keys from service providers. See instructions on Managing Keys for details and options.
4

Run a survey

Read the Starter Tutorial and download a notebook to create a survey and run it. See examples for many use cases and tips on using EDSL effectively in the documentation.
5

Validate with real respondents

Choose when to add a human-in-the-loop by automatically launching a web-based survey to share with real respondents. Learn about collecting responses in the Survey Builder and Humanize sections.
Join our Discord to ask questions and chat with other users!

​
Researchers

Are you using EDSL for a research project? Send an email to info@expectedparrot.com and we’ll give you credits to run your project!

​
Introduction

Overview

An overview of the purpose, concepts and goals of the EDSL package.

Whitepaper

A whitepaper about the EDSL package (in progress).

Citation

How to cite the package in your work.

Papers & Citations

Research papers and articles that use or cite EDSL.

Teaching guide

A guide for teaching EDSL and using it in the classroom.

Starter Tutorial

A step-by-step tutorial for getting started with EDSL.

​
Core Concepts

Questions

Learn about different question types and applications.

Scenarios

Explore how questions can be dynamically parameterized for tasks like data labeling.

Surveys

Construct surveys with rules and conditions.

Agents

Design AI agents with relevant traits to respond to surveys.

Language Models

Select language models to generate results.

​
Getting Data

Firecrawl

Web scraping and data extraction integration for EDSL scenarios.

​
Working with Results

Results

Access built-in methods for analyzing survey results as datasets.

Caching LLM Calls

Learn about caching and sharing results.

Estimating & Tracking Costs

See how to estimate costs for running surveys and track actual costs for each question and model that you use.

Exceptions & Debugging

Identify and handle exceptions in running surveys.

Token usage

Monitor token limits and usage for language models.

Dataset

Work with tabular data using the versatile Dataset class.

​
Validating with Humans

Humanize

Generate web-based surveys and collect responses from human respondents.

Prolific studies

Launch surveys as studies on Prolific, a platform for recruiting human participants for research studies.

​
No-code Apps

Survey Builder

A user-friendly no-code interface for creating surveys and gathering responses from humans and AI agents.

​
Coop

Coop is a platform for creating, storing and sharing AI-based research. It is fully integrated with EDSL and provides access to special features for working with AI agents and language models, free storage and collaboration tools, including:
  • Remote Inference: Access all available language models and run surveys at the Expected Parrot server.
  • Remote Caching: Automatically store results and API calls at the Expected Parrot server.
  • Notebooks & Colab Notebooks: Easily post and share .ipynb and .py files to the Coop and access with Colab.
  • File Store: Store and share data files for use in EDSL projects.
Learn more about how it works and purchasing credits.

​
Importing Surveys

  • Automatically import other survey data into EDSL to:
    • Clean and analyze your data
    • Create AI agents and conduct follow-on interviews
    • Extend results with new questions
    • Store and share data at the Coop

​
How-to Guides & Notebooks

Examples of special methods and use cases for EDSL, including:
  • Data labeling
  • Data cleaning
  • Analyzing survey results
  • Adding data to surveys from CSVs, PDFs, images and other sources
  • Conducting agent conversations
  • Converting surveys into EDSL
  • Cognitive testing
  • Validating LLM answers with humans
  • Research methods
⌘I